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.

Initial state

The environment looks as follows:

The default user account on ABC-owned node 1 owns 1000 tokens in the ACME contract:

The default user account on XYZ-owned node 2 owns 2 digital collectible tokens in the MOVIE contract:

Initiate Swap Proposal from Sending Organization

• Organization ABC clicks the ABC - tokenswap service 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 ACME loyalty 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 ACME loyalty 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 - tokenswap service.

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 MOVIE token
• 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 - tokenswap instance
• A notification is displayed saying that 1 MOVIE token 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 MOVIE token
• 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 MOVIE token smart contract

Counter-party Receives Notification

• Organization XYZ accesses the XYZ - tokenswap service
• Organization XYZ sees a similar notification stating that 100 ACME tokens 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 ACME tokens are transferred to the XYZ-owned node 2 default user account
• This state is represented in the ACME token contract
• 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 ACME loyalty and a new digital collectible MOVIE token

• Organization XYZ has the 100 ACME loyalty point tokens and a single remaining non-fungible digital collectible MOVIE token

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.