Skip to main content

Overview

The Non-Fungible Token Connector consists of 4 contracts:

  • nft_connetor
  • bridge_token_deployer
  • bridge_token
  • permissions_manager

All of these contracts need to be installed on both chains.

For installing the bridge and all the prerequisties take a look on the section Running a Bridge

In this description we assume that a bridge between NEAR Testnet and a Calimero shard are set up.

Setting up the nft_connectors

On the nft_connetor, the owner of the contract needs to set the locker account, which is the nft_connetor contract on the other chain. This info is used to check when proving that a transaction/receipt happend on the other network, that it happened on the corresponding nft_connetor contract.

Bridging NFT from NEAR to Calimero (when original token is on NEAR)

In blockchain terminology here we are locking NFTs on NEAR and minting wNFT (wrapped NFT) on Calimero.

  1. Call nft_transfer_call on NFT contract on NEAR (lock on NEAR)
    • this step essentially locks a non-fungible token on the NEAR side, as a user/dapp sends NFTs to the nft_connetor contract on NEAR
  2. Call NEAR RPC for tx status
    • inside this transaction is the receipt with the event denoting a lock happened, and we are going to prove this on Calimero
  3. Call Calimero light client for current height
    • the current_height on the light client contract on Calimero needs to be higher than the block height where the lock of NFTs happened on source chain
  4. Call NEAR RPC for light client proof
    • this is all the proof data from the archival node on NEAR needed to be able to prove tx actually passed successfuly
  5. Call Mint() on Calimero nft_connetor, these are all the steps that happen:
    • If this is first time transferring that NFT then deploy the bridge_token on Calimero (since wNFT does not exist yet on Calimero)
    • Proves outcome (fails if proof invalid), if proved mints wNFT on Calimero
    • get_metadata for wNFT on Calimero, if empty: get_metadata on NEAR, and set_metadata on Calimero
    • map_contract on NEAR nft_connetor, map the Calimero NFT contract with NEAR NFT contract
  6. Congrats, wNFT exists now on Calimero

Bridging back NFT from Calimero to NEAR (burn the wrapped NFT)

In blockchain terminology here we are burning/withdrawing wNFTs on Calimero and unlocking NFT on NEAR.

  1. Call view_mapping on nft_connetor on Calimero in order to get the name of the wNFT since transfer initiator maybe knows only the NFT name on NEAR
  2. Call withdraw on the wNFT (bridge_token) on Calimero
    • this is the transaction we will need to prove that it actually happened
    • this method burns the wanted token_id of wNFT on Calimero
  3. Call Calimero RPC for tx status
    • we want to prove the receipt denoting a burn of a specific wNFT happened with the given token_id, and to whom it should be unlocked on NEAR side
  4. Call NEAR light client for current height
    • needs to be higher than the block height where the withdraw of wNFTs happened on destination chain
  5. Call Calimero RPC for light client proof
  6. Call unlock() on NEAR nft_connetor with the obtained proof and a valid block height
    • Proves outcome and if proved unlocks NFT on NEAR
  7. Congrats, NFT is now unlocked on the source network

Bridging between Calimero and NEAR when original asset is on Calimero

Original asset on Calimero means that it was first time ever minted on Calimero, it never existed on NEAR. This means that bridging to NEAR would bring a wrapped NFT on NEAR. All steps from the previous two sections apply, its only reversed.

Automatic bridging

All of these steps are automated with the Calimero Bridge service. The user/dapp needs only to make a nft_transfer_call when locking NFTs on a chain, the bridge service will do all the magic and the wrapped asset will appear on the other chain. Similarly, when someone wants to unlock the funds, they simply need to make a withdraw call on the nft contract, and the bridge service will automatically do its thing and all the components are updated automatically. The token will be unlocked on the other side if token were burnt on the starting chain.