buildInvoke

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:

1. Build the transaction with automatic type conversion

2. Check who needs to sign with needsNonInvokerSigningBy()

3. Collect signatures from each party with signAuthEntries()

4. 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)
}

Parameters

Throws

Build a transaction for invoking a contract method with pre-encoded XDR arguments.

This is the spec-free counterpart to the Map-based buildInvoke. Arguments are supplied as SCValXdr values that the caller has already encoded, so no ContractSpec is required and the method works on clients created via forContractWithoutSpec. It is the primary entry point for generated bindings that need transaction control (multi-signature workflows, memos, custom preconditions).

The transaction is built and, when ClientOptions.simulate is set, simulated; the returned AssembledTransaction is not signed or submitted. This mirrors the Map-based buildInvoke exactly, minus the spec-driven argument conversion and method-name validation (an unknown function fails at simulation time instead of before the request).

Parameters