Moving ERC721 Tokens Between Ethereum and Basechain Using Transfer Gateways
Update:
- Basechain was formerly known as PlasmaChain. Read the official announcement.
- We have a step-by-step video tutorial for using the Transfer Gateway to transfer assets to a Loom DappChain:
In our previous article, we covered how to get started with a development environment and deploy your first dapp to Loom Network’s Basechain testnet.
Basechain is a DPoS blockchain with 21+ validators around the world, which is great for transaction throughput and computation time, but a bit less secure than Ethereum mainnet.
Transfer Gateways allow for the same level of security guaranteed by the Ethereum network through its massive network of nodes and validators for digital assets created on Basechain. As the name implies, they are collectively a set of gateways through which you can transfer your ERC721 (and soon ERC20) assets over to Ethereum mainnet and other smart contract chains.
Transfer Gateways are broken down into four pieces:
- Ethereum Gateway
- Basechain Gateway
- Basechain Address Mapper
- Gateway Oracle
Let’s break these down one by one to understand how they work.
Ethereum and Basechain Gateways
The Ethereum Gateway works to communicate with the Gateway Oracle when there is a deposit event. It’s a mechanism for communicating with the Gateway Oracle. The Basechain Gateway serves much the same purpose as the Ethereum Gateway, only being the endpoint on the Basechain instead.
Basechain Address Mapper
The Basechain Address Mapper exists to bake in the idea of “multiple accounts” on multiple chains. By registering your accounts on the Address Mapper, you can claim the ERC721 tokens as they are deposited to Basechain.
Gateway Oracle
The Gateway Oracle is in charge of communicating between Ethereum (among other chains) and Basechain. It usually runs on nodes that serve as validators for Basechain, but can be run standalone. It monitors for activity on the Gateway Contracts from Ethereum or Basechain, listening for deposit and withdrawal events. When it picks up an event, it published a transaction to the other chain.
Example Transaction
Let’s put this together into a cohesive play-by-play.
Charlie just traded a Water Officer card for a Fire Officer card on Ethereum mainnet. He wants to transfer his new Fire Officer to Basechain, so he can use it in Zombie Battleground, a game built on Basechain.
Charlie must register his Ethereum account with the Basechain Address Mapper. This only needs to be done once.
To prove that Charlie owns the Ethereum account, Charlie will create a request to Basechain Address Mapper providing a message signed by his Ethereum account’s public key. The Basechain Address Mapper will map that Ethereum public key to the Basechain account that made that mapping request.
Charlie is now set up to move tokens between the chains.
The first step is to deposit the token into the Ethereum Gateway. This transfers the ownership of the token to the Gateway, and emits a deposit event.
The second step is that the Gateway Oracle picks up this deposit event as it’s subscribed to both Ethereum and Basechain Gateway events. The Gateway Oracle then does one of two things:
If the token does not exist on Basechain, then it will “mint” a new token with those specifications, whose owner will be the Basechain Gateway. Then it will be made available for withdrawal by the depositor's Basechain account which they will have included as part of the deposit transaction.
If the token is owned by the Basechain Gateway already (which might happen if it was originally created on Basechain and then transferred to a different chain) then it is available for withdrawal by the depositor’s Basechain account.
Finally, using his Basechain account, Charlie can claim this token through the Basechain Gateway by issuing a withdrawal request.
If Charlie wanted to trade his new card to someone on Ethereum or wanted to store a rare card he got on his Ethereum wallet instead of the Basechain wallet for security, he would issue a transfer request from the Basechain Gateway, which would get picked up and signed by the Gateway Oracle. He can then take the withdrawal receipt and claim it on Ethereum.
How to Connect Your ERC721 Token to the Transfer Gateways
If you’re a dapp developer and you want to issue transferable ERC721 tokens, you might be wondering how to connect your ERC721 token to the Transfer Gateways.
The first step is to deploy your ERC721 contracts on both Basechain and on Ethereum. The contracts don’t need to be anything special, as the deposit function is simply a transfer of ownership of the token from the user to the Gateway contract. That being said, it might be useful to include a depositToGateway or similar function that specifically transfers to a known Gateway contract address so your users don’t have to put the Gateway address every time.
pragma solidity ^0.4.24;
import "openzeppelin- solidity/contracts/token/ERC721/ERC721Token.sol"; contract MyAwesomeToken is ERC721Token("MyAwesomeToken", "MAT") { // Mainnet Gateway address address public gateway;constructor(address _gateway) public {
gateway = _gateway;
}function depositToGateway(uint tokenId) public {
safeTransferFrom(msg.sender, gateway, tokenId); }
}
Once you’ve deployed your ERC721 token contracts on both the chains, you need to create a mapping between them. This “registers” your token with the Gateways. In this example, we will create a mapping between Ethereum testnet (Rinkeby) and Basechain Testnet (extdev).
The Rinkeby Transfer Gateway address as of this writing is: 0xF19D543f5ca6974b8b9b39Fcb923286dE4e9D975
As this is a testnet, the Gateway contract could be wiped and redeployed by the Loom team. As such, make sure to always check this page for the current address.
The mapping can be accomplished by calling the extdev Gateway contract’s addContractMapping function with the addresses of both ERC721 token contracts and a signature proving that you own those contracts.
To prove that you deployed the ERC721 contract to one of the Ethereum networks, you must provide a signature generated by signing a message using the Ethereum private key you used to deploy the contract, along with a hash of the Ethereum transaction that deployed the contract.
To prove that you deployed the ERC721 contract on Basechain is somewhat easier. You only need to sign the request to the Basechain Gateway to register your contract with the same key that you used to deploy the contract. The Basechain Gateway will then just make sure that your key is the owner of the deployed contract.
Sample App
To make this simpler, there’s a fantastic sample app you can look through on how to set up deployment and to use loom-js to accomplish these tasks. Loom-js is a javascript library to help you handle things like signing transactions and interacting with Transfer Gateways. A whole class (“TransferGateway”) is dedicated to providing an easy way to do things like mapping ERC721 contracts to each other between chains.
The Transfer Gateway example app can be found here, and loom-js can be found here.
Specifically looking through the Transfer Gateway example, one of the most useful files to check out is the gateway-cli.js, as it provides an excellent deployment tooling you can modify for your own set of contracts, or use as is. As of this writing, the addresses that link Rinkeby and extdev are hardcoded into gateway-cli.js, and so you might need to update those if they are different than ones listed on this page.
Loom Network is the multichain interop platform for scaling high-performance dapps — already live in production, audited, and battle-tested.
Deploy your dapp to Loom’s Basechain once and reach the widest possible user base across all major blockchains today.
New to Loom? Start here.
Want to stake your LOOM tokens and help secure Basechain? Find out how.
Like what we’re doing here? Stay in the loop by signing up for our private mailing list.
