Skip to main content
@chipi-stack/core is in development (v0.1.0). APIs may change before stable release.

Overview

TxBuilder provides a fluent API for composing multiple StarkNet calls into a single atomic transaction. All calls execute together via Account.execute(), which is more gas-efficient than separate transactions (important when sponsoring gas via a paymaster).

Usage

Constructor

Parameters

  • account (Account): A starknet.js Account instance
  • opts.paymaster (PaymasterAdapter, optional): Adapter for gasless transactions via sendSponsored()

Methods

add(call)

Add one or more raw StarkNet calls to the batch.

Parameters

  • call (Call | Call[]): A single Call or array of Calls

Returns

this (chainable)

approve(token, spender, amount)

Add an ERC20 approve call. Handles uint256 encoding automatically.

Parameters

  • token (string): Token contract address
  • spender (string): Address to approve
  • amount (bigint): Raw amount in base units

Returns

this (chainable)

transfer(token, targets)

Add one or more ERC20 transfer calls.

Parameters

  • token (string): Token contract address
  • targets (TransferTarget[]): Array of { to: string, amount: bigint } pairs

Returns

this (chainable)

calls()

Returns a copy of the current call batch (for inspection).

Returns

Call[]

send()

Execute all batched calls atomically.

Returns

Promise<InvokeFunctionResponse>

Throws

  • If no calls have been added
  • If send() was already called (builders are single-use)

sendSponsored()

Execute via Chipi’s paymaster (gasless). Requires a PaymasterAdapter in the constructor.

Returns

Promise<string> (transaction hash)

Throws

  • If no paymaster was configured in the constructor
  • If no calls have been added
  • If send() or sendSponsored() was already called (builders are single-use)

estimateFee()

Estimate the fee for the current batch without executing.

Returns

Promise<EstimateFeeResponse>

Throws

  • If no calls have been added

preflight()

Simulate the transaction without submitting. Returns the transaction trace and fee estimation. Useful for checking if a transaction would succeed before sending.

Returns

Promise<PreflightResult> with transaction_trace and fee_estimation

Throws

  • If no calls have been added

Examples

Simple Transfer

Approve + Swap (Atomic Batch)

Fee Preview Before Sending

With Erc20 and Amount

With Bramble (browser wallet)

The user’s own wallet signs and pays gas. starknet.js’s WalletAccount wraps the wallet as an Account; Bramble injects it as window.starknet_bramble.
  • Bramble parses params strictly: a fee, max_fee or paymaster field fails with 114. send() adds none (WalletAccount.execute sends only { calls }). Keep a batch to 16 calls, and pass contract addresses as lowercase hex.
  • A new OpenZeppelin or Argent account is deployed in the same flow as its first transaction. An undeployed Braavos account is refused.
  • Braavos and Ready work the same way through their own injected objects. With starknetkit, add Bramble as an InjectedConnector with id "bramble"; it is not in the default list.
  • A transaction hash is not a result: wait for the receipt (provider.waitForTransaction).

Can Bramble use sendSponsored()?

Bramble’s guide says dApp-sponsored (paymaster) transactions are not supported through its public provider: wallet_addInvokeTransaction refuses paymaster fields. sendSponsored() takes a different path. With Chipi’s adapter (sdk.createPaymasterAdapter) it:
  1. reads the account’s class hash with getClassHashAt, so the account must already be deployed;
  2. asks Chipi’s backend for SNIP-9 outside-execution typed data for the calls;
  3. has the wallet sign it with signMessage (wallet_signTypedData) and keeps { r, s }: the two felts of [r, s], or the last two of Argent’s ["1", "0", publicKey, r, s] (14.17.0+; earlier versions sent r = 1, s = 0 for that shape);
  4. has Chipi’s paymaster relay it, paying the gas.
So it needs a deployed account whose class supports outside execution and accepts [r, s] from its key. Bramble reviews an outside-execution typed data like an invoke. This path has not been verified with Bramble or Ready: until it is, use send().

Gasless with Cartridge Controller

Backend Automation (gasless)

  • Amount: Type-safe token amounts for use with TxBuilder
  • Erc20: Generate typed Call objects for approve/transfer
  • SignerAdapter: Different signing strategies for the Account