StarkNet messaging bridge

Welcome! This is an automated workshop that will explain how to use the StarkNet L1 <-> L2 messaging bridge to create powerful cross layer applications.

It is aimed at developers that:

• Understand Cairo syntax
• Understand the Solidity syntax
• Understand the ERC20 token standard
• Understand the ERC721 standard

Introduction

Disclaimer

​ Don't expect any kind of benefit from using this, other than learning a bunch of cool stuff about StarkNet, the first general purpose validity rollup on the Ethereum Mainnnet. ​ StarkNet is still in Alpha. This means that development is ongoing, and the paint is not dry everywhere. Things will get better, and in the meanwhile, we make things work with a bit of duct tape here and there! ​

How it works

The goal of this tutorial is for you to create and deploy contracts on StarkNet and Ethereum that will interact with each other. In other words, you will create your own L1 <-> L2 bridge.

Your progress will be check by an evaluator contract, deployed on StarkNet, which will grant you points in the form of ERC20 tokens.

Each exercise will require you to add functionnality to your bridge.

• The first part allows you to send messages back and forth from L1 to L2, without necessarily having to code.
• The second part requires you to code smart contracts on L1 and L2 that are able to send messages to L2 and L1 counterparts.
• The second part requires you to code smart contracts on L1 and L2 that are able to receive messages from L2 and L1 counterparts.

For each exercise, you will have to write a new version on your contract, deploy it, and submit it to the evaluator for correction. ​ ​

Where am I?

This workshop is the fourth in a series aimed at teaching how to build on StarkNet. Checkout out the following:

Providing feedback & getting help

Once you are done working on this tutorial, your feedback would be greatly appreciated!

Please fill out this form to let us know what we can do to make it better.

​ And if you struggle to move forward, do let us know! This workshop is meant to be as accessible as possible; we want to know if it's not the case.

​ Do you have a question? Join our Discord server, register, and join channel #tutorials-support ​

Contributing

This project can be made better and will evolve as StarkNet matures. Your contributions are welcome! Here are things that you can do to help:

• Create a branch with a translation to your language
• Correct bugs if you find some
• Add an explanation in the comments of the exercise if you feel it needs more explanation

​

Getting ready to work

Step 1 - Clone the repo

git clone https://github.com/starknet-edu/starknet-messaging-bridge
cd starknet-messaging-bridge

Step 2 - Set up your environment

There are two ways to set up your environment on StarkNet: a local installation, or using a docker container

• For Mac and Linux users, we recommend either
• For windows users we recommand docker

For a production setup instructions we wrote this article.

Option A - Set up a local python environment

• Set up the environment following these instructions
• Install OpenZeppelin's cairo contracts.

pip install openzeppelin-cairo-contracts

Option B - Use a dockerized environment

• Linux and macos

for mac m1:

alias cairo='docker run --rm -v "$PWD":"$PWD" -w "$PWD" shardlabs/cairo-cli:latest-arm'

for amd processors

alias cairo='docker run --rm -v "$PWD":"$PWD" -w "$PWD" shardlabs/cairo-cli:latest'

• Windows

docker run --rm -it -v ${pwd}:/work --workdir /work shardlabs/cairo-cli:latest

Step 3 -Test that you are able to compile the project

starknet-compile contracts/Evaluator.cairo

​ ​

Working on the tutorial

Workflow

L2 -> L1 communication takes ~30 mins so it is recommended to send the messages from L2 to L1 as soon as possible and to do the exercises on L1 in the meantime.

To do this tutorial you will have to interact with the Evaluator.cairo contract. To validate an exercise you will have to

• Read the evaluator code to figure out what is expected of your contract
• Customize your contract's code
• Deploy it to StarkNet's testnet. This is done using the CLI.
• Register your exercise for correction, using the submit_exercise function on the evaluator. This is done using Voyager.
• Call the relevant function on the evaluator contract to get your exercise corrected and receive your points. This is done using Voyager.
• There is also an evaluator contract on L1, that will check your solidity work. The workflow to use it is the same as above, only on L1.

Exercises & Contract addresses

