Avalanche Warp Navigator

A Navigator is a [...] Human mutant who possesses the Navigator Gene. This gives a Navigator the unique ability to navigate a faster-than-light starship accurately through [the Warp]. - Warhammer 40k Wiki

Avalanche Warp Navigator is an experimental feature of the Ash Rust CLI that allows to monitor/decode all the messages sent through Avalanche Warp Messaging between Avalanche Subnet-EVM chains.

This project was created during Avalanche Hackathon 2023 (HK) on 2023-08-07 and is competing in the Track 3: Dev Tooling.

The repository contains all the resources required to:

• Interact with the HolyTerra EVM chain deployed on Fuji to send Warp messages and use Avalanche Warp Navigator to monitor/decode them!
• Or setup a local environment with a Warp enabled Subnet to run Avalanche Warp Navigator!

Table of Contents

• Use Avalanche Warp Navigator on HolyTerra (Fuji)
  • Prerequisites
  • Warpspace Subnet information
  • Setup
  • Create a wallet and airdrop PSYCHIC tokens
  • Send Warp messages from HolyTerra
  • Monitor/decode Warp messages from HolyTerra
• Avalanche Warp Messages format
• Use Avalanche Warp Navigator locally
  • Prerequisites
  • Local environment architecture
  • Environment setup
  • Interact with Avalanche Warp Messaging
• Repository content
• Code and contributions part of the project

Use Avalanche Warp Navigator on HolyTerra (Fuji)

Prerequisites

To use Avalanche Warp Navigator on HolyTerra you need to install Ash CLI in version 0.3.0-alpha (see Ash CLI Installation).

Warpspace Subnet information

For the purpose of this hackathon, the Ash team deployed the Warpspace Subnet on Fuji with 2 Warp-enabled Subnet-EVM chains: HolyTerra (in ref. to Terra) and Fenris (in ref. to Fenris). Here is the Subnet information:

Subnet '27FCSEqR5nE9pu255fqrJZZQDNt5Cg4P2B86ifD97KRunhMgic':
  Type: Permissioned
  Control keys: ["P-fuji1eg9uk9nllt8a26s7ynnxkm32mx6t0pyln9tawg"]
  Threshold:    1
  Blockchains list (2):
  - 'HolyTerra':
    ID:      qgchaJrK1YzWZTYbQ4MCcoKUAgga1qU38odx7XA78iae8yQhr
    VM ID:   jvFWMths2qLjsZgbyEKx82PkQv2YWR4rotjQfxV55vLLogjNA
    VM type: SubnetEVM
    RPC URL: https://validator01.ash-test.center/ext/bc/qgchaJrK1YzWZTYbQ4MCcoKUAgga1qU38odx7XA78iae8yQhr/rpc
  - 'Fenris':
    ID:      2VDAzBtDc2Rgzfm3dfu9bjFrJX2b95zcKwBcN426x3wDTz8JeG
    VM ID:   jvFWMths2qLjsZgbyEKx82PkQv2YWR4rotjQfxV55vLLogjNA
    VM type: SubnetEVM
    RPC URL: https://validator01.ash-test.center/ext/bc/2VDAzBtDc2Rgzfm3dfu9bjFrJX2b95zcKwBcN426x3wDTz8JeG/rpc
  Validators list (5):
  - NodeID-FhFWdWodxktJYq884nrJjWD8faLTk9jmp
  - NodeID-QC741RWyWherFvfXhWfB2KttpJEHKxZDS
  - NodeID-23Rau2xyULqtEmCb3CsQa1WhqYK3zG8Z3
  - NodeID-PXmtxGdX1Aab5Rh1yZbeGbkaTVaqmgQvG
  - NodeID-74aTSN8C4dJj1cgwNoK6jMAt4uNhRWHf7

The chains are deployed using a custom build of the Subnet-EVM by the Ash team: Warp-enabled Subnet-EVM.

The HolyTerra chain has been provided with:

• A Blockscout explorer avaiable at https://explorer.holyterra.ash-test.center
• A Faucet available at https://faucet.holyterra.ash-test.center

Setup

# Clone the repo
git clone https://github.com/AshAvalanche/avalanche-warp-navigator.git --recurse-submodules
cd avalanche-warp-navigator

Create a wallet and airdrop PSYCHIC tokens

Before sending Warp messages, you need a wallet with PSYCHIC energy (=tokens) on the HolyTerra chain:

1. Create a new wallet and get its public EVM address:

# Use the Ash CLI to create a new wallet
# Save the private key to a local file for later use
ash avalanche wallet generate --json | jq -r '.hex' > .private-key.txt

# Set environment variable for the Ash CLI
export ASH_CONFIG=ash-conf/fuji.yml
export AVALANCHE_NETWORK=fuji
export AVALANCHE_PRIVATE_KEY=$(cat .private-key.txt)

# Get the public EVM address of the wallet
ash avalanche wallet info -e hex
# Wallet information:
#   X-Chain address: X-fuji10448z83ddzpua8vyst3fvtemwnn2lgxeuu0z7h
#   P-Chain address: P-fuji10448z83ddzpua8vyst3fvtemwnn2lgxeuu0z7h
#   EVM address:     0xEd19d15da88048CA9620ED15a2B67a543cCa6C30    <-- This address

2. Claim some PSYCHIC tokens from the faucet
   1. Go to https://faucet.holyterra.ash-test.center
   2. Paste the EVM address of your wallet
   3. Click on REQUEST 2 PSYCHIC:
      
   4. Check that the transaction was successful on the explorer

