Moving ERC721 Tokens Between Ethereum and PlasmaChain Using Transfer Gateways

In our previous article, we covered how to get started with a development environment and deploy your first DApp to the Loom PlasmaChain testnet.

PlasmaChain is a DPoS chain, which means that unlike Ethereum mainnet, the number of nodes participating in block creation is limited to a smaller handful of powerful machines. While this is great for transaction throughput and computation time, it means that PlasmaChain (and any other Ethereum sidechain) is 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 PlasmaChain. 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:

  1. Ethereum Gateway
  2. PlasmaChain Gateway
  3. PlasmaChain Address Mapper
  4. Gateway Oracle
Loom’s Transfer Gateway Docs

Let’s break these down one by one to understand how they work.

Ethereum and PlasmaChain 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 PlasmaChain Gateway serves much the same purpose as the Ethereum Gateway, only being the endpoint on the PlasmaChain instead.

PlasmaChain Address Mapper

The PlasmaChain 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 PlasmaChain.

Gateway Oracle

The Gateway Oracle is in charge of communicating between Ethereum (among other chains) and PlasmaChain. It usually runs on nodes that serve as validators for PlasmaChain, but can be run standalone. It monitors for activity on the Gateway Contracts from Ethereum or PlasmaChain, 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 PlasmaChain, so he can use it in Zombie Battleground, a game built on PlasmaChain.

Charlie must register his Ethereum account with the PlasmaChain Address Mapper. This only needs to be done once.

To prove that Charlie owns the Ethereum account, Charlie will create a request to PlasmaChain Address Mapper providing a message signed by his Ethereum account’s public key. The PlasmaChain Address Mapper will map that Ethereum public key to the PlasmaChain 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 PlasmaChain Gateway events. The Gateway Oracle then does one of two things:

If the token does not exist on PlasmaChain, then it will “mint” a new token with those specifications, whose owner will be the PlasmaChain Gateway. Then it will be made available for withdrawal by the depositor's PlasmaChain account which they will have included as part of the deposit transaction.

If the token is owned by the PlasmaChain Gateway already (which might happen if it was originally created on PlasmaChain and then transferred to a different chain) then it is available for withdrawal by the depositor’s PlasmaChain account.

Finally, using his PlasmaChain account, Charlie can claim this token through the PlasmaChain 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 PlasmaChain wallet for security, he would issue a transfer request from the PlasmaChain 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 PlasmaChain 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 PlasmaChain testnet (extdev).

The Rinkeby Transfer Gateway address as of this writing is: 0x6f7Eb868b2236638c563af71612c9701AC30A388

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 PlasmaChain is somewhat easier. You only need to sign the request to the PlasmaChain Gateway to register your contract with the same key that you used to deploy the contract. The PlasmaChain 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 a platform for building highly scalable DPoS sidechains to Ethereum, with a focus on large-scale games and social apps.

Want more info? Start here.

Fan of blockchain gaming? Check out Zombie Battleground, the world’s first desktop and mobile card game that runs fully on its own blockchain.

And if you enjoyed this article and want to stay in the loop, go ahead and sign up for our private mailing list.