Tasks list

Exercise 0 - Send an L2→L1→L2 message with existing contracts (2 pts)

Use a predeployed contract to mint ERC20 tokens on L1 from L2. A secret message is passed with the messages; be sure to find it in order to collect your points.

• Call function ex_0_a of L2 Evaluator
  • You need to specify an L1 address, and an amount of ERC20 to mint
  • The secret message is sent from L2 to L1 at this stage.
• Call mint of L1 DummyToken
  • You need to show that you know the secret value at this step
• Call i_have_tokens of L1 DummyToken
  • This function checks that you have indeed been able to mint ERC20 tokens, and will then send a message back to L2 to credit your points
  • This is done using ex_0_b of the L2 evaluator

Exercise 1 - Send an L2→L1 message with your contract (2 pts)

Write and deploy a contract on L2 that sends messages to L1.

• Write a contract on L2 that will send a message to L1 MessagingNft and trigger createNftFromL2
  • Your function should be called create_l1_nft_message
• Deploy your contract
• Submit the contract address to L2 Evaluator by calling its submit_exercise
• Call ex1a of L2 Evaluator to trigger the message sending to L2
• Call createNftFromL2 of L1 MessagingNft to trigger the message consumption on L1
  • L1 MessagingNft sends back a message to L2 to credit your points on L2

Exercise 2 - Send an L1→L2 message with your contract (2 pts)

Write and deploy a contract on L1 that sends messages to L2.

• Write a contract on L1 that will send a message to L2 Evaluator and trigger ex2
  • You can check how L1 MessagingNft sends a message to L2 to get some ideas
  • You can get latest address of the StarkNet Core Contract Proxy on Goerli by running starknet get_contract_addresses --network alpha-goerli in your CLI
  • Learn how to get the selector of a StarkNet contract function
• Deploy your contract
• Trigger the message sending on L1. Your points are automatically attributed on L2.

Exercise 3 - Receive an L2→L1 message with your contract (2 pts)

• Write a contract on L1 that will receive a message from from function ex3_a.
  • Make sure your contract is able to handle the message.
  • Your message consumption function should be called consumeMessage
• Deploy your L1 contract
• Call ex3_a of L2 Evaluator to send an L2→L1 message
• Call ex3of L1 Evaluator, which triggers message consumption from your L1 contract
  • L1 evaluator will also send back a message to L2 to distribute your points

Exercise 4 - Receive an L1→L2 message with your contract (2 pts)

• Write a L2 contract that is able to receive a message from ex4 of L1 Evaluator
  • You can name your function however you like, since you provide the function selector as a parameter on L1
• Deploy your contract on L2
• Call ex4 of L1 Evaluator to send the random value out to your L2 contract
• Call ex4_b of L2 Evaluator that will check you completed your work correctly and distribute your points

Annex - Useful tools and ressources

Converting data to and from decimal

To convert data to felt use the utils.py script To open Python in interactive mode after running script

python -i utils.py

>>> str_to_felt('ERC20-101')
1278752977803006783537

Checking your progress & counting your points

​ Your points will get credited in your wallet; though this may take some time. If you want to monitor your points count in real time, you can also see your balance in voyager! ​

• Go to the ERC20 counter in voyager, in the "read contract" tab
• Enter your address in decimal in the "balanceOf" function

You can also check your overall progress here ​

Transaction status

​ You sent a transaction, and it is shown as "undetected" in voyager? This can mean two things: ​

• Your transaction is pending, and will be included in a block shortly. It will then be visible in voyager.
• Your transaction was invalid, and will NOT be included in a block (there is no such thing as a failed transaction in StarkNet). ​ You can (and should) check the status of your transaction with the following URL https://alpha4.starknet.io/feeder_gateway/get_transaction_receipt?transactionHash= , where you can append your transaction hash. ​

Articles & documentation

• Messaging Mechanism | StarkNet Docs
• Interacting with L1 contracts | StarkNet Documentation
• Sample Project: StarkNet graffiti | GitHub
• Thread on StarkNet ⇄ Ethereum Messaging | Twitter