The mechanism to natively read Ethereum data from Matic EVM chain is that of ‘State Sync’. In other words, this mechanism enables transfer of arbitrary data from Ethereum chain to Matic chain. The procedure that makes it possible is: Validators on the Heimdall layer are listening for a particular event —
StateSynced from a Sender contract, as soon as the event is picked, the
data that was passed in the event is written on the Receiver contract. Read more here.
The Sender and Receiver contract are required to be mapped on Ethereum — StateSender.sol needs to be aware of each sender and receiver. If you'd like to get the mapping done, please request a mapping here.
In the following walkthrough, we'll be deploying a Sender contract on Goerli (Ethereum testnet) and a Receiver contract on Mumbai (Matic's testnet) and then we'll be sending data from Sender and reading data on Receiver via web3 calls in a node script.
1. Deploy Sender contract
The sole purpose of Sender contract is to be able to call syncState function on the StateSender contract — which is Matic's state syncer contract - the StateSynced event of which Heimdall is listening to.
0xEAa852323826C71cd7920C3b4c007184234c3945 on Goerli
0x28e4F3a7f651294B9564800b2D01f35189A5bFbE on Ethereum Mainnet
To be able to call this function, let's first include it's interface in our contract:
Next, let's write our custom function that takes in the data we'd like to pass on to Matic and calls syncState
In the above function,
stateSenderContract is the address of the StateSender on the network you'll be deploying
Sender on. (eg., we'll be using
0xEAa852323826C71cd7920C3b4c007184234c3945 for Goerli), and
receiver is the contract that will receive the data we send from here.
It is recommended to use constructors to pass in variables, but for the purpose of this demo, we'll simply harcode these two addresses:
Following is how our Sender.sol looks like:
We're using a simple
states counter to keep track of the number of states sent via the Sender contract.
Use Remix to deploy the contract and keep a note of the address and ABI.
2. Deploy Receiver contract
Receiver contract is the one that is invoked by a Validator when the
StateSynced event is emitted. The Validator invokes the function
onStateReceiveon the receiver contract to submit the data. To implement it, we first import StateReceiver interface and write down our custom logic — to interpret the tranferred data inside onStateReceive.
Following is how our Receiver.sol looks like:
The function simply assigns the last received State Id and data to variables. StateId is a simple unique reference to the transferred state (a simple counter).
Deploy your Receiver.sol on Matic's testnet and keep a note of the address and ABI
3. Getting your Sender and Receiver mapped
You can either use the already deployed addresses (mentioned above) for sender and receiver, or deploy your custom contracts and request a mapping done here: https://mapper.matic.today/
4. Sending and Receiving data
Now that we have our contracts in place and mapping done, we'll be writing a simple node script to send arbitrary hex bytes, receive them on matic network and interpret the data!
4.1 Setup your script
We'll first initialise our web3 objects, wallet to make the transactions and contracts
We're using @maticnetwork/meta package for the RPCs, the package isn't a requirement to run the script.
main objects refer to the web3 object initialised with Matic's and Ropsten's RPC respectively.
receiver objects refer to the contract objects of Sender.sol and Receiver.sol that we deployed in Step 1 and 2.
4.2 Sending data
Next, let's setup our functions to create bytestring of the data and send it via Sender contract:
getData will convert an ascii string (eg.,
Hello World !) to a string of bytes (eg.,
0x48656c6c6f20576f726c642021); while the function
data (an ascii string), calls
getData and passes on the bytestring to sender contract
4.3 Receiving data
Next, we'll be checking for received data on Receiver.sol.
It should take ~7-8 minutes for the state sync to execute.
Add the following functions to check (a) number of sent states from Sender and (b) Last received state on Receiver.
checkReceiver simply calls the variables we defined in the contract — which would be set as soon as the Validator calls
onStateReceive on the contract. The
getString function simply interprets the bytestring (converts it back to ascii)
Finally, we'll write up a method to execute our functions:
4.4 Putting it all together!
This is how our test script looks like:
4.5 Let's run the script
Successful execution of the above script provide an output as: