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.jsAccountinstanceopts.paymaster(PaymasterAdapter, optional): Adapter for gasless transactions viasendSponsored()
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 addressspender(string): Address to approveamount(bigint): Raw amount in base units
Returns
this (chainable)
transfer(token, targets)
Add one or more ERC20 transfer calls.
Parameters
token(string): Token contract addresstargets(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
paymasterwas configured in the constructor - If no calls have been added
- If
send()orsendSponsored()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’sWalletAccount wraps the wallet as an Account; Bramble injects it as window.starknet_bramble.
- Bramble parses params strictly: a fee,
max_feeor paymaster field fails with114.send()adds none (WalletAccount.executesends 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
InjectedConnectorwith 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:
- reads the account’s class hash with
getClassHashAt, so the account must already be deployed; - asks Chipi’s backend for SNIP-9 outside-execution typed data for the calls;
- 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 sentr = 1, s = 0for that shape); - has Chipi’s paymaster relay it, paying the gas.
[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)
Related
- Amount: Type-safe token amounts for use with TxBuilder
- Erc20: Generate typed Call objects for approve/transfer
- SignerAdapter: Different signing strategies for the Account
