Welcome to the StarkEx Playground tutorial. StarkEx Playground is a StarkEx deployment on the Goerli testnet that provides a simple demonstration of the StarkEx scalability solution. You can use the playground to:
easily submit transactions to StarkEx,
see these transactions in a StarkEx batch, and
watch how the state, including your transactions, is updated on-chain in the StarkEx contract.
If you have questions, at any step of the way, please contact us at [email protected].
The StarkEx Playground package provides a list of valid, pre-prepared StarkEx transactions, such as deposits, withdrawals, settlements, and mint requests. These transactions apply to pre-registered StarkEx users. You also get a Player script that submits these transactions to StarkEx.
Simply run the Player and:
observe the transactions as they propagate through StarkEx,
query StarkEx to see the latest off-chain batch with your transactions in it, and
watch as a new on-chain state is formed in the StarkEx smart contract.
Download the package here:
Your Playground package includes the following files:
txs.json – A list of L2 transactions, including deposits, settlements, and withdrawals that are executed from the Vault range that you were assigned. These transactions are valid and signed by users that were registered to the system in advance using their
starkKey. This allows you to observe a full StarkEx operation cycle without getting into the details of the exact transaction for each operation.
player.py – A python script that checks and submits the list of transactions specified in txs.json to the StarkEx contract and the StarkEx off-chain service. These transactions are then submitted to the L2 StarkEx service, executed, and added to the batch to be submitted as a new on-chain state.
An Infura endpoint link for Goerli. If you don’t have one, please open an Ethereum account at https://infura.io/ to acquire a link.
Docker (Linux install via:
apt install -y docker.io).
A Goerli Eth account with enough Eth to pay for the deposit transaction gas. For your convenience, you can try this faucet.
Download the StarkEx_Playground.zip, open it, and change the directory to the StarkEx_Playground directory.
Build and run a Docker image by running the following command (see also, the REAME.md):
docker build -t <MEMORABLE_NAME> .
docker run -it <MEMORABLE_NAME>
Run the Player script by running the following command:
./player.py --txs txs.json --node_url <your infura node> --funder_private_key <your Goerli private key> --verboseYou can export your Goerli private key from MetaMask:
select "Account Details" from the menu next to the account address
select "Export Private Key" and provide your MetaMask password
You will now see output prints of two types:
On-chain deposit transactions' description of the StarkEx contract with Etherscan links (Fig. 1).
Off-chain StarkEx transactions' description containing the transaction type and unique tx_id (Fig. 2).
That’s it; you've submitted your first StarkEx transactions. Congratulations! You will be able to see the on-chain state update in a few minutes.
The file txs.json contains an explicit list of transactions in StarkEx API format.
Let’s look at the following Deposit transaction as an example:
stark_key is the cryptographic key that lets you sign transactions
amount is the value of the transfer
token_id is the ERC-20 token StarkEx identifier
vault_id is the account number in StarkEx that you are depositing to – this account must be an account that is associated with the specified
the final argument describes the transaction type submitted, in this case, a DepositRequest.
You can check the state in StarkEx smart contract at https://goerli.etherscan.io/address/0x471bDA7f420de34282AB8AF1F5F3DAf2a4C09746. If your batch is already submitted on-chain (allow about 5 minutes), you will see a state update transaction.
You can also check what happened in the Verifier smart contract, which verifies STARK proofs, at https://goerli.etherscan.io/address/0xAB43bA48c9edF4C2C4bB01237348D1D7B28ef168. You will see that a new proof was submitted for verification. Once the proof is verified, a new Fact is registered on-chain approving the proof validation. The StarkEx contract checks this Fact before updating the state.
Vault balances derive directly from the history of the transactions that were submitted to StarkEx batches. This information can be queried off-chain by using the Feeder Gateway StarkEx API.
This can be done by running the following commands:
Get the last batch_id:
wget -nv -q -O- https://gw.playground-v2.starkex.co/feeder_gateway/get_last_batch_id
The output of this command is a unique identifier that should be used as input for the next command.
Get the content through the Feeder Gateway of the batch_id that was provided in the previous step (or query previous batches):
wget -nv -q -O- https://gw.playground-v2.starkex.co/feeder_gateway/get_batch_info?batch_id=<batch_id>
The output will be similar to the one presented in Fig. 3. Lines 2–14 provide the information about the order tree root and the vault tree root, which represents the state. Lines 21 onward display the
information about the transactions in the batch; you will be able to spot your transactions using the tx_id that you saw in the Player script output (e.g., line 27). Pay close attention to the field was_replaced ; invalid transactions get the value true (as per the first and second transactions in Fig. 3; lines 28 and 40), valid transactions are not replaced, and are assigned the value false (line 52, Fig. 3.b). The StarkEx Playground is configured to skip the invalid transactions and not to replace them; however, in practice, this is a good indicator of whether the transaction was executed or not.
If you want to take it up a notch, you can modify the list of transactions by yourself or create a new list. You can see the detailed definition of the StarkEx API here. This requires you to be able to sign transactions with a STARK signature. Your user's
starkKeypairs are available at player_data.py. You can find the signature library here and an example of signing a limit order here.
Sure! Please contact us at [email protected].