Send Warp messages from HolyTerra

To send Warp messages, we interacting directly with the WarpMessenger stateful precompile using Hardhat tasks on the holyTerra network:

# Install dependencies
cd contracts
npm install

# Get the bytes32 blockchain ID of the Subnet as seen by WarpMessenger
npx hardhat warpMessenger:getBlockchainID --network holyTerra

# Send a Warp message to your address on the 'Fenris' chain
npx hardhat warpMessenger:sendWarpMessage \
  --destinationchainid 0xc3c002f116bcbb3e9d9d73e57557c316c534d4f884b83e56609b66334d988a21 \
  --destinationaddress 0xEd19d15da88048CA9620ED15a2B67a543cCa6C30 \
  --message 'For the Emperor!' --network holyTerra

Note: AVALANCHE_PRIVATE_KEY has to be set (see previous section).

Monitor/decode Warp messages from HolyTerra

Now that we have sent a message, we can use avalanche warp navigate to decode it!

# Go back to the root of the repo
cd ..

# Get all the Warp messages sent from the 'HolyTerra' chain since block 0
ash avalanche warp navigate HolyTerra

# If you want to only see the message you sent, you can use the `--from-block` and `--to-block` options and use the block number of the transaction
ash avalanche warp navigate HolyTerra --from-block 4 --to-block 4

Here is your message with its decoded payloads! 🎉

To learn more about the Warp message format, see Avalanche Warp messages format.

Avalanche Warp Messages format

Let's explain the different parts of a Warp message with the example of the message sent from HolyTerra to Fenris:

• Status: the message status. It can be Sent or Signed by X validators. This is computed by the Ash CLI by querying each validator for its signature of the message.

  Note: the Ash CLI might not be able to query the validators on Fuji. In this case, the status will be Sent even if the message has technically been signed by the validators.

• Unsigned message (UnsignedMessage): all the bytes of the message except the signature and the ID
  • ID: the ID of the message. It is actually a SHA256 hash of the unsigned message.
  • NetworkID: the ID of the Avalanche network the message is sent from (e.g. 5 for Fuji)
  • SourceChainID: the CB58 ID of the chain the message is sent from (e.g. qgchaJrK1YzWZTYbQ4MCcoKUAgga1qU38odx7XA78iae8yQhr for HolyTerra)
  • Payload: the message payload as arbitrary bytes. In our case, it is an AddressedPayload of the Subnet-EVM.
• Verified message: the message as it will be consumed on a destination chain. In our case it is the Subnet-EVM WarpMessage that will be outputed by the getVerifiedMessage precompile function.

For more information of how messages are generated, signed and reveived, see subnet-evm Avalanche Warp Messaging README.

Use Avalanche Warp Navigator locally

Prerequisites

To use Avalanche Warp Navigator locally you need to install:

• Multipass (see Install Multipass)
• Terraform (see Install Terraform)
• jq (see Download jq)
• Ash CLI in version 0.3.0-alpha (see Ash CLI Installation)

Local environment architecture

The local environment is composed of:

• 5 Avalanche nodes running on Multipass VMs (deployed using ansible-avalanche-getting-started)
• 1 Blockscout explorer running on a Multipass VM
• 1 Subnet with 2 EVM chains: HolyTerra and Fenris

The chains are deployed using a custom build of the Subnet-EVM by the Ash team: Warp-enabled Subnet-EVM.

Environment setup

Bootstrap the local network

Run scripts/local_network.sh to bootstrap a local Avalanche test network with 5 nodes and create a Subnet with 2 EVM chains:

# Clone the repo
git clone https://github.com/AshAvalanche/avalanche-warp-navigator.git --recurse-submodules

cd avalanche-warp-navigator
./scripts/local_network.sh

Run scripts/explorer.sh to deploy the Blockscout explorer:

./scripts/explorer.sh

Environment cleanup

Run scripts/cleanup.sh to destroy the local network and the Blockscout explorer.

./scripts/cleanup.sh

Interact with Avalanche Warp Messaging

Send Warp messages

See Sending Warp messages from HolyTerra for instructions on how to send Warp messages from the HolyTerra chain. Replace the --network option with local to target the local Avalanche network.

Monitor/decode Warp messages

1. Set environment variables for the Ash CLI:

   export ASH_CONFIG=ash-conf/local.yml
   export AVALANCHE_NETWORK=local

2. See Monitor/decode Warp messages from HolyTerra for instructions on how to monitor/decode Warp messages from the HolyTerra chain.

Repository content

• ansible-avalanche-getting-started/: Ansible playbook to bootstrap a local Avalanche test network with 5 nodes (Git submodule)
• ash-conf/: Ash CLI configuration files for the local (autogenerated) and Fuji networks
• contracts/: Solidity contracts to interact with stateful precompiles taken from subnet-evm/contracts.
• scripts/: Bash scripts to bootstrap/cleanup the local network and deploy the Blockscout explorer

Code and contributions part of the project

In complement to this repository, the following repositories contain code part of the project:

• AshAvalanche/ash-rs: branch avalanche-warp-navigator
• AshAvalanche/ansible-avalanche-getting-started: branch avalanche-warp-navigator

When developing the Navigator feature, we contributed to Subnet-EVM:

• Subnet-EVM Warp messages: message encoding in SendWarpMessage event logs (discussion)
• Cannot aggregate Warp message signatures with warp_getAggregateSignature (issue)