Atomic Transfers

Atomic Transfers are irreducible batch transactions that allow groups of transactions to be submitted at one time. If any of the transactions fail, then all the transactions will fail. That is, an Atomic Transfer guarantees the simultaneous execution of multiple transfers of all kinds of fungible tokens. 

The implementation allows individual transactions to be created and then grouped into a file. Each transfer is signed separately by the originator of the transfer. This file is then submitted to the network, where the node verifies the transactions and submits them all at once. This eliminates the need for hashed time-locks for atomic swaps in other blockchains and also avoids the delays inherent with hashed timed-locks.

Atomic Transfers enables applications such as: 

  • Circular trades: Alice pays Bob if and only if Bob pays Clare if and only if Clare pays Alice
  • Group payments: Either everyone pays or no one does.
  • Decentralized exchanges: Atomic multi-party transfers enable trades without trusted intermediaries.
  • Internal units of accounting: Several companies can settle their accounts with each other with a single transaction.
  • Payments to multiple recipients

The primary steps to creating an Atomic Transfer are as follows:

  • Create unsigned transactions and save them to a file

  • Combine these transactions in to one file

  • Sign the grouped transactions with all the appropriate keys and submit them

See here for SDK Documentation: Atomic Transfer SDK Usage

Step 1: Create unsigned transactions and save them to a file

Before getting into the details of how Atomic Transfers work and if you have not done so already... we will create a default Wallet and add three accounts using the goal account and wallet new commands. 

goal wallet new MyWallet -d data
goal wallet -f MyWallet  -d data
goal account new -d data
goal account new -d data
goal account new -d data

We will also seed some TestNet algos into each account to account for transaction fees using the TestNet dispenser.  Run this command and you should see something similar to the accounts listed below…

goal account list -d data
[offline] Unnamed-0 R4G4IWWH5LTK5VICEGTNUXUEMPKBCKTL5HFG77YXPN2B3EMXPDGIRPCVDI 1000000 microAlgos *Default

This process is the same as creating any transaction in Algorand, which can be done with any of the SDKs or using goal. The only difference is the transaction must saved to memory or a file to be combined with other transactions later. For example to do this in goal you can save the transaction to a file using the -o option with the goal clerk send command.


Notice that we do not use the -s option which signs the transaction. Signing has to occur after grouping the transactions. You can create additional transactions by just creating new files.



Step 2: Combine these transactions into a group

The next step is to combine all the transactions into one group. This can be done on a unix based system using the cat OS command, similar to the following.

 cat 1.tx 2.tx > at1.tx
goal clerk group -i at1.tx -o out.tx -d data -w yourwallet

Step 3: Sign the grouped transactions and submit them

The final step to creating an Atomic Transfer is to create and submit the grouped transaction file to the network.

The out.tx file contains the raw transactions that can now be then be signed using the goal clerk sign command. If all the keys are on the same machine this can be done with the following command.

 goal clerk sign -i out.tx -o signout.tx -d data -w yourwallet

If the keys are located on different machines you will need to use the goal clerk split command to separate each transaction into its own file to be signed on that machine.

goal clerk split -i out.tx -o splitfiles -d data -w yourwallet 
Wrote transaction 0 to splitfiles-0
Wrote transaction 1 to splitfiles-1
goal clerk sign -i splitfiles-0 -o splitfiles-0.sig -d data -w yourwallet
goal clerk sign -i splitfiles-1 -o splitfiles-1.sig -d data -w yourwallet

Once individual files are signed you would use another cat command to combine all the signed transactions into one file to be submitted.

cat splitfiles-0.sig splitfiles-1.sig > group.sig

You can submit the combined signed and grouped transactions to the network using goal clerk rawsend.

goal clerk rawsend -f group.sig -d data -w yourwallet

The node will verify that all transactions are valid and submit them. If any transaction is not valid, all of them will fail.