Token Swaps Usage
Use the Kaleido Swap service to securely exchange tokenized assets with other account owners in your environment. The service provides a convenient interface that allows for any member with the service deployed to act as their own market maker or transaction initiator by offering a designated amount of liquidity (one or more tokens) to a specified counterpart. Under the covers the swap service leverages an underlying hash time locked contract (HTLC) as an escrow, which provides security and atomicity for any proposed token swaps. Counterparts to proposed swaps can subsequently react to the proffered liquidity by injecting tokenized assets under their control into the HTLC. If the trade initiator is happy with the counter-offer, they can withdraw the asset(s) and unlock the HTLC for the counterpart to receive the initially proposed liquidity.
The Transfer Flow
The flow takes place as follows:
- Party A specifies a token, an amount and their wallet address that owns the asset(s)
- Party A designates the recipient, HTLC timeout and secret management scheme
- specifies the counterpart’s wallet address
- specifies contract timeout
- chooses self-managed or Kaleido-managed secret
- optionally inputs an email address to notify counterpart of proposal
- Party A deposits their token(s) into the HTLC. The asset(s) are locked and the timer begins
- Party B responds to the swap offer by:
- specifying a token
- specifying their wallet address that owns the asset(s)
- specifying an amount
- Party B deposits their token(s) into the HTLC
- Party A has half of the contract’s remaining timeout window to claim Party B’s asset(s)
- If the secret is self-managed, Party A needs to supply the secret to unlock the contract
- If the secret is Kaleido-managed, Party A simply needs to “claim”
- Once Party A has claimed, the contract is “unlocked” for Party B to claim to the proffered liquidity
- If Party A does not claim Party B’s asset(s) within the available timeout window, then each asset can be refunded upon expiration of the contract.
NOTE: Swaps are multi-part and time sensitive. As such, Kaleido recommends an out-of-band agreement on token transfers prior to locking assets into the HTLC. This helps with coordination and adds assurances for the successful completion of the transaction.
Walk through of a transfer
This sample flow uses two memberships – Organization ABC & Organization XYZ – where each membership has a token swap service, a token factory service and a single node deployed in the environment. The default user account for the Organization ABC node owns the entire supply of tokens in an ERC20 Movie Theatre Loyalty Points token contract; the contract symbol is
ACME. The default user account for the Organization XYZ node owns two non-fungible tokens within an ERC721 Digital Movie Collectibles token contract; the contract symbol is
MOVIE. An understanding is in place where a digital movie collectible can be redeemed for 100 loyalty points.
The environment looks as follows:
The default user account on ABC-owned node 1 owns 1000 tokens in the
The default user account on XYZ-owned node 2 owns 2 digital collectible tokens in the
Initiate Swap Proposal from Sending Organization
- Organization ABC clicks the
ABC - tokenswapservice to initiate the transfer.
- Organization ABC clicks the Swap Tokens button in the service dashboard.
- Organization ABC is taken to an info panel with some high level information about the swap mechanics.
Choose Offer Details
- Organization ABC clicks Let’s Get Started
- Organization ABC selects the
ACMEloyalty points token for its side of the swap
- Organization ABC specifies the node 1 user account that owns the tokens
- Organization ABC specifies 100 as the transfer amount
Choose Target for Swap
- Organization ABC clicks Next
- Organization ABC inputs the wallet address for Organization XYZ (this is the XYZ-owned node 2 default user account)
- Organization ABC sets the swap timeout. We use 1 hour in this example
- Organization ABC chooses the secret management scheme. We use Kaleido-managed in this example
- Organization ABC enters the email address for Organization XYZ node owner
Deposit Offer into Escrow
- Organization ABC clicks Deposit and the 1 hour timer begins.
- This locks the 100
ACMEloyalty point tokens into the HTLC as shown in the on-screen graphic. The tokens are only refundable after the 1 hour time lock expires.
- A notification is sent to the specified Organization XYZ email. Additionally, a notification is triggered in the
XYZ - tokenswapservice.
Counter-party Receives Notification via Email
- Organization XYZ receives an email and accesses the XYZ - tokenswap service.
- Organization XYZ sees a notification that ABC has offered 100 ACME tokens.
- Organization XYZ clicks the Details tab
Respond to Offer
- Organization XYZ clicks the Respond to Offer button
- Organization XYZ specifies the
- Organization XYZ specifies the node 2 default user account that owns the tokens
- Organization XYZ specifies the token ID. In our case this is 1
Deposit Accepted Offer into Escrow
- Organization XYZ clicks Deposit.
- This locks the non-fungible movie collectible token into the HTLC.
- Both assets are now held in the escrow smart contract. This is visualized through the service graphic.
- Now its time for Organization ABC to respond to the offer from Organization XYZ
Initiator Receives Notification
- Organization ABC returns to the
ABC - tokenswapinstance
- A notification is displayed saying that 1
MOVIEtoken is ready to be claimed
- The screen also shows the status of a previous swap that expired and the subsequent refund of ACME tokens
Initiator Reviews the Status
- Organization ABC clicks Details to claim the
- Organization ABC is taken to a new screen displaying the remaining time available for the claim
- Organization ABC has half of the HTLC’s remaining time once Organization XYZ locked their asset.
- Simple Maths: HTLC Timeout of 1 hour. Organization XYZ locks assets with 30 min remaining. Organization ABC has 15 min to claim
Initiator Claims the Offer
- Organization ABC clicks Claim Offer
- The asset is transferred to the ABC-owned node 1 default user account
- This state is represented in the
MOVIEtoken smart contract
Counter-party Receives Notification
- Organization XYZ accesses the XYZ - tokenswap service
- Organization XYZ sees a similar notification stating that 100
ACMEtokens are ready to be claimed
- Organization XYZ clicks the Details button to claim the reward points
Counter-party Claims the Offer
- Organization XYZ clicks Claim Offer
- The 100
ACMEtokens are transferred to the XYZ-owned node 2 default user account
- This state is represented in the
- The on-screen graphic provides a visualization of the new token ownership
Both Parties see Updated Balances
- Each Organization can now access their default node wallets to see the token ownership visualized
- Organization ABC has 900 remaining
ACMEloyalty and a new digital collectible
- Organization XYZ has the 100
ACMEloyalty point tokens and a single remaining non-fungible digital collectible
Alternate Signing Accounts
This sample made use of the default node user accounts for the sake of readability and simplicity. In a real world swap it’s likely that an organization would utilize alternate wallet addresses in order to logically partition assets across different accounts. The Wallet service can be used to create additional signing accounts and these addresses can be specified by using the Signing Account dropdown to designate which address will sign transactions and ultimately own assets. For more information on the Wallet service and account creation, please refer to the Managed Wallet documentation.