Overview

Soroban, and Stellar more generally, supports having multiple parties sign the same transaction.

Prior to now, the libraries generated with soroban contract bindings typescript did not.

This adds multi-auth support to the generated libraries, streamlining it as much as possible while adding minimal overhead to the "normal stuff" that most people will do with these libraries 98% of the time.

Read calls (simulation only)

The biggest change for view calls, which require only a simulation and no signing, is that you now need to get the result of a transaction:

-const balance = await tokenContract.balance({ account: 'G…' })
+const balance = (await tokenContract.balance({ account: 'G…' })).result

You can streamline this further using destructuring:

-const balance = await tokenContract.balance({ account: 'G…' })
+const { result: balance } = await tokenContract.balance({ account: 'G…' })

Or just call the variable result and it looks very clean:

-const balance = await tokenContract.balance({ account: 'G…' })
+const { result } = await tokenContract.balance({ account: 'G…' })

Write calls with one signer

For these, you now need to explicitly sign and send the transaction. This helps you build up the mental model that the transaction is first simulated, that this is good enough for view calls, and that you also need a signAndSend step if you want a write call to actually go through.

-const result = await tokenContract.send({ to: 'G…', amount: 10n })
+const tx = await tokenContract.send({ to: 'G…', amount: 10n })
+const { result } = tx.signAndSend()

This also allows these libraries to expose information and options in more expectable places, rather than cluttering global interfaces. Examples:

• tx.isReadCall – make explicit logic around read vs write calls
• tx.signAndSend({ secondsToWait: 30 }) – specify how many seconds to wait for the transaction to complete (default: 10)
• tx.raw – access the raw SorobanClient transaction that this object wraps
• tx.simulationData – get the result of the simulation

Once you signAndSend(), the object you get back has different fields that are more relevant to the signing and sending behavior. See SentTransaction for more information.

Write calls with >1 signer

Let's consider an Atomic Swap contract. Alice wants to give 10 of her Token A tokens to Bob for 5 of his Token B tokens.

const ALICE = 'G123...'
const BOB = 'G456...'
const TOKEN_A = 'C123…'
const TOKEN_B = 'C456…'
const AMOUNT_A = 10n
const AMOUNT_b = 5n

Let's say Alice is also going to be the one signing the final transaction envelope, meaning she is the invoker. So your app, from Alice's browser, simulates the swap call:

const tx = await swapContract.swap({
  a: ALICE,
  b: BOB,
  token_a: TOKEN_A,
  token_b: TOKEN_B,
  amount_a: AMOUNT_A,
  amount_b: AMOUNT_B,
})

But your app can't signAndSend this right away, because Bob needs to sign it first. You can check this:

const whoElseNeedsToSign = tx.needsNonInvokerSigningBy()

You can verify that whoElseNeedsToSign is an array of length 1, containing only Bob's public key.

Then, still on Alice's machine, you can serialize the transaction-under-assembly:

const json = tx.toJSON()

And now you need to send it to Bob's browser. How you do this depends on your app. Maybe you send it to a server first, maybe you use WebSockets, or maybe you have Alice text the JSON blob to Bob and have him paste it into your app in his browser (note: this option might be error-prone 😄).

Once you get the JSON blob into your app on Bob's machine, you can deserialize it:

const tx = swapContract.fromJSON.swap(json)

And have Bob sign it. What Bob will actually need to sign is some auth entries within the transaction, not the transaction itself or the transaction envelope. Your app can verify that Bob has the correct wallet selected in Freighter, then:

await tx.signAuthEntries()

Under the hood, this uses signAuthEntry from the injected wallet (@stellar/freighter-api by default).

Now Bob can again serialize the transaction and send back to Alice, where she can finally signAndSend().

To see an even more complicated example, where Alice swaps with Bob but the transaction is invoked by yet another party, check out the new test-swap.ts

All the nitty gritty details

Here's a full(er) accounting of everything that changed here:

• switch from ts-tests/package.json to an initialize.sh script that
  uses a .env if available or defaults to environment variables. As
  before, this will build, deploy, and generate bindings for the new
  contracts, plus creating an alice identity and minting separate
  amounts of two separate tokens to the root user and alice
• add eslint to catch missing awaits
• add transaction-rebuilding to increment transaction sequence numbers,
  so that all tests can pass when run in parallel
• add atomic_swap and token contracts from
  https://github.com/stellar/soroban-examples to test-wasms
• add tests for atomic swap functionality inspired by
  https://github.com/stellar/soroban-react-atomic-swap
• let this logic guide needed updates to bindings typescript-generated
  libraries:
  • don't return flat values
  • instead, return a new AssembledTransaction, a class that has a
    result getter that can be used to get the result of the simulation
    right away, or can be used to await tx.signAndSend(), which then
    returns a SentTransaction
  • SentTransaction contains all possibly-relevant fields
    from the logic it performs, such as sendTransactionAll
  • AssembledTransaction has a needsNonInvokerSigningBy() getter
    and a signAuthEntriesFor(publicKey, signingFunction) to facilitate
    multi-auth workflows.
  • Since assembling transactions may now take place across multiple
    users' browsers, you can also call json = tx.toJSON() on an
    AssembledTransaction and then contract.fromJSON[method](json) on
    the next machine to continue signing, as shown in test-swap.ts