build
Build a transaction for invoking a contract method with Map arguments.
This method returns an AssembledTransaction that you can manipulate before signing and submitting. Essential for multi-signature workflows where multiple parties need to sign authorization entries before the transaction is submitted.
For simple execution without transaction manipulation, use invoke instead.
Primary Use Case: Multi-Signature Workflows
When a contract requires authorization from multiple parties (e.g., atomic swaps, multi-party escrow, DAO proposals), use buildInvoke() to:
Build the transaction with automatic type conversion
Check who needs to sign with
needsNonInvokerSigningBy()Collect signatures from each party with
signAuthEntries()Submit once all signatures are collected
// Alice wants to swap Token A for Bob's Token B
val client = ContractClient.forContract(swapContractId, rpcUrl, network)
val tx = client.buildInvoke(
functionName = "swap",
arguments = mapOf(
"a" to aliceAddress,
"b" to bobAddress,
"token_a" to tokenAContractId,
"token_b" to tokenBContractId,
"amount_a" to 1000,
"min_b_for_a" to 4500,
"amount_b" to 5000,
"min_a_for_b" to 950
),
source = aliceKeypair.accountId,
signer = aliceKeypair
)
// Check who else needs to sign
val otherSigners = tx.needsNonInvokerSigningBy()
println("Bob needs to sign: ${otherSigners.contains(bobAddress)}")
// Bob signs his authorization entries
tx.signAuthEntries(bobKeypair)
// Alice submits the transaction with all signatures
val result = tx.signAndSubmit(aliceKeypair)Other Use Cases
Adding memos: Attach metadata like invoice numbers or payment references
Custom time bounds: Set specific transaction validity windows
Simulation inspection: Review resource costs and footprint before committing
Custom preconditions: Add ledger bounds or minimum sequence number
// Example: Adding a memo
val tx = client.buildInvoke("transfer", transferArgs, source, signer)
tx.raw?.addMemo(Memo.text("Invoice #12345"))
tx.signAndSubmit(signer)
// Example: Inspecting simulation results
val tx = client.buildInvoke("complexCall", args, source, signer)
val simData = tx.getSimulationData()
if (simData.transactionData.resourceFee < maxAcceptableFee) {
tx.signAndSubmit(signer)
}Return
AssembledTransaction for manual control
Parameters
The contract function to invoke
Function arguments as Map
The source account (G... or M... address)
KeyPair for signing (null for read-only calls)
Optional custom function to parse result XDR
Invocation options
Throws
if contract spec not loaded
if method not found or invalid arguments