@chipi-stack/core

Core primitives for Chipi Pay SDK: transaction building, token math, signer adapters, and fee estimation.

Install

npm install @chipi-stack/core

Modules

TxBuilder

Build Starknet multicall transactions with a fluent API:

import { TxBuilder } from "@chipi-stack/core";

const tx = TxBuilder.new()
  .transfer({ token: "USDC", to: "0x...", amount: "10.00" })
  .approve({ token: "USDC", spender: "0x...", amount: "50.00" })
  .build();

TokenRegistry

Look up token metadata (address, decimals) by symbol and network:

import { TokenRegistry } from "@chipi-stack/core";

const usdc = TokenRegistry.get("USDC", "mainnet");
// { address: "0x033068...", decimals: 6, symbol: "USDC" }

Amount

Safe token amount math with decimal precision:

import { Amount } from "@chipi-stack/core";

const amt = Amount.fromHuman("10.50", 6); // 10.5 USDC
amt.toRaw();   // 10500000n
amt.toHuman(); // "10.50"

Signers

Unified SignerAdapter interface with three implementations:

import { DirectSigner, ExternalSigner, PasskeySigner } from "@chipi-stack/core";

// Local key (testing only)
const direct = new DirectSigner("0x...");

// External provider (Privy, Cartridge, etc.)
const external = new ExternalSigner({
  getPublicKey: () => provider.getPublicKey(),
  sign: (hash) => provider.sign(hash),
  getAccountAddress: () => provider.getAddress(),
});

// Passkey-based signer
const passkey = new PasskeySigner({
  authenticateFn: (challenge) => passkeyAuth(challenge),
  publicKey: "0x...",
  accountAddress: "0x...",
});

Fee Estimation

Estimate Starknet transaction fees before execution:

import { estimateFee, preflight } from "@chipi-stack/core";

const fee = await estimateFee(calls, account);
const check = await preflight(calls, account); // fee + balance check

What you can ship

• Gasless wallets for gaming and loyalty apps — abstract away gas fees so users never touch crypto
• Invisible signers for AI agents — let autonomous agents sign and submit transactions
• Multi-call DeFi transactions — batch swaps, approvals, and transfers into a single execution
• Custom payment flows for remittance platforms — build cross-border payment rails on Starknet

Have an idea? Tell us what you want to build

Documentation

Full docs at docs.chipipay.com

License

MIT

Private balances (STRK20 privacy pool)

Mainnet-proven shield/unshield engine (Chipi's "Modo privado"). React apps should use the hooks in @chipi-stack/chipi-react / @chipi-stack/nextjs; this is the headless layer they wrap.

import {
  ChipiProofProvider,
  derivePoolKeypair,
  deriveCompanionKeypair,
  deriveCompanionAddress,
  requestGasFunding,
  waitForFunding,
  execShield,
  GAS_FUND_STRK,
} from "@chipi-stack/core";
import { RpcProvider } from "starknet";

// Keys derive CLIENT-SIDE from the user's anchor — never persist them.
// NOTE the trust model: delegated proving sends the pool key to the prover
// per operation (privacy vs the PUBLIC, not the proving operator) — docs.
const pool = await derivePoolKeypair({ anchorSecret, seedDomainTag: wallet.address });
const companion = await deriveCompanionKeypair(anchorSecret);
const companionAddress = deriveCompanionAddress({
  publicKey: companion.publicKey,
  classHash: COMPANION_CLASS_HASH,
});

const provider = new RpcProvider({ nodeUrl: "https://api.cartridge.gg/x/starknet/mainnet" });
await requestGasFunding(companionAddress, {
  baseUrl: "https://api.chipipay.com/v1",
  apiKey: apiPublicKey,
  getBearerToken: () => getToken(),
});
await waitForFunding(provider, companionAddress, { strk: GAS_FUND_STRK });
const result = await execShield(
  {
    provider,
    chainId: "0x534e5f4d41494e",
    companionAddress,
    companionKey: companion.privateKey,
    classHash: COMPANION_CLASS_HASH,
    poolKey: BigInt(pool.privateKey),
    provingProvider: new ChipiProofProvider({
      baseUrl: "https://api.chipipay.com/v1",
      apiKey: apiPublicKey,
      getBearerToken: () => getToken(),
      chainId: "0x534e5f4d41494e",
    }),
  },
  USDC_ADDRESS,
  1_000_000n,
);
console.log(result.transactionHash); // receipt + pool event already verified

The bundled note-graph SDK is StarkWare's, Apache-2.0 — see NOTICE-starknet-sdk.md. Full guide: the docs' "Private Balances" page; runnable example + smoke: examples/private-balance.