This is an implementation of the ICS 721 specification written in CosmWasm. It allows NFTs to be moved between IBC compatible blockchains.
This implementation
- is entirely compatible with the cw721 NFT standard, the standard used by most NFT marketplaces in the IBC ecosystem;
- has a minimal, but powerful governance system that can quickly pause the system in an emergency, without ceding any of the governance module's control over the bridge;
- supports a proxy system that allows for arbitrary filtering and rate limiting of outgoing NFTs;
- is well tested.
From a thousand feet up
This contract deals in debt-vouchers.
To sent a NFT from chain A to chan B:
- The NFT is locked on chain A.
- A message is delivered over IBC to the destination chain describing the NFT that has been locked.
- A debt-voucher, which is convienently an exact replica of the NFT locked on chain A, is minted on chain B.
The duplicate NFT on the receiving chain is a debt-voucher. Possession of that debt-voucher on the receiving chain gives the holder the right to redeem it for the original NFT on chain A.
To return the transferred NFT:
- The debt-voucher is returned to the bridge.
- A message is sent to the source chain informing it that the debt voucher has been returned.
- The original NFT is unlocked and sent to the receiver of the NFT.
- The debt-voucher is burned on chain B.
The failure handling logic for this contract is also reasonably simple to explain: if the receiver does not process the packet correctly, the NFT sent to the bridge is returned to the sender as if the transfer had never happened.
From closer to the ground
The complete process for an ICS-721 NFT transfer is described in this flowchart:
Quick pauses and filtering
This implementation can be quickly paused by a subDAO and supports rich filtering and rate limiting for the NFTs allowed to traverse it.
Pause functionality is designed to allow for quick pauses by a trusted group, without conceding the ability to lock the contract to that group. To this end, the admin of this contract may appoint a subDAO which may pause the contract a single time. In pausing the contract, the subDAO looses the ability to pause again until it is reauthorized by governance.
After a pause, the bridge will remain paused until governance chooses to unpause it. During the unpause process governance may appoint a new subDAO or reappoint the existing one as pause manager. It is imagined that the admin of this contract will be a chain's community pool, and the pause manager will be a small, active subDAO. This process means that the subDAO may pause the contract in the event of a problem, but may not lock the contract, as in pausing the contract the subDAO burns its ability to do so again.
Filtering is enabled by an optional proxy that the bridge may be configured to use. If a proxy is configured, the bridge will only accept NFTs delivered by the proxy address. This proxy interface is very minimal and enables very flexible rate limiting and filtering. Currently, per-collection rate limiting is implemented. Users of this bridge are enchouraged to implement their own filtering regimes and may add them to the proxy repository so that others may use them.
Failure handling eratta
This contract will never close an IBC channel between itself and another bridge. If the other side of a channel closes the connection, the bridge assumes this has happened due to a catastrophic bug in its counterparty or a malicious action. As such, if a channel closes NFTs will not be removable from it until governance intervention sets the policy for what to do.
Depending on what kind of filtering is applied to this contract, permissionless chains where anyone can instantiate a NFT contract may allow the transfer of a buggy cw721 implementation that causes transfers to fail.
These sorts of issues can cause trouble with relayer implementations. The inability to collect fees for relaying is a limitation of the IBC protocol and this bridge contract can not hope to address that. To this end, it is strongly recommended that users of this bridge and all other IBC bridges have users relay their own packets. We will be working on an implementation of this that other front ends can easily integrate as part of this work.