The Transfer action is the means by which all asset transfers are conducted, with the exception of enforcement actions. The action is versatile and allows assets to be transferred between multiple holders and across multiple smart contracts. The following outlines the main ways in which the Transfer action is used.
The act of transferring tokens can become complicated when there are multiple parties and contracts involved, however, the final outcome is always captured in just two on-chain transactions:
- Transfer action (Request)
- Settlement action (Response)
Note: Unlike most other actions, the Transfer action places the participating addresses inside the message payload as an Asset Transfer type instead of using the transaction inputs and output. This means the recipient of a transfer will be unaware of the transfer until it has settled and helps reduce the number of dust outputs. The same structure applies to the Enforcement actions.
When transferring tokens to a single receiver the transfer is an action between 2 parties which is validated by a smart contract.
In this example, a token issuer will send 100 tokens from its own balance to a receiver. This event is initiated by the the administration of the contract issuer through the creation of a Transfer action detailing the receiver's address and the number of tokens they wish to send.
The smart contract receives the request into its wallet and validates that it meets all of the terms and conditions for transfers on the contract. Once evaluated, the contract then builds a Settlement action in response and sends it onto the network.
Similarly, when transferring tokens to multiple receivers--for an issuer to distribute tokens to more than one person--the transfer is a 2 step process.
In this example, the issuer will now send an additional 100 tokens to the receiver from the example above (receiver 1), and 300 tokens to a second receiver (receiver 2).
Note that the transfer action deals with the number of tokens being sent, but the settlement transaction deals with the final balances of each account. First, the administration builds a transfer request detailing the number of tokens to be sent and the addresses to send them to:
Next, once the smart contract has checked everything is ok, it sends a settlement transaction that updates the balances of any wallets involved in the transaction.
Swap Tokens for Bitcoin
The purchase of tokens with Bitcoin (token for bitcoin transfer) is a more complicated interaction as it requires that the Transfer action be signed by two parties before it can be sent onto the network.
This would typically work by the token purchaser entering into an exchange interface or shopfront, and selecting the tokens that they wish to purchase. Typically, the interface will provide them with a cost for the tokens, with a time limit to finalize the purchase at the proposed price.
When the user has assembled the information for their purchase, they are sent a Message action which contains an 'Offer' message type. This includes a transaction template that contains the details of the seller, the amount they are to pay, the asset and the smart contract that will settle the transaction.
Depending on the exchange used, there may be additional BSV outputs for the cost of performing the exchange. These details will also be included in the Transfer template. If the buyer changes the contents of the transaction, the exchange can simply elect not to sign, invalidating the transaction. If the buyer is happy with the proposed exchange, they add appropriate Bitcoin inputs to the transaction, insert their token receiving address into the appropriate locations, and sign the transaction, sending the template back to the Smart Contract in a 'Signature Request' message.
Once the seller-signed transaction has been received by the merchant/exchange, they have one final opportunity to verify that the contents remain in-line with what they agreed to with the buyer, and can sign and transmit the transaction to the Bitcoin network.
Because only one smart contract is involved, the exchange settlement can be built and sent directly by the smart contract.
Cross Contract Atomic Swaps
Conducting an atomic swap (token for token transfer) using Tokenized is another more complicated transaction as it requires the holders of the tokens being exchanged to sign the Transfer action, and for both smart contracts to sign the Settlement action.
To begin, the two token holders agree to a transaction between themselves. The first token holder builds a partially complete transaction template which has the full details of the exchange except for the second party's receiving addresses and UTXO commitment. This is sent to the second party as a serialized partial transaction inside a Message action, using message type 1001 (Offer).
The second party then fills in the missing details and signs the transaction before sending it back to the first party in another message using message type 1002 (Signature Request).
The first user then countersigns and sends the transaction to the Bitcoin network.
Once it is received by the smart contracts, the first contract listed in the Transfer action builds a settlement action template. Since the first contract doesn't know the balances of the other contract it sends the incomplete settlement action data to the second contract in a message type 1003 (Settlement Request).
The second contract then adds settlement data pertaining to it and since the data is now complete and it knows everything about the settlement, it creates the complete settlement tx (minus signatures), signs its inputs, and sends it back to the first contract in a message type 1002 (Signature Request).
The first contract then double checks the settlement transaction to ensure the second contract didn't modify anything it wasn't supposed to, then signs it and transmits it to the Bitcoin network. In this example, Participant 1 is sending 100 of its 150 Token 1 to Participant 2 (who previously had none) in exchange for 20 of its Token 2 (all of them). Participant 1 already has 10 of Token 2, leaving its final balance at 30.