# Asset Requirements (/docs/builderkit/asset-requirements)

---
title: Asset Requirements
description: "Required assets and file structure for chain and token logos."
---

# Asset Requirements

BuilderKit requires specific asset files for displaying chain and token logos. These assets should follow a standardized file structure and naming convention.

## Chain Logos

Chain logos are used by components like `ChainIcon`, `ChainDropdown`, and `TokenIconWithChain`.

### File Structure

Chain logos should be placed at:
```
/chains/logo/{chain_id}.png
```

### Examples
```
/chains/logo/43114.png  // Avalanche C-Chain
/chains/logo/43113.png  // Fuji Testnet
/chains/logo/173750.png // Echo L1
```

### Requirements

- Format: PNG with transparency
- Dimensions: 32x32px (minimum)
- Background: Transparent
- Shape: Circular or square with rounded corners
- File size: < 100KB

## Token Logos

Token logos are used by components like `TokenIcon`, `TokenChip`, and `TokenRow`.

### File Structure

Token logos should be placed at:
```
/tokens/logo/{chain_id}/{address}.png
```

### Examples
```
/tokens/logo/43114/0x1234567890123456789012345678901234567890.png  // Token on C-Chain
/tokens/logo/43113/0x5678901234567890123456789012345678901234.png  // Token on Fuji
```

### Requirements

- Format: PNG with transparency
- Dimensions: 32x32px (minimum)
- Background: Transparent
- Shape: Circular or square with rounded corners
- File size: < 100KB

## Directory Structure

Your public assets directory should look like this:
```
public/
├── chains/
│   └── logo/
│       ├── 43114.png
│       ├── 43113.png
│       └── 173750.png
└── tokens/
    └── logo/
        ├── 43114/
        │   ├── 0x1234....png
        │   └── 0x5678....png
        └── 43113/
            ├── 0x9012....png
            └── 0xabcd....png
```

# Custom Chain Setup (/docs/builderkit/chains)

---
title: Custom Chain Setup
description: "Configure custom Avalanche L1 chains in your application."
---

# Custom Chain Setup

Learn how to configure custom Avalanche L1 chains in your BuilderKit application.

## Chain Definition

Define your custom L1 chain using `viem`'s `defineChain`:

```tsx
import { defineChain } from "viem";

export const myL1 = defineChain({
    id: 173750,  // Your L1 chain ID
    name: 'My L1',  // Display name
    network: 'my-l1',  // Network identifier
    nativeCurrency: {
        decimals: 18,
        name: 'Token',
        symbol: 'TKN',
    },
    rpcUrls: {
        default: {
            http: ['https://api.avax.network/ext/L1/rpc']
        },
    },
    blockExplorers: {
        default: { 
            name: 'Explorer', 
            url: 'https://explorer.avax.network/my-l1' 
        },
    },
    // Optional: Custom metadata
    iconUrl: "/chains/logo/my-l1.png",
    icm_registry: "0x..."  // ICM registry contract
});
```

## Provider Configuration

Add your custom L1 chain to the Web3Provider:

```tsx
import { Web3Provider } from '@avalabs/builderkit';
import { avalanche } from '@wagmi/core/chains';
import { myL1 } from './chains/definitions/my-l1';

function App() {
  return (
    <Web3Provider
      chains={[avalanche, myL1]}
      defaultChain={avalanche}
    >
      <YourApp />
    </Web3Provider>
  );
}
```

## Required Properties

| Property | Type | Description |
|----------|------|-------------|
| `id` | `number` | Unique L1 chain identifier |
| `name` | `string` | Human-readable chain name |
| `network` | `string` | Network identifier |
| `nativeCurrency` | `object` | Chain's native token details |
| `rpcUrls` | `object` | RPC endpoint configuration |
| `blockExplorers` | `object` | Block explorer URLs |

## Optional Properties

| Property | Type | Description |
|----------|------|-------------|
| `iconUrl` | `string` | Chain logo URL |
| `icm_registry` | `string` | ICM registry contract address |
| `testnet` | `boolean` | Whether the chain is a testnet |

## Example: Echo L1

Here's a complete example using the Echo L1:

```tsx
import { defineChain } from "viem";

export const echo = defineChain({
    id: 173750,
    name: 'Echo L1',
    network: 'echo',
    nativeCurrency: {
        decimals: 18,
        name: 'Ech',
        symbol: 'ECH',
    },
    rpcUrls: {
        default: {
            http: ['https://subnets.avax.network/echo/testnet/rpc']
        },
    },
    blockExplorers: {
        default: { 
            name: 'Explorer', 
            url: 'https://subnets-test.avax.network/echo' 
        },
    },
    iconUrl: "/chains/logo/173750.png",
    icm_registry: "0xF86Cb19Ad8405AEFa7d09C778215D2Cb6eBfB228"
});
```

# Contribute (/docs/builderkit/contribute)

---
title: Contribute
description: "Guide for contributing to BuilderKit by building hooks, components, and flows."
---

# Contributing to BuilderKit

We welcome contributions to BuilderKit! Whether you're fixing bugs, adding new features, or improving documentation, your help makes BuilderKit better for everyone.

## What You Can Contribute

### Hooks
Build reusable hooks that handle common Web3 functionality:
- Chain data management
- Token interactions
- Contract integrations
- State management
- API integrations

### Components
Create new UI components or enhance existing ones:
- Form elements
- Display components
- Interactive elements
- Layout components
- Utility components

### Flows
Design complete user journeys by combining components:
- Token swaps
- NFT minting
- Governance voting
- Staking interfaces
- Custom protocols

# Getting Started (/docs/builderkit/getting-started)

---
title: Getting Started
description: "Quick setup guide for BuilderKit in your React application."
---

Get started with BuilderKit in your React application.

## Installation

```bash
npm install @avalabs/builderkit
# or
yarn add @avalabs/builderkit
```

## Provider Setup

Wrap your application with the Web3Provider to enable wallet connections and chain management:

```tsx
import { Web3Provider } from '@avalabs/builderkit';
import { avalanche, avalancheFuji } from '@wagmi/core/chains';
import { echo } from './chains/definitions/echo';
import { dispatch } from './chains/definitions/dispatch';

// Configure chains
const chains = [avalanche, avalancheFuji, echo, dispatch];

function App() {
  return (
    <Web3Provider
      appName="My DApp"
      projectId="YOUR_PROJECT_ID"
      chains={chains}
    >
      <YourApp />
    </Web3Provider>
  );
}
```

## Next Steps

- Learn about [Token Configuration](/docs/builderkit/tokens)
- Explore [Core Components](/docs/builderkit/components/control)
- Check out [Pre-built Flows](/docs/builderkit/flows/ictt) 

# Introduction (/docs/builderkit)

---
title: Introduction
description: "A comprehensive React component library for building Web3 applications on Avalanche."
---

BuilderKit is a powerful collection of React components and hooks designed specifically for building Web3 applications on Avalanche. It provides everything you need to create modern, user-friendly blockchain applications with minimal effort.

## Ready to Use Components

BuilderKit offers a comprehensive set of components that handle common Web3 functionalities:

- **Control Components**: Buttons, forms, and wallet connection interfaces
- **Identity Components**: Address displays and domain name resolution
- **Token Components**: Balance displays, inputs, and price conversions
- **Input Components**: Specialized form inputs for Web3 data types
- **Chain Components**: Network selection and chain information displays
- **Transaction Components**: Transaction submission and status tracking
- **Collectibles Components**: NFT displays and collection management

## Powerful Hooks

BuilderKit provides hooks for seamless integration with Avalanche's ecosystem:

### Blockchain Interaction
Access and manage blockchain data, tokens, and cross-chain operations with hooks for chains, tokens, DEX interactions, and inter-chain transfers.

### Precompile Integration
Easily integrate with Avalanche's precompiled contracts for access control, fee management, native minting, rewards, and cross-chain messaging.


## Getting Started

Get started quickly by installing BuilderKit in your React application:

```bash
npm install @avalabs/builderkit
# or
yarn add @avalabs/builderkit
```

Check out our [Getting Started](/docs/builderkit/getting-started) guide to begin building your Web3 application. 

# Token Configuration (/docs/builderkit/tokens)

---
title: Token Configuration
description: "Guide for configuring tokens in BuilderKit flows."
---

# Token Configuration

BuilderKit flows require proper token configuration to function correctly. This guide explains the required fields for different token configurations.

## Basic Token Structure

All tokens in BuilderKit share a common base structure with these required fields:

```typescript
interface BaseToken {
  // Contract address of the token, use "native" for native chain token
  address: string;      
  
  // Human-readable name of the token
  name: string;         
  
  // Token symbol/ticker
  symbol: string;       
  
  // Number of decimal places the token uses
  decimals: number;     
  
  // ID of the chain where this token exists
  chain_id: number;     
}
```

## ICTT Token Fields

ICTT tokens extend the base structure with additional fields for cross-chain functionality:

```typescript
interface ICTTToken extends BaseToken {
  // Whether this token can be used with ICTT
  supports_ictt: boolean;  
  
  // Address of the contract that handles transfers
  transferer?: string;     
  
  // Whether this token instance is a transferer
  is_transferer?: boolean; 
  
  // Information about corresponding tokens on other chains
  mirrors: {
    // Contract address of the mirrored token
    address: string;       
    
    // Transferer contract on the mirror chain
    transferer: string;    
    
    // Chain ID where the mirror exists
    chain_id: number;      
    
    // Decimal places of the mirrored token
    decimals: number;      
    
    // Whether this is the home/original chain
    home?: boolean;        
  }[];
}
```

## Field Requirements

### Base Token Fields
- `address`: Must be a valid contract address or "native"
- `name`: Should be human-readable
- `symbol`: Should match the token's trading symbol
- `decimals`: Must match the token's contract configuration
- `chain_id`: Must be a valid chain ID

### ICTT-Specific Fields
- `supports_ictt`: Required for ICTT functionality
- `transferer`: Required if token supports ICTT
- `is_transferer`: Optional, indicates if token is a transferer
- `mirrors`: Required for ICTT, must contain at least one mirror configuration

### Mirror Configuration Fields
- `address`: Required, contract address on mirror chain
- `transferer`: Required, transferer contract on mirror chain
- `chain_id`: Required, must be different from token's chain_id
- `decimals`: Required, must match token contract
- `home`: Optional, indicates original/home chain

# Getting Started (/docs/avalanche-l1s)

---
title: Getting Started
description: As you begin your Avalanche L1 journey, it's useful to look at the lifecycle of taking an Avalanche L1 from idea to production.
---

## Figure Out Your Needs

The first step of planning your Avalanche L1 is determining your application's needs. What features do you need that the Avalanche C-Chain doesn't provide? 

### When to Choose an Avalanche L1

Building your own Avalanche L1 is a great choice when your project demands capabilities beyond those offered by the C-Chain. For instance, if you need the flexibility to use a custom gas token, require strict access control (for example, by only permitting users who are KYC-verified), or wish to implement a unique transaction fee model, then an Avalanche L1 can provide the necessary options. In addition, if having a completely sovereign network with its own governance and consensus mechanisms is central to your vision, an Avalanche L1 is likely the best path forward.

### Decide What Type of Avalanche L1 You Want

After confirming that an Avalanche L1 suits your project's requirements, the next step is to select the type of virtual machine (VM) that will power your blockchain. Broadly, you can choose among three options.

#### EVM-Based Avalanche L1s

The majority of Avalanche L1s are utilizing the Ethereum Virtual Machine. They support Solidity smart contracts and standard [Ethereum APIs](/docs/api-reference/c-chain/api#ethereum-apis). Ava Labs' implementation, [Subnet-EVM](https://github.com/ava-labs/subnet-evm), is the most mature option available. It is recognized for its robust developer tooling and regular updates, making it the safest and most popular choice for building your blockchain.

#### Custom Avalanche L1s

Custom Avalanche L1s offer an open-ended interface that enables you to build any virtual machine you envision. Whether you fork an existing VM such as Subnet-EVM, integrate a non-Avalanche-native VM like Solana's, or build a completely new VM using any programming language you prefer, the choice is yours. For guidance on how to get started with VM development, see [Introduction to VMs](/docs/virtual-machines).

### Determine Tokenomics

Avalanche L1s are powered by gas tokens, and building your own blockchain gives you the flexibility to determine which token to use and how to distribute it. Whether you decide to leverage AVAX, adapt an existing C-Chain token, or launch a new token entirely, you'll need to plan the allocation of tokens for validator rewards, establish an emission schedule, and decide whether transaction fees should be burned or redistributed as block rewards.

### Decide how to Customize Your Avalanche L1

Once you have selected your virtual machine, further customization may be necessary to align the blockchain with your specific needs. This might involve configuring the token allocation in the genesis block, setting gas fee rates, or making changes to the VM's behavior through precompiles. Such customizations often require careful iterative testing to perfect. For detailed instructions, refer to [Customize Your EVM-Powered Avalanche L1](/docs/avalanche-l1s/upgrade/customize-avalanche-l1).

### Available Subnet-EVM Precompiles

The Subnet-EVM provides several precompiled contracts that you can use in your Avalanche L1 blockchain:

- [AllowList Interface](/docs/avalanche-l1s/evm-configuration/allowlist) - A reusable interface for permission management
- [Permissions](/docs/avalanche-l1s/evm-configuration/permissions) - Control contract deployment and transaction submission
- [Tokenomics](/docs/avalanche-l1s/evm-configuration/tokenomics) - Manage native token supply and minting
- [Transaction Fees & Validator Rewards](/docs/avalanche-l1s/evm-configuration/transaction-fees) - Configure fee parameters and reward mechanisms
- [Warp Messenger](/docs/avalanche-l1s/evm-configuration/warpmessenger) - Perform cross-chain operations

# WAGMI Avalanche L1 (/docs/avalanche-l1s/wagmi-avalanche-l1)

---
title: WAGMI Avalanche L1
description: Learn about the WAGMI Avalanche L1 in this detailed case study.
---

This is one of the first cases of using Avalanche L1s as a proving ground for changes in a production VM (Coreth). Many underestimate how useful the isolation of Avalanche L1s is for performing complex VM testing on a live network (without impacting the stability of the primary network).

We created a basic WAGMI Explorer [https://subnets-test.avax.network/wagmi](https://subnets-test.avax.network/wagmi) that surfaces aggregated usage statistics about the Avalanche L1.

- SubnetID: [28nrH5T2BMvNrWecFcV3mfccjs6axM1TVyqe79MCv2Mhs8kxiY](https://explorer-xp.avax-test.network/avalanche-l1/28nrH5T2BMvNrWecFcV3mfccjs6axM1TVyqe79MCv2Mhs8kxiY?tab=validators)
- ChainID: [2ebCneCbwthjQ1rYT41nhd7M76Hc6YmosMAQrTFhBq8qeqh6tt](https://testnet.avascan.info/blockchain/2ebCneCbwthjQ1rYT41nhd7M76Hc6YmosMAQrTFhBq8qeqh6tt)

### Network Parameters[​](#network-parameters "Direct link to heading")

- NetworkID: 11111
- ChainID: 11111
- Block Gas Limit: 20,000,000 (2.5x C-Chain)
- 10s Gas Target: 100,000,000 (~6.67x C-Chain)
- Min Fee: 1 Gwei (4% of C-Chain)
- Target Block Rate: 2s (Same as C-Chain)

The genesis file of WAGMI can be found [here](https://github.com/ava-labs/public-chain-assets/blob/1951594346dcc91682bdd8929bcf8c1bf6a04c33/chains/11111/genesis.json).

### Adding WAGMI to Core[​](#adding-wagmi-to-core "Direct link to heading")

- Network Name: WAGMI
- RPC URL: [https://subnets.avax.network/wagmi/wagmi-chain-testnet/rpc]
- WS URL: wss://avalanche-l1s.avax.network/wagmi/wagmi-chain-testnet/ws
- Chain ID: 11111
- Symbol: WGM
- Explorer: [https://subnets.avax.network/wagmi/wagmi-chain-testnet/explorer]

<Callout title="Note">
This can be used with other wallets too, such as MetaMask.
</Callout>

Case Study: WAGMI Upgrades[​](#case-study-wagmi-upgrades "Direct link to heading")
----------------------------------------------------------------------------------

This case study uses [WAGMI](https://subnets-test.avax.network/wagmi) Avalanche L1 upgrade to show how a network upgrade on an EVM-based (Ethereum Virtual Machine) Avalanche L1 can be done simply, and how the resulting upgrade can be used to dynamically control fee structure on the Avalanche L1.

### Introduction[​](#introduction "Direct link to heading")

[Subnet-EVM](https://github.com/ava-labs/subnet-evm) aims to provide an easy to use toolbox to customize the EVM for your blockchain. It is meant to run out of the box for many Avalanche L1s without any modification. But what happens when you want to add a new feature updating the rules of your EVM?

Instead of hard coding the timing of network upgrades in client code like most EVM chains, requiring coordinated deployments of new code, [Subnet-EVM v0.2.8](https://github.com/ava-labs/subnet-evm/releases/tag/v0.2.8) introduces the long awaited feature to perform network upgrades by just using a few lines of JSON in a configuration file.

### Network Upgrades: Enable/Disable Precompiles[​](#network-upgrades-enabledisable-precompiles "Direct link to heading")

Detailed description of how to do this can be found in [Customize an Avalanche L1](/docs/avalanche-l1s/upgrade/customize-avalanche-l1#network-upgrades-enabledisable-precompiles) tutorial. Here's a summary:

1. Network Upgrade utilizes existing precompiles on the Subnet-EVM:
    - ContractDeployerAllowList, for restricting smart contract deployers
    - TransactionAllowList, for restricting who can submit transactions
    - NativeMinter, for minting native coins
    - FeeManager, for configuring dynamic fees
    - RewardManager, for enabling block rewards
2. Each of these precompiles can be individually enabled or disabled at a given timestamp as a network upgrade, or any of the parameters governing its behavior changed.
3. These upgrades must be specified in a file named `upgrade.json` placed in the same directory where [`config.json`](/docs/avalanche-l1s/upgrade/customize-avalanche-l1#avalanchego-chain-configs) resides: `{chain-config-dir}/{blockchainID}/upgrade.json`.

### Preparation[​](#preparation "Direct link to heading")

To prepare for the first WAGMI network upgrade, on August 15, 2022, we had announced on [X](https://x.com/AaronBuchwald/status/1559249414102720512) and shared on other social media such as Discord.

For the second upgrade, on February 24, 2024, we had another announcement on [X](https://x.com/jceyonur/status/1760777031858745701?s=20).

### Deploying upgrade.json[​](#deploying-upgradejson "Direct link to heading")

The content of the `upgrade.json` is:

```json
{
  "precompileUpgrades": [
    {
      "feeManagerConfig": {
        "adminAddresses": ["0x6f0f6DA1852857d7789f68a28bba866671f3880D"],
        "blockTimestamp": 1660658400
      }
    },
    {
      "contractNativeMinterConfig": {
        "blockTimestamp": 1708696800,
        "adminAddresses": ["0x6f0f6DA1852857d7789f68a28bba866671f3880D"],
        "managerAddresses": ["0xadFA2910DC148674910c07d18DF966A28CD21331"]
      }
    }
  ]
}
```

With the above `upgrade.json`, we intend to perform two network upgrades:

1.  The first upgrade is to activate the FeeManager precompile:
    - `0x6f0f6DA1852857d7789f68a28bba866671f3880D` is named as the new Admin of the FeeManager precompile.
    - `1660658400` is the [Unix timestamp](https://www.unixtimestamp.com/) for Tue Aug 16 2022 14:00:00 GMT+0000 (future time when we made the announcement) when the new FeeManager change would take effect.
2.  The second upgrade is to activate the NativeMinter precompile:
    - `0x6f0f6DA1852857d7789f68a28bba866671f3880D` is named as the new Admin of the NativeMinter precompile.
    - `0xadFA2910DC148674910c07d18DF966A28CD21331` is named as the new Manager of the NativeMinter precompile. Manager addresses are enabled after Durango upgrades which occurred on February 13, 2024.
    - `1708696800` is the [Unix timestamp](https://www.unixtimestamp.com/) for Fri Feb 23 2024 14:00:00 GMT+0000 (future time when we made the announcement) when the new NativeMinter change would take effect.

Detailed explanations of feeManagerConfig can be found in [here](/docs/avalanche-l1s/upgrade/customize-avalanche-l1#configuring-dynamic-fees), and for the contractNativeMinterConfig in [here](/docs/avalanche-l1s/upgrade/customize-avalanche-l1#minting-native-coins).

We place the `upgrade.json` file in the chain config directory, which in our case is `~/.avalanchego/configs/chains/2ebCneCbwthjQ1rYT41nhd7M76Hc6YmosMAQrTFhBq8qeqh6tt/`. After that, we restart the node so the upgrade file is loaded.

When the node restarts, AvalancheGo reads the contents of the JSON file and passes it into Subnet-EVM. We see a log of the chain configuration that includes the updated precompile upgrade. It looks like this:

```bash
INFO [02-22|18:27:06.473] <2ebCneCbwthjQ1rYT41nhd7M76Hc6YmosMAQrTFhBq8qeqh6tt Chain> github.com/ava-labs/subnet-evm/core/blockchain.go:335: Upgrade Config: {"precompileUpgrades":[{"feeManagerConfig":{"adminAddresses":["0x6f0f6da1852857d7789f68a28bba866671f3880d"],"blockTimestamp":1660658400}},{"contractNativeMinterConfig":{"adminAddresses":["0x6f0f6da1852857d7789f68a28bba866671f3880d"],"managerAddresses":["0xadfa2910dc148674910c07d18df966a28cd21331"],"blockTimestamp":1708696800}}]}
```

We note that `precompileUpgrades` correctly shows the upcoming precompile upgrades. Upgrade is locked in and ready.

### Activations[​](#activations "Direct link to heading")

When the time passed 10:00 AM EDT August 16, 2022 (Unix timestamp 1660658400), the `upgrade.json` had been executed as planned and the new FeeManager admin address has been activated. From now on, we don't need to issue any new code or deploy anything on the WAGMI nodes to change the fee structure. Let's see how it works in practice!

For the second upgrade on February 23, 2024, the same process was followed. The `upgrade.json` had been executed after Durango, as planned, and the new NativeMinter admin and manager addresses have been activated.

### Using Fee Manager[​](#using-fee-manager "Direct link to heading")

The owner `0x6f0f6DA1852857d7789f68a28bba866671f3880D` can now configure the fees on the Avalanche L1 as they see fit. To do that, all that's needed is access to the network, the private key for the newly set manager address and making calls on the precompiled contract.

We will use [Remix](https://remix.ethereum.org/) online Solidity IDE and the [Core Browser Extension](https://support.avax.network/en/articles/6066879-core-extension-how-do-i-add-the-core-extension). Core comes with WAGMI network built-in. MetaMask will do as well but you will need to [add WAGMI](/docs/avalanche-l1s/wagmi-avalanche-l1) yourself.

First using Core, we open the account as the owner `0x6f0f6DA1852857d7789f68a28bba866671f3880D`.

Then we connect Core to WAGMI, Switch on the `Testnet Mode` in `Advanced` page in the hamburger menu:

![Core Testnet mode](/images/wagmi1.png)

And then open the `Manage Networks` menu in the networks dropdown. Select WAGMI there by clicking the star icon:

![Core network selection](/images/wagmi2.png)

We then switch to WAGMI in the networks dropdown. We are ready to move on to Remix now, so we open it in the browser. First, we check that Remix sees the extension and correctly talks to it. We select `Deploy & run transactions` icon on the left edge, and on the Environment dropdown, select `Injected Provider`. We need to approve the Remix network access in the Core browser extension. When that is done, `Custom (11111) network` is shown:

![Injected provider](/images/wagmi3.png)

Good, we're talking to WAGMI Avalanche L1. Next we need to load the contracts into Remix. Using 'load from GitHub' option from the Remix home screen we load two contracts:

- [IAllowList.sol](https://github.com/ava-labs/subnet-evm/blob/master/contracts/contracts/interfaces/IAllowList.sol)
- and [IFeeManager.sol](https://github.com/ava-labs/subnet-evm/blob/master/contracts/contracts/interfaces/IFeeManager.sol).

IFeeManager is our precompile, but it references the IAllowList, so we need that one as well. We compile IFeeManager.sol and use deployed contract at the precompile address `0x0200000000000000000000000000000000000003` used on the [Avalanche L1](https://github.com/ava-labs/subnet-evm/blob/master/precompile/contracts/feemanager/module.go#L21).

![Deployed contract](/images/wagmi4.png)

Now we can interact with the FeeManager precompile from within Remix via Core. For example, we can use the `getFeeConfig` method to check the current fee configuration. This action can be performed by anyone as it is just a read operation.

Once we have the new desired configuration for the fees on the Avalanche L1, we can use the `setFeeConfig` to change the parameters. This action can **only** be performed by the owner `0x6f0f6DA1852857d7789f68a28bba866671f3880D` as the `adminAddress` specified in the [`upgrade.json` above](#deploying-upgradejson).

![setFeeConfig](/images/wagmi5.png)

When we call that method by pressing the `transact` button, a new transaction is posted to the Avalanche L1, and we can see it on [the explorer](https://subnets-test.avax.network/wagmi/block/0xad95ccf04f6a8e018ece7912939860553363cc23151a0a31ea429ba6e60ad5a3):

![transaction](/images/wagmi6.png)

Immediately after the transaction is accepted, the new fee config takes effect. We can check with the `getFeeCofig` that the values are reflected in the active fee config (again this action can be performed by anyone):

![getFeeConfig](/images/wagmi7.png)

That's it, fees changed! No network upgrades, no complex and risky deployments, just making a simple contract call and the new fee configuration is in place!

### Using NativeMinter[​](#using-nativeminter "Direct link to heading")

For the NativeMinter, we can use the same process to connect to the Avalanche L1 and interact with the precompile. We can load INativeMinter interface using 'load from GitHub' option from the Remix home screen with following contracts:

- [IAllowList.sol](https://github.com/ava-labs/subnet-evm/blob/master/contracts/contracts/interfaces/IAllowList.sol)
- and [INativeMinter.sol](https://github.com/ava-labs/subnet-evm/blob/master/contracts/contracts/interfaces/INativeMinter.sol).

We can compile them and interact with the deployed contract at the precompile address `0x0200000000000000000000000000000000000001` used on the [Avalanche L1](https://github.com/ava-labs/subnet-evm/blob/master/precompile/contracts/nativeminter/module.go#L22).

![Deployed contract](/images/wagmi8.png)

The native minter precompile is used to mint native coins to specified addresses. The minted coins is added to the current supply and can be used by the recipient to pay for gas fees. For more information about the native minter precompile see [here](/docs/avalanche-l1s/upgrade/customize-avalanche-l1#minting-native-coins).

`mintNativeCoin` method can be only called by enabled, manager and admin addresses. For this upgrade we have added both an admin and a manager address in [`upgrade.json` above](#deploying-upgradejson). The manager address was available after Durango upgrades which occurred on February 13, 2024. We will use the manager address `0xadfa2910dc148674910c07d18df966a28cd21331` to mint native coins.

![mintNativeCoin](/images/wagmi9.png)

When we call that method by pressing the `transact` button, a new transaction is posted to the Avalanche L1, and we can see it on [the explorer](https://subnets-test.avax.network/wagmi/tx/0xc4aaba7b5863c1b8f6664ac1d483e2d7d392ab58d1a8feb0b6c318cbae7f1e93):

![tx](/images/wagmi10.png)

As a result of this transaction, the native minter precompile minted a new native coin (1 WGM) to the recipient address `0xB78cbAa319ffBD899951AA30D4320f5818938310`. The address page on the explorer [here](https://subnets-test.avax.network/wagmi/address/0xB78cbAa319ffBD899951AA30D4320f5818938310) shows no incoming transaction; this is because the 1 WGM was directly minted by the EVM itself, without any sender.

### Conclusion[​](#conclusion "Direct link to heading")

Network upgrades can be complex and perilous procedures to carry out safely. Our continuing efforts with Avalanche L1s is to make upgrades as painless and simple as possible. With the powerful combination of stateful precompiles and network upgrades via the upgrade configuration files we have managed to greatly simplify both the network upgrades and network parameter changes. This in turn enables much safer experimentation and many new use cases that were too risky and complex to carry out with high-coordination efforts required with the traditional network upgrade mechanisms.

We hope this case study will help spark ideas for new things you may try on your own. We're looking forward to seeing what you have built and how easy upgrades help you in managing your Avalanche L1s! If you have any questions or issues, feel free to contact us on our [Discord](https://chat.avalabs.org/). Or just reach out to tell us what exciting new things you have built!


# Why Build Avalanche L1s (/docs/avalanche-l1s/when-to-build-avalanche-l1)

---
title: Why Build Avalanche L1s
description: Learn key concepts to decide when to build your own Avalanche L1.
---

## Why Build Your Own Avalanche L1

There are many advantages to running your own Avalanche L1. If you find one or more of these a good match for your project then an Avalanche L1 might be a good solution for you.

### We Want Our Own Gas Token

C-Chain is an Ethereum Virtual Machine (EVM) chain; it requires the gas fees to be paid in its native token. That is, the application may create its own utility tokens (ERC-20) on the C-Chain, but the gas must be paid in AVAX. In the meantime, [Subnet-EVM](https://github.com/ava-labs/subnet-evm) effectively creates an application-specific EVM-chain with full control over native(gas) coins. The operator can pre-allocate the native tokens in the chain genesis, and mint more using the [Subnet-EVM](https://github.com/ava-labs/subnet-evm) precompile contract. And these fees can be either burned (as AVAX burns in C-Chain) or configured to be sent to an address which can be a smart contract.

Note that the Avalanche L1 gas token is specific to the application in the chain, thus unknown to the external parties. Moving assets to other chains requires trusted bridge contracts (or upcoming cross Avalanche L1 communication feature).

### We Want Higher Throughput

The primary goal of the gas limit on C-Chain is to restrict the block size and therefore prevent network saturation. If a block can be arbitrarily large, it takes longer to propagate, potentially degrading the network performance. The C-Chain gas limit acts as a deterrent against any system abuse but can be quite limiting for high throughput applications. Unlike C-Chain, Avalanche L1 can be single-tenant, dedicated to the specific application, and thus host its own set of validators with higher bandwidth requirements, which allows for a higher gas limit thus higher transaction throughput. Plus, [Subnet-EVM](https://github.com/ava-labs/subnet-evm) supports fee configuration upgrades that can be adaptive to the surge in application traffic.

Avalanche L1 workloads are isolated from the Primary Network; which means, the noisy neighbor effect of one workload (for example NFT mint on C-Chain) cannot destabilize the Avalanche L1 or surge its gas price. This failure isolation model in the Avalanche L1 can provide higher application reliability.

### We Want Strict Access Control

The C-Chain is open and permissionless where anyone can deploy and interact with contracts. However, for regulatory reasons, some applications may need a consistent access control mechanism for all on-chain transactions. With [Subnet-EVM](https://github.com/ava-labs/subnet-evm), an application can require that “only authorized users may deploy contracts or make transactions.” Allow-lists are only updated by the administrators, and the allow list itself is implemented within the precompile contract, thus more transparent and auditable for compliance matters.

### We Need EVM Customization

If your project is deployed on the C-Chain then your execution environment is dictated by the setup of the C-Chain. Changing any of the execution parameters means that the configuration of the C-Chain would need to change, and that is expensive, complex and difficult to change. So if your project needs some other capabilities, different execution parameters or precompiles that C-Chain does not provide, then Avalanche L1s are a solution you need. You can configure the EVM in an Avalanche L1 to run however you want, adding precompiles, and setting runtime parameters to whatever your project needs.

### We Need Custom Validator Management

With the Etna upgrade, L1s can implement their own validator management logic through a _ValidatorManager_ smart contract. This gives you complete control over your validator set, allowing you to define custom staking rules, implement permissionless proof-of-stake with your own token, or create permissioned proof-of-authority networks. The validator management can be handled directly through smart contracts, giving you programmatic control over validator selection and rewards distribution.

### We Want to Build a Sovereign Network

L1s on Avalanche are truly sovereign networks that operate independently without relying on other systems. You have complete control over your network's consensus mechanisms, transaction processing, and security protocols. This independence allows you to scale horizontally without dependencies on other networks while maintaining full control over your network parameters and upgrades. This sovereignty is particularly important for projects that need complete autonomy over their blockchain's operation and evolution.

## Conclusion

Here we presented some considerations in favor of running your own Avalanche L1 vs. deploying on the C-Chain.

If an application has relatively low transaction rate and no special circumstances that would make the C-Chain a non-starter, you can begin with C-Chain deployment to leverage existing technical infrastructure, and later expand to an Avalanche L1. That way you can focus on working on the core of your project and once you have a solid product/market fit and have gained enough traction that the C-Chain is constricting you, plan a move to your own Avalanche L1.

Of course, we're happy to talk to you about your architecture and help you choose the best path forward. Feel free to reach out to us on [Discord](https://chat.avalabs.org/) or other [community channels](https://www.avax.network/community) we run.


# When to Build on C-Chain (/docs/dapps/c-chain-or-avalanche-l1)

---
title: When to Build on C-Chain
description: Learn key concepts to decide when to build on the Avalanche C-Chain.
---

Here are some advantages of the Avalanche C-Chain that you should take into account.

## High Composability with C-Chain Assets[​](#we-want-high-composability-with-c-chain-assets "Direct link to heading")

C-Chain is a better option for seamless integration with existing C-Chain assets and contracts. It is easier to build a DeFi application on C-Chain, as it provides larger liquidity pools and thus allows for efficient exchange between popular assets.

## Low Initial Cost[​](#we-want-low-initial-cost "Direct link to heading")

C-Chain has economic advantages of low-cost deployment and cheap transactions. The recent Etna upgrade trim down the base fee of Avalanche C-Chain by 25x, which results in much lower transaction costs.

## Low Operational Costs[​](#we-want-low-operational-costs "Direct link to heading")

C-Chain is run and operated by thousands of nodes, it is highly decentralized and reliable, and all the infrastructure (explorers, indexers, exchanges, bridges) has already been built out by dedicated teams that maintain them for you at no extra charge. Project deployed on the C-Chain can leverage all of that basically for free.

## High Security[​](#we-want-high-security "Direct link to heading")

The security of Avalanche Primary Network is a function of the security of the underlying validators and stake delegators. You can choose C-Chain in order to achieve maximum security by utilizing thousands of Avalanche Primary Network validators.

## Conclusion

If an application has relatively low transaction rate and no special circumstances that would make the C-Chain a non-starter, you can begin with C-Chain deployment to leverage existing technical infrastructure, and later expand to an Avalanche L1. That way you can focus on working on the core of your project and once you have a solid product/market fit and have gained enough traction that the C-Chain is constricting you, plan a move to your own Avalanche L1.

Of course, we're happy to talk to you about your architecture and help you choose the best path forward. Feel free to reach out to us on [Discord](https://chat.avalabs.org/) or other [community channels](https://www.avax.network/community) we run.

# Introduction (/docs/dapps)

---
title: Introduction
description: Learn about the Avalanche C-Chain.
---

Avalanche is a [network of networks](/docs/quick-start/primary-network). One of the chains running on Avalanche Primary Network is an EVM fork called the C-Chain (contract chain).

C-Chain runs a fork of [`go-ethereum`](https://geth.ethereum.org/docs/rpc/server) called [`coreth`](https://github.com/ava-labs/coreth) that has the networking and consensus portions replaced with Avalanche equivalents. What's left is the Ethereum VM, which runs Solidity smart contracts and manages data structures and blocks on the chain.

As a result, you get a blockchain that can run all the Solidity smart contracts from Ethereum, but with much greater transaction bandwidth and instant finality that [Avalanche's revolutionary consensus](/docs/quick-start/avalanche-consensus) enables.

Coreth is loaded as a plugin into [AvalancheGo](https://github.com/ava-labs/avalanchego), the client node application used to run Avalanche network. Any dApp deployed to Avalanche C-Chain will function the same as on Ethereum, but much faster and cheaper.

## Add C-Chain to Wallet

### Avalanche C-Chain Mainnet

- **Network Name**: Avalanche Mainnet C-Chain
- **RPC URL**: https://api.avax.network/ext/bc/C/rpc
- **WebSocket URL**: wss://api.avax.network/ext/bc/C/ws
- **ChainID**: `43114`
- **Symbol**: `AVAX`
- **Explorer**: https://subnets.avax.network/c-chain

### Avalanche Fuji Testnet

- **Network Name**: Avalanche Fuji C-Chain
- **RPC URL**: https://api.avax-test.network/ext/bc/C/rpc
- **WebSocket URL**: wss://api.avax-test.network/ext/bc/C/ws
- **ChainID**: `43113`
- **Symbol**: `AVAX`
- **Explorer**: https://subnets-test.avax.network/c-chain

### Via Block Explorers

Head to either explorer linked above and select "Add Avalanche C-Chain to Wallet" under "Chain Info" to automatically add the network.

Alternatively, visit [chainlist.org](https://chainlist.org/?search=Avalanche&testnets=true) and connect your wallet.

# Introduction (/docs/cross-chain)

---
title: Introduction
description: Learn about different interoperability protocols in the Avalanche ecosystem.
---

<Cards>
<Card title="Avalanche Interchain Messaging" description="Learn about Avalanche Interchain Messaging, a protocol for cross-chain communication." href="/docs/cross-chain/avalanche-warp-messaging/overview" />

<Card title="ICM Contracts" description="Learn about ICM Contracts, a protocol for cross-chain communication between EVM Chains." href="/docs/cross-chain/teleporter/overview" />

<Card title="Interchain Token Transfer" description="Learn about Avalanche Interchain Token Transfer (ICTT), a protocol for transferring tokens between Avalanche L1s." href="/docs/cross-chain/interchain-token-transfer/overview" />
</Cards>


# Introduction (/docs/nodes)

---
title: Introduction
description: A brief introduction to the concepts of nodes and validators within the Avalanche ecosystem.
---

The Avalanche network is a decentralized platform designed for high throughput and low latency, enabling a wide range of applications. At the core of the network are nodes and validators, which play vital roles in maintaining the network's security, reliability, and performance.

## What is a Node?

A node in the Avalanche network is any computer that participates in the network by maintaining a copy of the blockchain, relaying information, and validating transactions. Nodes can be of different types depending on their role and level of participation in the network’s operations.

### Types of Nodes

- **Full Node**: Stores the entire blockchain data and helps propagate transactions and blocks across the network. It does not participate directly in consensus but is crucial for the network's health and decentralization. **Archival full nodes** store the entire blockchain ledger, including all transactions from the beginning to the most recent. **Pruned full nodes** download the blockchain ledger, then delete blocks starting with the oldest to save memory.
- **Validator Node**: A specialized type of full node that actively participates in the consensus process by validating transactions, producing blocks, and securing the network. Validator nodes are required to stake AVAX tokens as collateral to participate in the consensus mechanism.
- **RPC (Remote Procedure Call) Node**: These nodes act as an interface, enabling third-party applications to query and interact with the blockchain.

## More About Validator Nodes

A validator node participates in the network's consensus protocol by validating transactions and creating new blocks. Validators play a critical role in ensuring the integrity, security, and decentralization of the network.

#### Key Functions of Validators:

- **Transaction Validation**: Validators verify the legitimacy of transactions before they are added to the blockchain.
- **Block Production**: Validators produce and propose new blocks to the network. This involves reaching consensus with other validators to agree on which transactions should be included in the next block.
- **Security and Consensus**: Validators work together to secure the network and ensure that only valid transactions are confirmed. This is done through the Avalanche Consensus protocol, which allows validators to achieve agreement quickly and with high security.

### Primary Network Validators

To become a validator on the Primary Network, you must stake **2,000 AVAX**. This will grant you the ability to validate transactions across all three chains in the Primary Network: the P-Chain, C-Chain, and X-Chain.

### Avalanche L1 Validator

To become a validator on an Avalanche L1, you must meet the specific validator management criteria for that network. If the L1 operates on a Proof-of-Stake (PoS) model, you will need to stake the required amount of tokens to be eligible.

In addition to meeting these criteria, there is a monthly fee of **1.33 AVAX** per validator.


# System Requirements (/docs/nodes/system-requirements)

---
title: System Requirements
description: This document provides information about the system and networking requirements for running an AvalancheGo node.
---

## Hardware and Operating Systems

Avalanche is an incredibly lightweight protocol, so nodes can run on commodity hardware. Note that as network usage increases, hardware requirements may change.

- **CPU**: Equivalent of 8 AWS vCPU
- **RAM**: 8 GiB (16 GiB recommended)
- **Storage**: 1 TiB SSD
- **OS**: Ubuntu 22.04 or MacOS >= 12

<Callout title="Warning" type="warn">
Nodes which choose to use a HDD may get poor and random read/write latencies, therefore reducing performance and reliability. An SSD is strongly suggested.
</Callout>

## Networking

To run successfully, AvalancheGo needs to accept connections from the Internet on the network port `9651`. Before you proceed with the installation, you need to determine the networking environment your node will run in.

### On a Cloud Provider

If your node is running on a cloud provider computer instance, it will have a static IP. Find out what that static IP is, or set it up if you didn't already.

### On a Home Connection

If you're running a node on a computer that is on a residential internet connection, you have a dynamic IP; that is, your IP will change periodically. **For the sake of demonstration, you can ignore the following information.** Otherwise, you will need to set up inbound port forwarding of port `9651` from the internet to the computer the node is installed on.

As there are too many models and router configurations, we cannot provide instructions on what exactly to do, but there are online guides to be found (like [this](https://www.noip.com/support/knowledgebase/general-port-forwarding-guide/), or [this](https://www.howtogeek.com/66214/how-to-forward-ports-on-your-router/) ), and your service provider support might help too.

<Callout title="Note">
Please note that a fully connected Avalanche node maintains and communicates over a couple of thousand of live TCP connections.

For some under-powered and older home routers, that might be too much to handle. If that is the case, you may experience lagging on other computers connected to the same router, node getting benched, or failing to sync and similar issues.
</Callout>


# Avalanche Community Proposals (/docs/quick-start/avalanche-community-proposals)

---
title: Avalanche Community Proposals
description: Learn about community proposals and how to create them.
---

An Avalanche Community Proposal is a concise document that introduces a change or best practice for adoption on the [Avalanche Network](https://www.avax.network/). ACPs should provide clear technical specifications of any proposals and a compelling rationale for their adoption.

ACPs are an open framework for proposing improvements and gathering consensus around changes to the Avalanche Network. ACPs can be proposed by anyone and will be merged into this repository as long as they are well-formatted and coherent. Once an overwhelming majority of the Avalanche Network/Community have [signaled their support for an ACP](/docs/nodes/configure/configs-flags#avalanche-community-proposals), it may be scheduled for activation on the Avalanche Network by Avalanche Network Clients (ANCs). It is ultimately up to members of the Avalanche Network/Community to adopt ACPs they support by running a compatible ANC, such as [AvalancheGo](https://github.com/ava-labs/avalanchego).

## ACP Tracks

There are three kinds of ACP:

- A `Standards Track` ACP describes a change to the design or function of the Avalanche Network, such as a change to the P2P networking protocol, P-Chain design, Avalanche L1 architecture, or any change/addition that affects the interoperability of Avalanche Network Clients (ANCs).
- A `Best Practices Track` ACP describes a design pattern or common interface that should be used across the Avalanche Network to make it easier to integrate with Avalanche or for Avalanche L1s to interoperate with each other. This would include things like proposing a smart contract interface, not proposing a change to how smart contracts are executed.
- A `Meta Track` ACP describes a change to the ACP process or suggests a new way for the Avalanche Community to collaborate.
- A `Subnet Track` ACP describes a change to a particular Avalanche L1. This would include things like configuration changes or coordinated Layer 1 upgrades.

## ACP Statuses

There are four statuses of an ACP:

- A `Proposed` ACP has been merged into the main branch of the ACP repository. It is actively being discussed by the Avalanche Community and may be modified based on feedback.
- An `Implementable` ACP is considered "ready for implementation" by the author and will no longer change meaningfully from its current form (which would require a new ACP).
- An `Activated` ACP has been activated on the Avalanche Network via a coordinated upgrade by the Avalanche Community. Once an ACP is `Activated`, it is locked.
- A `Stale` ACP has been abandoned by its author because it is not supported by the Avalanche Community or has been replaced with another ACP.

## ACP Workflow

### Step 0: Think of a Novel Improvement to Avalanche

The ACP process begins with a new idea for Avalanche. Each potential ACP must have an author: someone who writes the ACP using the style and format described below, shepherds the associated GitHub Discussion, and attempts to build consensus around the idea. Note that ideas and any resulting ACP is public. Authors should not post any ideas or anything in an ACP that the Author wants to keep confidential or to keep ownership rights in (such as intellectual property rights).

### Step 1: Post Your Idea to [GitHub Discussions](https://github.com/avalanche-foundation/ACPs/discussions/categories/ideas)

The author should first attempt to ascertain whether there is support for their idea by posting in the "Ideas" category of GitHub Discussions. Vetting an idea publicly before going as far as writing an ACP is meant to save both the potential author and the wider Avalanche Community time. Asking the Avalanche Community first if an idea is original helps prevent too much time being spent on something that is guaranteed to be rejected based on prior discussions (searching the Internet does not always do the trick). It also helps to make sure the idea is applicable to the entire community and not just the author. Small enhancements or patches often don't need standardization between multiple projects; these don't need an ACP and should be injected into the relevant development workflow with a patch submission to the applicable ANC issue tracker.

### Step 2: Propose an ACP via [Pull Request](https://github.com/avalanche-foundation/ACPs/pulls)

Once the author feels confident that an idea has a decent chance of acceptance, an ACP should be drafted and submitted as a pull request (PR). This draft must be written in ACP style as described below. It is highly recommended that a single ACP contain a single key proposal or new idea. The more focused the ACP, the more successful it tends to be. If in doubt, split your ACP into several well-focused ones. The PR number of the ACP will become its assigned number.

### Step 3: Build Consensus on [GitHub Discussions](https://github.com/avalanche-foundation/ACPs/discussions/categories/discussion) and Provide an Implementation (if Applicable)

ACPs will be merged by ACP maintainers if the proposal is generally well-formatted and coherent. ACP editors will attempt to merge anything worthy of discussion, regardless of feasibility or complexity, that is not a duplicate or incomplete. After an ACP is merged, an official GitHub Discussion will be opened for the ACP and linked to the proposal for community discussion. It is recommended for author or supportive Avalanche Community members to post an accompanying non-technical overview of their ACP for general consumption in this GitHub Discussion. The ACP should be reviewed and broadly supported before a reference implementation is started, again to avoid wasting the author and the Avalanche Community's time, unless a reference implementation will aid people in studying the ACP.

### Step 4: Mark ACP as `Implementable` via [Pull Request](https://github.com/avalanche-foundation/ACPs/pulls)

Once an ACP is considered complete by the author, it should be marked as `Implementable`. At this point, all open questions should be addressed and an associated reference implementation should be provided (if applicable). As mentioned earlier, the Avalanche Foundation meets periodically to recommend the ratification of specific ACPs but it is ultimately up to members of the Avalanche Network/Community to adopt ACPs they support by running a compatible Avalanche Network Client (ANC), such as [AvalancheGo](https://github.com/ava-labs/avalanchego).

### [Optional] Step 5: Mark ACP as `Stale` via [Pull Request](https://github.com/avalanche-foundation/ACPs/pulls)

An ACP can be superseded by a different ACP, rendering the original obsolete. If this occurs, the original ACP will be marked as `Stale`. ACPs may also be marked as `Stale` if the author abandon work on it for a prolonged period of time (12+ months). ACPs may be reopened and moved back to `Proposed` if the author restart work.

## What Belongs in a Successful ACP?

Each ACP must have the following parts:

- `Preamble`: Markdown table containing metadata about the ACP, including the ACP number, a short descriptive title, the author, and optionally the contact info for each author, etc.
- `Abstract`: Concise (~200 word) description of the ACP
- `Motivation`: Rationale for adopting the ACP and the specific issue/challenge/opportunity it addresses
- `Specification`: Complete description of the semantics of any change should allow any ANC/Avalanche Community member to implement the ACP
- `Security Considerations`: Security implications of the proposed ACP

Each ACP can have the following parts:

- `Open Questions`: Questions that should be resolved before implementation

Each `Standards Track` ACP must have the following parts:

- `Backwards Compatibility`: List of backwards incompatible changes required to implement the ACP and their impact on the Avalanche Community
- `Reference Implementation`: Code, documentation, and telemetry (from a local network) of the ACP change

Each `Best Practices Track` ACP can have the following parts:

- `Backwards Compatibility`: List of backwards incompatible changes required to implement the ACP and their impact on the Avalanche Community
- `Reference Implementation`: Code, documentation, and telemetry (from a local network) of the ACP change

### ACP Formats and Templates

Each ACP is allocated a unique subdirectory in the `ACPs` directory. The name of this subdirectory must be of the form `N-T` where `N` is the ACP number and `T` is the ACP title with any spaces replaced by hyphens. ACPs must be written in [markdown](https://daringfireball.net/projects/markdown/syntax) format and stored at `ACPs/N-T/README.md`. Please see the [ACP template](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/TEMPLATE.md) for an example of the correct layout.

### Auxiliary Files

ACPs may include auxiliary files such as diagrams or code snippets. Such files should be stored in the ACP's subdirectory (`ACPs/N-T/*`). There is no required naming convention for auxiliary files.

### Waived Copyright

ACP authors must waive any copyright claims before an ACP will be merged into the repository. This can be done by including the following text in an ACP:

```
## Copyright
Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).
```

## Contributing

Before contributing to ACPs, please read the [ACP Terms of Contribution](https://github.com/avalanche-foundation/ACPs/blob/main/CONTRIBUTING.md).








# Avalanche Consensus (/docs/quick-start/avalanche-consensus)

---
title: Avalanche Consensus
description: Learn about the groundbreaking Avalanche Consensus algorithms.
---

Consensus is the task of getting a group of computers (a.k.a. nodes) to come to an agreement on a decision. In blockchain, this means that all the participants in a network have to agree on the changes made to the shared ledger.

This agreement is reached through a specific process, a consensus protocol, that ensures that everyone sees the same information and that the information is accurate and trustworthy.

## Avalanche Consensus

Avalanche Consensus is a consensus protocol that is scalable, robust, and decentralized. It combines features of both classical and Nakamoto consensus mechanisms to achieve high throughput, fast finality, and energy efficiency. For the whitepaper, see [here](https://www.avalabs.org/whitepapers).

Key Features Include:

- Speed: Avalanche consensus provides sub-second, immutable finality, ensuring that transactions are quickly confirmed and irreversible.
- Scalability: Avalanche consensus enables high network throughput while ensuring low latency.
- Energy Efficiency: Unlike other popular consensus protocols, participation in Avalanche consensus is neither computationally intensive nor expensive.
- Adaptive Security: Avalanche consensus is designed to resist various attacks, including sybil attacks, distributed denial-of-service (DDoS) attacks, and collusion attacks. Its probabilistic nature ensures that the consensus outcome converges to the desired state, even when the network is under attack.

## Conceptual Overview

Consensus protocols in the Avalanche family operate through repeated sub-sampled voting. When a node is determining whether a [transaction](http://support.avalabs.org/en/articles/4587384-what-is-a-transaction) should be accepted, it asks a small, random subset of [validator nodes](http://support.avalabs.org/en/articles/4064704-what-is-a-blockchain-validator) for their preference. Each queried validator replies with the transaction that it prefers, or thinks should be accepted.

<Callout title="Note">
Consensus will never include a transaction that is determined to be **invalid**. For example, if you were to submit a transaction to send 100 AVAX to a friend, but your wallet only has 2 AVAX, this transaction is considered **invalid** and will not participate in consensus.
</Callout>

If a sufficient majority of the validators sampled reply with the same preferred transaction, this becomes the preferred choice of the validator that inquired.

In the future, this node will reply with the transaction preferred by the majority.

The node repeats this sampling process until the validators queried reply with the same answer for a sufficient number of consecutive rounds.

- The number of validators required to be considered a "sufficient majority" is referred to as "α" (_alpha_).
- The number of consecutive rounds required to reach consensus, a.k.a. the "Confidence Threshold," is referred to as "β" (_beta_).
- Both α and β are configurable.

When a transaction has no conflicts, finalization happens very quickly. When conflicts exist, honest validators quickly cluster around conflicting transactions, entering a positive feedback loop until all correct validators prefer that transaction. This leads to the acceptance of non-conflicting transactions and the rejection of conflicting transactions.

![How Avalanche Consensus Works](/images/avalanche-consensus1.png)

Avalanche Consensus guarantees that if any honest validator accepts a transaction, all honest validators will come to the same conclusion.

<Callout title="Note">
For a great visualization, check out [this demo](https://tedyin.com/archive/snow-bft-demo/#/snow).
</Callout>

## Deep Dive Into Avalanche Consensus

<YouTube id="ZUF9sIu-D_k" fullSize={false}/>

### Intuition

First, let's develop some intuition about the protocol. Imagine a room full of people trying to agree on what to get for lunch. Suppose it's a binary choice between pizza and barbecue. Some people might initially prefer pizza while others initially prefer barbecue. Ultimately, though, everyone's goal is to achieve **consensus**.

Everyone asks a random subset of the people in the room what their lunch preference is. If more than half say pizza, the person thinks, "OK, looks like things are leaning toward pizza. I prefer pizza now." That is, they adopt the _preference_ of the majority. Similarly, if a majority say barbecue, the person adopts barbecue as their preference.

Everyone repeats this process. Each round, more and more people have the same preference. This is because the more people that prefer an option, the more likely someone is to receive a majority reply and adopt that option as their preference. After enough rounds, they reach consensus and decide on one option, which everyone prefers.

### Snowball

The intuition above outlines the Snowball Algorithm, which is a building block of Avalanche consensus. Let's review the Snowball algorithm.

#### Parameters

- _n_: number of participants
- _k_ (sample size): between 1 and _n_
- α (quorum size): between 1 and _k_
- β (decision threshold): >= 1

#### Algorithm

```
preference := pizza
consecutiveSuccesses := 0
while not decided:
  ask k random people their preference
  if >= α give the same response:
    preference := response with >= α
    if preference == old preference:
      consecutiveSuccesses++
    else:
      consecutiveSuccesses = 1
  else:
    consecutiveSuccesses = 0
  if consecutiveSuccesses > β:
    decide(preference)
```

#### Algorithm Explained

Everyone has an initial preference for pizza or barbecue. Until someone has _decided_, they query _k_ people (the sample size) and ask them what they prefer. If α or more people give the same response, that response is adopted as the new preference. α is called the _quorum size_. If the new preference is the same as the old preference, the `consecutiveSuccesses` counter is incremented. If the new preference is different then the old preference, the `consecutiveSuccesses` counter is set to `1`. If no response gets a quorum (an α majority of the same response) then the `consecutiveSuccesses` counter is set to `0`.

Everyone repeats this until they get a quorum for the same response β times in a row. If one person decides pizza, then every other person following the protocol will eventually also decide on pizza.

Random changes in preference, caused by random sampling, cause a network preference for one choice, which begets more network preference for that choice until it becomes irreversible and then the nodes can decide.

In our example, there is a binary choice between pizza or barbecue, but Snowball can be adapted to achieve consensus on decisions with many possible choices.

The liveness and safety thresholds are parameterizable. As the quorum size, α, increases, the safety threshold increases, and the liveness threshold decreases. This means the network can tolerate more byzantine (deliberately incorrect, malicious) nodes and remain safe, meaning all nodes will eventually agree whether something is accepted or rejected. The liveness threshold is the number of malicious participants that can be tolerated before the protocol is unable to make progress.

These values, which are constants, are quite small on the Avalanche Network. The sample size, _k_, is `20`. So when a node asks a group of nodes their opinion, it only queries `20` nodes out of the whole network. The quorum size, α, is `14`. So if `14` or more nodes give the same response, that response is adopted as the querying node's preference. The decision threshold, β, is `20`. A node decides on choice after receiving `20` consecutive quorum (α majority) responses.

Snowball is very scalable as the number of nodes on the network, _n_, increases. Regardless of the number of participants in the network, the number of consensus messages sent remains the same because in a given query, a node only queries `20` nodes, even if there are thousands of nodes in the network.

Everything discussed to this point is how Avalanche is described in [the Avalanche white-paper](https://assets-global.website-files.com/5d80307810123f5ffbb34d6e/6009805681b416f34dcae012_Avalanche%20Consensus%20Whitepaper.pdf). The implementation of the Avalanche consensus protocol by Ava Labs (namely in AvalancheGo) has some optimizations for latency and throughput.

### Blocks

A block is a fundamental component that forms the structure of a blockchain. It serves as a container or data structure that holds a collection of transactions or other relevant information. Each block is cryptographically linked to the previous block, creating a chain of blocks, hence the term "blockchain."

In addition to storing a reference of its parent, a block contains a set of transactions. These transactions can represent various types of information, such as financial transactions, smart contract operations, or data storage requests.

If a node receives a vote for a block, it also counts as a vote for all of the block's ancestors (its parent, the parents' parent, etc.).

### Finality

Avalanche consensus is probabilistically safe up to a safety threshold. That is, the probability that a correct node accepts a transaction that another correct node rejects can be made arbitrarily low by adjusting system parameters. In Nakamoto consensus protocol (as used in Bitcoin and Ethereum, for example), a block may be included in the chain but then be removed and not end up in the canonical chain. This means waiting an hour for transaction settlement. In Avalanche, acceptance/rejection are **final and irreversible** and only take a few seconds.

### Optimizations

It's not safe for nodes to just ask, "Do you prefer this block?" when they query validators. In Ava Labs' implementation, during a query a node asks, "Given that this block exists, which block do you prefer?" Instead of getting back a binary yes/no, the node receives the other node's preferred block.

Nodes don't only query upon hearing of a new block; they repeatedly query other nodes until there are no blocks processing.

Nodes may not need to wait until they get all _k_ query responses before registering the outcome of a poll. If a block has already received _alpha_ votes, then there's no need to wait for the rest of the responses.

### Validators

If it were free to become a validator on the Avalanche network, that would be problematic because a malicious actor could start many, many nodes which would get queried very frequently. The malicious actor could make the node act badly and cause a safety or liveness failure. The validators, the nodes which are queried as part of consensus, have influence over the network. They have to pay for that influence with real-world value in order to prevent this kind of ballot stuffing. This idea of using real-world value to buy influence over the network is called Proof of Stake.

To become a validator, a node must **bond** (stake) something valuable (**AVAX**). The more AVAX a node bonds, the more often that node is queried by other nodes. When a node samples the network it's not uniformly random. Rather, it's weighted by stake amount. Nodes are incentivized to be validators because they get a reward if, while they validate, they're sufficiently correct and responsive.

Avalanche doesn't have slashing. If a node doesn't behave well while validating, such as giving incorrect responses or perhaps not responding at all, its stake is still returned in whole, but with no reward. As long as a sufficient portion of the bonded AVAX is held by correct nodes, then the network is safe, and is live for virtuous transactions.

### Big Ideas

Two big ideas in Avalanche are **subsampling** and **transitive voting**.

Subsampling has low message overhead. It doesn't matter if there are twenty validators or two thousand validators; the number of consensus messages a node sends during a query remains constant.

Transitive voting, where a vote for a block is a vote for all its ancestors, helps with transaction throughput. Each vote is actually many votes in one.

### Loose Ends

Transactions are created by users which call an API on an [AvalancheGo](https://github.com/ava-labs/avalanchego) full node or create them using a library such as [AvalancheJS](https://github.com/ava-labs/avalanchejs).

### Other Observations

Conflicting transactions are not guaranteed to be live. That's not really a problem because if you want your transaction to be live then you should not issue a conflicting transaction.

Snowman is the name of Ava Labs' implementation of the Avalanche consensus protocol for linear chains.

If there are no undecided transactions, the Avalanche consensus protocol _quiesces_. That is, it does nothing if there is no work to be done. This makes Avalanche more sustainable than Proof-of-work where nodes need to constantly do work.

Avalanche has no leader. Any node can propose a transaction and any node that has staked AVAX can vote on every transaction, which makes the network more robust and decentralized.

## Why Do We Care?

Avalanche is a general consensus engine. It doesn't matter what type of application is put on top of it. The protocol allows the decoupling of the application layer from the consensus layer. If you're building a dapp on Avalanche then you just need to define a few things, like how conflicts are defined and what is in a transaction. You don't need to worry about how nodes come to an agreement. The consensus protocol is a black box that put something into it and it comes back as accepted or rejected.

Avalanche can be used for all kinds of applications, not just P2P payment networks. Avalanche's Primary Network has an instance of the Ethereum Virtual Machine, which is backward compatible with existing Ethereum Dapps and dev tooling. The Ethereum consensus protocol has been replaced with Avalanche consensus to enable lower block latency and higher throughput.

Avalanche is very performant. It can process thousands of transactions per second with one to two second acceptance latency.

## Summary

Avalanche consensus is a radical breakthrough in distributed systems. It represents as large a leap forward as the classical and Nakamoto consensus protocols that came before it. Now that you have a better understanding of how it works, check out other documentations for building game-changing Dapps and financial instruments on Avalanche.








# Avalanche L1s (/docs/quick-start/avalanche-l1s)

---
title: Avalanche L1s
description: Explore the multi-chain architecture of Avalanche ecosystem.
---

An Avalanche L1 is a sovereign network which defines its own rules regarding its membership and token economics. It is composed of a dynamic subset of Avalanche validators working together to achieve consensus on the state of one or more blockchains. Each blockchain is validated by exactly one Avalanche L1, while an Avalanche L1 can validate many blockchains.

Avalanche's [Primary Network](/docs/quick-start/primary-network) is a special Avalanche L1 running three blockchains:

- The Platform Chain [(P-Chain)](/docs/quick-start/primary-network#p-chain)
- The Contract Chain [(C-Chain)](/docs/quick-start/primary-network#c-chain)
- The Exchange Chain [(X-Chain)](/docs/quick-start/primary-network#x-chain)

![image](/images/subnet1.png)

<Callout title="Note">
Every validator of an Avalanche L1 **must** sync the P-Chain of the Primary Network for interoperability.
</Callout>

Node operators that validate an Avalanche L1 with multiple chains do not need to run multiple machines for validation. For example, the Primary Network is an Avalanche L1 with three coexisting chains, all of which can be validated by a single node, or a single machine.

## Advantages

### Independent Networks

- Avalanche L1s use virtual machines to specify their own execution logic, determine their own fee regime, maintain their own state, facilitate their own networking, and provide their own security.
- Each Avalanche L1's performance is isolated from other Avalanche L1s in the ecosystem, so increased usage on one Avalanche L1 won't affect another.
- Avalanche L1s can have their own token economics with their own native tokens, fee markets, and incentives determined by the Avalanche L1 deployer.
- One Avalanche L1 can host multiple blockchains with customized [virtual machines](/docs/quick-start/virtual-machines).

### Native Interoperability

Avalanche Warp Messaging enables native cross-Avalanche L1 communication and allows Virtual Machine (VM) developers to implement arbitrary communication protocols between any two Avalanche L1s.

### Accommodate App-Specific Requirements

Different blockchain-based applications may require validators to have certain properties such as large amounts of RAM or CPU power.

an Avalanche L1 could require that validators meet certain [hardware requirements](/docs/nodes/system-requirements#hardware-and-operating-systems) so that the application doesn't suffer from low performance due to slow validators.

### Launch Networks Designed With Compliance

Avalanche's L1 architecture makes regulatory compliance manageable. As mentioned above, an Avalanche L1 may require validators to meet a set of requirements.

Some examples of requirements the creators of an Avalanche L1 may choose include:

- Validators must be located in a given country.
- Validators must pass KYC/AML checks.
- Validators must hold a certain license.

### Control Privacy of On-Chain Data

Avalanche L1s are ideal for organizations interested in keeping their information private.

Institutions conscious of their stakeholders' privacy can create a private Avalanche L1 where the contents of the blockchains would be visible only to a set of pre-approved validators.

Define this at creation with a [single parameter](/docs/nodes/configure/avalanche-l1-configs#private-avalanche-l1).

### Validator Sovereignty

In a heterogeneous network of blockchains, some validators will not want to validate certain blockchains because they simply have no interest in those blockchains.

The Avalanche L1 model enables validators to concern themselves only with blockchain networks they choose to participate in. This greatly reduces the computational burden on validators.

## Develop Your Own Avalanche L1

Avalanche L1s on Avalanche are deployed by default with [Subnet-EVM](https://github.com/ava-labs/subnet-evm#subnet-evm), a fork of go-ethereum. It implements the Ethereum Virtual Machine and supports Solidity smart contracts as well as most other Ethereum client functionality.

To get started, check out our [L1 Toolbox](/tools/l1-toolbox) or the tutorials in the [Avalanche CLI](/docs/tooling/create-avalanche-l1) section.


# AVAX Token (/docs/quick-start/avax-token)

---
title: AVAX Token
description: Learn about the native token of Avalanche Primary Network.
---

AVAX is the native utility token of Avalanche. It's a hard-capped, scarce asset that is used to pay for fees, secure the platform through staking, and provide a basic unit of account between the multiple Avalanche L1s created on Avalanche.

<Callout title="Note">
`1 nAVAX` is equal to `0.000000001 AVAX`.
</Callout>

## Utility

AVAX is a capped-supply (up to 720M) resource in the Avalanche ecosystem that's used to power the
network. AVAX is used to secure the ecosystem through staking and for day-to-day operations like
issuing transactions.

AVAX represents the weight that each node has in network decisions. No single actor owns
the Avalanche Network, so each validator in the network is given a proportional weight in the
network's decisions corresponding to the proportion of total stake that they own through proof
of stake (PoS).

Any entity trying to execute a transaction on Avalanche pays a corresponding fee (commonly known as
"gas") to run it on the network. The fees used to execute a transaction on Avalanche is burned,
or permanently removed from circulating supply.

## Tokenomics

A fixed amount of 360M AVAX was minted at genesis, but a small amount of AVAX is constantly minted
as a reward to validators. The protocol rewards validators for good behavior by minting them AVAX
rewards at the end of their staking period. The minting process offsets the AVAX burned by
transactions fees. While AVAX is still far away from its supply cap, it will almost always remain an
inflationary asset.

Avalanche does not take away any portion of a validator's already staked tokens (commonly known as
"slashing") for negligent/malicious staking periods, however this behavior is disincentivized as
validators who attempt to do harm to the network would expend their node's computing resources
for no reward.

AVAX is minted according to the following formula, where $R_j$ is the total number of tokens at 
year $j$, with $R_1 = 360M$, and $R_l$ representing the last year that the values of
$\gamma,\lambda \in \R$ were changed; $c_j$ is the yet un-minted supply of coins to reach $720M$ at
year $j$ such that $c_j \leq 360M$; $u$ represents a staker, with $u.s_{amount}$ representing the
total amount of stake that $u$ possesses, and $u.s_{time}$ the length of staking for $u$.

AVAX is minted according to the following formula, where $R_j$ is the total number of tokens at:

$$
R_j = R_l + \sum_{\forall u} \rho(u.s_{amount}, u.s_{time}) \times \frac{c_j}{L} \times \left( \sum_{i=0}^{j}\frac{1}{\left(\gamma + \frac{1}{1 + i^\lambda}\right)^i} \right)
$$

where,

$$
L = \left(\sum_{i=0}^{\infty} \frac{1}{\left(\gamma + \frac{1}{1 + i^\lambda} \right)^i} \right)
$$

At genesis, $c_1 = 360M$. The values of $\gamma$ and $\lambda$ are governable, and if changed,
the function is recomputed with the new value of $c_*$. We have that $\sum_{*}\rho(*) \le 1$.
$\rho(*)$ is a linear function that can be computed as follows ($u.s_{time}$ is measured in weeks,
and $u.s_{amount}$ is measured in AVAX tokens):

$$
\rho(u.s_{amount}, u.s_{time}) = (0.002 \times u.s_{time} + 0.896) \times \frac{u.s_{amount}}{R_j}
$$

If the entire supply of tokens at year $j$ is staked for the maximum amount of staking time (one
year, or 52 weeks), then $\sum_{\forall u}\rho(u.s_{amount}, u.s_{time}) = 1$. If, instead,
every token is staked continuously for the minimal stake duration of two weeks, then
$\sum_{\forall u}\rho(u.s_{amount}, u.s_{time}) = 0.9$. Therefore, staking for the maximum
amount of time incurs an additional 11.11% of tokens minted, incentivizing stakers to stake
for longer periods.

Due to the capped-supply, the above function guarantees that
AVAX will never exceed a total of $720M$ tokens, or $\lim_{j \to \infty} R(j) = 720M$.





# Disclaimer (/docs/quick-start/disclaimer)

---
title: Disclaimer
---

The Knowledge Base, including all the Help articles on this site, is provided for technical support purposes only, without representation, warranty or guarantee of any kind.

Not an offer to sell or solicitation of an offer to buy any security or other regulated financial instrument. Not technical, investment, financial, accounting, tax, legal or other advice; please consult your own professionals.

Please conduct your own research before connecting to or interacting with any dapp or third party or making any investment or financial decisions.

MoonPay, ParaSwap and any other third party services or dapps you access are offered by third parties unaffiliated with us.

Please review this [Notice](https://assets.website-files.com/602e8e4411398ca20cfcafd3/60ec9607c853cd466383f1ad_Important%20Notice%20-%20avalabs.org.pdf) and the [Terms of Use](https://core.app/terms/core).






# Introduction (/docs/quick-start)

---
title: Introduction
description: Learn about Avalanche Protocol and its unique features.
---

Avalanche is an open-source platform for building decentralized applications in one interoperable, decentralized, and highly scalable ecosystem.

Powered by a uniquely powerful [consensus mechanism](/docs/quick-start/avalanche-consensus), Avalanche is the first ecosystem designed to accommodate the scale of global finance, with near-instant transaction finality.

## Blazingly Fast

Avalanche employs the fastest consensus mechanism of any Layer 1 blockchain. The unique consensus mechanism enables quick finality and low latency: in less than 2 seconds, your transaction is effectively processed and verified.

## Built to Scale

Developers who build on Avalanche can build application-specific blockchains with complex rulesets or build on existing private or public Avalanche L1s in any language.

Avalanche is incredibly energy-efficient and can run easily on consumer-grade hardware. The entire Avalanche network consumes the same amount of energy as 46 US households, equivalent to 0.0005% of the amount of energy consumed by Bitcoin.

Solidity developers can build on Avalanche's implementation of the EVM straight out-of-the box, or build their own custom Virtual Machine (VM) for advanced use cases.

## Advanced Security

Avalanche consensus scales to thousands of concurrent validators without suffering performance degradation making it one of the most secure protocols for internet scaling systems.

Permissionless and permissioned custom blockchains deployed as an Avalanche L1s can include custom rulesets designed to be compliant with legal and jurisdictional considerations.





# Primary Network (/docs/quick-start/primary-network)

---
title: Primary Network
description: Learn about the Avalanche Primary Network and its three blockchains.
---

Avalanche is a heterogeneous network of blockchains. As opposed to homogeneous networks, where all applications reside in the same chain, heterogeneous networks allow separate chains to be created for different applications.

The Primary Network is a special [Avalanche L1](/docs/quick-start/avalanche-l1s) that runs three blockchains:

- The Platform Chain [(P-Chain)](/docs/quick-start/primary-network#p-chain)
- The Contract Chain [(C-Chain)](/docs/quick-start/primary-network#c-chain)
- The Exchange Chain [(X-Chain)](/docs/quick-start/primary-network#x-chain)

<Callout title="Note">
[Avalanche Mainnet](/docs/quick-start/networks/mainnet) is comprised of the Primary Network and all deployed Avalanche L1s.
</Callout>

A node can become a validator for the Primary Network by staking at least **2,000 AVAX**.

![Primary network](/images/primary-network1.png)

## The Chains

All validators of the Primary Network are required to validate and secure the following:

### C-Chain

The **C-Chain** is an implementation of the Ethereum Virtual Machine (EVM). The [C-Chain's API](/docs/api-reference/c-chain/api) supports Geth's API and supports the deployment and execution of smart contracts written in Solidity.

The C-Chain is an instance of the [Coreth](https://github.com/ava-labs/coreth) Virtual Machine.

### P-Chain

The **P-Chain** is responsible for all validator and Avalanche L1-level operations. The [P-Chain API](/docs/api-reference/p-chain/api) supports the creation of new blockchains and Avalanche L1s, the addition of validators to Avalanche L1s, staking operations, and other platform-level operations.

The P-Chain is an instance of the Platform Virtual Machine.

### X-Chain

The **X-Chain** is responsible for operations on digital smart assets known as **Avalanche Native Tokens**. A smart asset is a representation of a real-world resource (for example, equity, or a bond) with sets of rules that govern its behavior, like "can't be traded until tomorrow." The [X-Chain API](/docs/api-reference/x-chain/api) supports the creation and trade of Avalanche Native Tokens.

One asset traded on the X-Chain is AVAX. When you issue a transaction to a blockchain on Avalanche, you pay a fee denominated in AVAX.

The X-Chain is an instance of the Avalanche Virtual Machine (AVM).


# Rewards Formula (/docs/quick-start/rewards-formula)

---
title: Rewards Formula
description: Learn about the rewards formula for the Avalanche Primary Network validator
---

## Primary Network Validator Rewards

Consider a Primary Network validator which stakes a $Stake$ amount of `AVAX` for $StakingPeriod$ seconds.

The potential reward is calculated **at the beginning of the staking period**. At the beginning of the staking period there is a $Supply$ amount of `AVAX` in the network. The maximum amount of `AVAX` is $MaximumSupply$. At the end of its staking period, a responsive Primary Network validator receives a reward.

$$
Potential Reward = \left(MaximumSupply - Supply \right) \times \frac{Stake}{Supply} \times \frac{Staking Period}{Minting Period} \times EffectiveConsumptionRate
$$

where,

$$
MaximumSupply - Supply = \text{the number of AVAX tokens left to emit in the network}
$$

$$
\frac{Stake}{Supply} = \text{the individual's stake as a percentage of all available AVAX tokens in the network}
$$

$$
\frac{StakingPeriod}{MintingPeriod} = \text{time tokens are locked up divided by the $MintingPeriod$}
$$

$$
\text{$MintingPeriod$ is one year as configured by the network).}
$$

$$
EffectiveConsumptionRate =
$$

$$
\frac{MinConsumptionRate}{PercentDenominator} \times \left(1- \frac{Staking Period}{Minting Period}\right) + \frac{MaxConsumptionRate}{PercentDenominator} \times \frac{Staking Period}{Minting Period}
$$

Note that $StakingPeriod$ is the staker's entire staking period, not just the staker's uptime, that is the aggregated time during which the staker has been responsive. The uptime comes into play only to decide whether a staker should be rewarded; to calculate the actual reward only the staking period duration is taken into account.

$EffectiveConsumptionRate$ is the rate at which the Primary Network validator is rewarded based on $StakingPeriod$ selection.

$MinConsumptionRate$ and $MaxConsumptionRate$ bound $EffectiveConsumptionRate$:

$$
MinConsumptionRate \leq EffectiveConsumptionRate \leq MaxConsumptionRate
$$

The larger $StakingPeriod$ is, the closer $EffectiveConsumptionRate$ is to $MaxConsumptionRate$. The smaller $StakingPeriod$ is, the closer $EffectiveConsumptionRate$ is to $MinConsumptionRate$.

A staker achieves the maximum reward for its stake if $StakingPeriod$ = $Minting Period$. The reward is:

$$
Max Reward = \left(MaximumSupply - Supply \right) \times \frac{Stake}{Supply} \times \frac{MaxConsumptionRate}{PercentDenominator}
$$

Note that this formula is the same as the reward formula at the top of this section because $EffectiveConsumptionRate$ = $MaxConsumptionRate$.

For reference, you can find all the Primary network parameters in [the section below](#primary-network-parameters-on-mainnet).

## Delegators Weight Checks

There are bounds set of the maximum amount of delegators' stake that a validator can receive.

The maximum weight $MaxWeight$ a validator $Validator$ can have is:

$$
MaxWeight = \min(Validator.Weight \times MaxValidatorWeightFactor, MaxValidatorStake)
$$

where $MaxValidatorWeightFactor$ and $MaxValidatorStake$ are the Primary Network Parameters described above.

A delegator won't be added to a validator if the combination of their weights and all other validator's delegators' weight is larger than $MaxWeight$. Note that this must be true at any point in time.

Note that setting $MaxValidatorWeightFactor$ to 1 disables delegation since the $MaxWeight = Validator.Weight$.

## Notes on Percentages

`PercentDenominator = 1_000_000` is the denominator used to calculate percentages.

It allows you to specify percentages up to 4 digital positions. To denominate your percentage in `PercentDenominator` just multiply it by `10_000`. For example:

- `100%` corresponds to `100 * 10_000 = 1_000_000`
- `1%` corresponds to `1* 10_000 = 10_000`
- `0.02%` corresponds to `0.002 * 10_000 = 200`
- `0.0007%` corresponds to `0.0007 * 10_000 = 7`

## Primary Network Parameters on Mainnet

For reference we list below the Primary Network parameters on Mainnet:

- `AssetID = Avax`
- `InitialSupply = 240_000_000 Avax`
- `MaximumSupply = 720_000_000 Avax`.
- `MinConsumptionRate = 0.10 * reward.PercentDenominator`.
- `MaxConsumptionRate = 0.12 * reward.PercentDenominator`.
- `Minting Period = 365 * 24 * time.Hour`.
- `MinValidatorStake = 2_000 Avax`.
- `MaxValidatorStake = 3_000_000 Avax`.
- `MinStakeDuration = 2 * 7 * 24 * time.Hour`.
- `MaxStakeDuration = 365 * 24 * time.Hour`.
- `MinDelegationFee = 20000`, that is `2%`.
- `MinDelegatorStake = 25 Avax`.
- `MaxValidatorWeightFactor = 5`. This is a platformVM parameter rather than a genesis one, so it's shared across networks.
- `UptimeRequirement = 0.8`, that is `80%`.

### Interactive Graph

The graph below demonstrates the reward as a function of the length of time
staked. The x-axis depicts $\frac{StakingPeriod}{MintingPeriod}$ as a percentage
while the y-axis depicts $Reward$ as a percentage of $MaximumSupply - Supply$,
the amount of tokens left to be emitted.

Graph variables correspond to those defined above:

- `h` (high) = $MaxConsumptionRate$
- `l` (low) = $MinConsumptionRate$
- `s` = $\frac{Stake}{Supply}$

<iframe src="https://www.desmos.com/calculator/uqtank2gcn" width="100%" height="400px"></iframe>



# Validator Management (/docs/quick-start/validator-manager)

---
title: Validator Management
description: Learn about the Validator Manager contract suite for Avalanche L1s
---

The Validator Manager contract suite allows Avalanche Layer 1s (L1s) to manage and enforce custom logic for validator sets through smart contracts.

### Choosing Between Proof of Authority and Proof of Stake Chains

Organizations may opt to run a Proof of Authority (PoA) or a Proof of Stake (PoS) chain based on their specific needs and objectives.

#### Proof of Authority

In a PoA chain, a limited number of validators are pre-approved and recognized entities. This model is ideal for organizations that require:

- **Control and Compliance**: Regulatory compliance or the need for trusted validators.
- **Simplified Governance**: Easier coordination among validators.

PoA is often used by private enterprises, consortiums, or government agencies where validator identity is crucial, and a controlled environment is preferred.

#### Proof of Stake

In a PoS chain, validators are selected based on the amount of stake (tokens) they hold and are willing to lock up. This model is suitable for organizations aiming for:

- **Decentralization**: Encouraging a wide distribution of validators.
- **Security**: Economic incentives align validator behavior with network health.
- **Community Participation**: Allowing token holders to participate in network validation.

PoS chains are ideal for public networks or organizations that wish to build an open ecosystem with active community involvement.


### Enforcing Custom Validation Logic via Smart Contracts

Avalanche L1s have the unique capability to enforce any validation logic that can be encoded via smart contracts. This flexibility allows developers and organizations to define custom rules and conditions for validator participation in their networks. By leveraging smart contracts, L1s can implement complex validation mechanisms, such as dynamic validator sets, customized staking requirements, or hybrid consensus models.

Smart contracts act as the governing code that dictates how validators are selected, how they behave, and under what conditions they can participate in the network. This programmable approach ensures that the validation logic is transparent, auditable, and can be updated or modified as needed to adapt to changing requirements or threats.

---

[Learn more about the Validator Manager contract suite](/docs/avalanche-l1s/validator-manager/contract)

[Build your first Avalanche L1](/docs/tooling/create-avalanche-l1)

# Virtual Machines (/docs/quick-start/virtual-machines)

---
title: Virtual Machines
description: Learn about blockchain VMs and how you can build a custom VM-enabled blockchain in Avalanche.
---

A **Virtual Machine** (VM) is the blueprint for a blockchain, meaning it defines a blockchain's complete application logic by specifying the blockchain's state, state transitions, transaction rules, and API interface.

Developers can use the same VM to create multiple blockchains, each of which follows identical rules but is independent of all others.

All Avalanche validators of the **Avalanche Primary Network** are required to run three VMs:

- **Coreth**: Defines the Contract Chain (C-Chain); supports smart contract functionality and is EVM-compatible.
- **Platform VM**: Defines the Platform Chain (P-Chain); supports operations on staking and Avalanche L1s.
- **Avalanche VM**: Defines the Exchange Chain (X-Chain); supports operations on Avalanche Native Tokens.

All three can easily be run on any computer with [AvalancheGo](/docs/nodes).

## Custom VMs on Avalanche

Developers with advanced use-cases for utilizing distributed ledger technology are often forced to build everything from scratch - networking, consensus, and core infrastructure - before even starting on the actual application.

Avalanche eliminates this complexity by:

- Providing VMs as simple blueprints for defining blockchain behavior
- Supporting development in any programming language with familiar tools
- Handling all low-level infrastructure automatically

This lets developers focus purely on building their dApps, ecosystems, and communities, rather than wrestling with blockchain fundamentals.
  
### How Custom VMs Work

Customized VMs can communicate with Avalanche over a language agnostic request-response protocol known as [RPC](https://en.wikipedia.org/wiki/Remote_procedure_call). This allows the VM framework to open a world of endless possibilities, as developers can implement their dApps using the languages, frameworks, and libraries of their choice.

Validators can install additional VMs on their node to validate additional [Avalanche L1s](/docs/quick-start/avalanche-l1s) in the Avalanche ecosystem. In exchange, validators receive staking rewards in the form of a reward token determined by the Avalanche L1s.

## Building a Custom VM

You can start building your first custom virtual machine in two ways:

1. Use the ready-to-deploy Subnet-EVM for Solidity-based development
2. Create a custom VM in Golang, Rust, or your preferred language

The choice depends on your needs. Subnet-EVM provides a quick start with Ethereum compatibility, while custom VMs offer maximum flexibility.

### Golang Examples

<Cards>
  <Card
    href="https://github.com/ava-labs/timestampvm"
    title="TimestampVM"
    description="A decentralized timestamp blockchain written in Golang (recommended for beginners)"
  />
  <Card
    href="https://github.com/ava-labs/coreth"
    title="Coreth"
    description="An implementation of EVM that powers the Avalanche C-Chain and supports Solidity smart contracts"
  />
  <Card
    href="https://github.com/ava-labs/subnet-evm"
    title="Subnet-EVM"
    description="An implementation of EVM that can be deployed to a custom Avalanche L1"
  />
  <Card
    href="https://github.com/ava-labs/xsvm"
    title="XSVM"
    description="An example of Interchain Messaging that implements Cross-Avalanche L1 asset transfers"
  />
</Cards>

See here for a tutorial on [How to Build a Simple Golang VM](/docs/virtual-machines/golang-vms/simple-golang-vm).

### Rust Examples

<Cards>
  <Card
    href="https://github.com/ava-labs/timestampvm-rs"
    title="TimestampVM RS"
    description="A Rust implementation of TimestampVM"
  />
</Cards>

See here for a tutorial on [How to Build a Simple Rust VM](/docs/virtual-machines/rust-vms/setting-up-environment).


# ACP-103: Dynamic Fees (/docs/acps/103-dynamic-fees)

---
title: "ACP-103: Dynamic Fees"
description: "Details for Avalanche Community Proposal 103: Dynamic Fees"
edit_url: https://github.com/avalanche-foundation/ACPs/edit/main/ACPs/103-dynamic-fees/README.md
---

| ACP | 103 |
| :--- | :--- |
| **Title** | Add Dynamic Fees to the P-Chain |
| **Author(s)** | Dhruba Basu ([@dhrubabasu](https://github.com/dhrubabasu)), Alberto Benegiamo ([@abi87](https://github.com/abi87)), Stephen Buttolph ([@StephenButtolph](https://github.com/StephenButtolph)) |
| **Status** | Activated ([Discussion](https://github.com/avalanche-foundation/ACPs/discussions/104)) |
| **Track** | Standards |

## Abstract

Introduce a dynamic fee mechanism to the P-Chain. Preview a future transition to a multidimensional fee mechanism.

## Motivation

Blockchains are resource-constrained environments. Users are charged for the execution and inclusion of their transactions based on the blockchain's transaction fee mechanism. The mechanism should fluctuate based on the supply of and demand for said resources to serve as a deterrent against spam and denial-of-service attacks.

With a fixed fee mechanism, users are provided with simplicity and predictability but network congestion and resource constraints are not taken into account. There is no incentive for users to withhold transactions since the cost is fixed regardless of the demand. The fee does not adjust the execution and inclusion fee of transactions to the market clearing price.

The C-Chain, in [Apricot Phase 3](https://medium.com/avalancheavax/apricot-phase-three-c-chain-dynamic-fees-432d32d67b60), employs a dynamic fee mechanism to raise the price during periods of high demand and lowering the price during periods of low demand. As the price gets too expensive, network utilization will decrease, which drops the price. This ensures the execution and inclusion fee of transactions closely matches the market clearing price.

The P-Chain currently operates under a fixed fee mechanism. To more robustly handle spikes in load expected from introducing the improvements in [ACP-77](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/77-reinventing-subnets/README.md), it should be migrated to a dynamic fee mechanism. 

The X-Chain also currently operates under a fixed fee mechanism. However, due to the current lower usage and lack of new feature introduction, the migration of the X-Chain to a dynamic fee mechanism is deferred to a later ACP to reduce unnecessary additional technical complexity.

## Specification

### Dimensions

There are four dimensions that will be used to approximate the computational cost of, or "gas" consumed in, a transaction:

1. Bandwidth $B$ is the amount of network bandwidth used for transaction broadcast. This is set to the size of the transaction in bytes.
2. Reads $R$ is the number of state/database reads used in transaction execution.
3. Writes $W$ is the number of state/database writes used in transaction execution.
4. Compute $C$ is the total amount of compute used to verify and execute a transaction, measured in microseconds.

The gas consumed $G$ in a transaction is:

$$G = B + 1000R + 1000W + 4C$$

A future ACP could remove the merging of these dimensions to granularly meter usage of each resource in a multidimensional scheme.

### Mechanism

This mechanism aims to maintain a target gas consumption $T$ per second and adjusts the fee based on the excess gas consumption $x$, defined as the difference between the current gas consumption and $T$.

Prior to the activation of this mechanism, $x$ is initialized:

$$x = 0$$

At the start of building/executing block $b$, $x$ is updated:

$$x = \max(x - T \cdot \Delta{t}, 0)$$

Where $\Delta{t}$ is the number of seconds between $b$'s block timestamp and $b$'s parent's block timestamp.

The gas price for block $b$ is:

$$M \cdot \exp\left(\frac{x}{K}\right)$$

Where:

- $M$ is the minimum gas price
- $\exp\left(x\right)$ is an approximation of $e^x$ following the EIP-4844 specification

  ```python
  # Approximates factor * e ** (numerator / denominator) using Taylor expansion
  def fake_exponential(factor: int, numerator: int, denominator: int) -> int:
    i = 1
    output = 0
    numerator_accum = factor * denominator
    while numerator_accum > 0:
        output += numerator_accum
        numerator_accum = (numerator_accum * numerator) // (denominator * i)
        i += 1
    return output // denominator
  ```

- $K$ is a constant to control the rate of change of the gas price

After processing block $b$, $x$ is updated with the total gas consumed in the block $G$:

$$x = x + G$$

Whenever $x$ increases by $K$, the gas price increases by a factor of `~2.7`. If the gas price gets too expensive, average gas consumption drops, and $x$ starts decreasing, dropping the price. The gas price constantly adjusts to make sure that, on average, the blockchain consumes $T$ gas per second.

A [token bucket](https://en.wikipedia.org/wiki/Token_bucket) is employed to meter the maximum rate of gas consumption. Define $C$ as the capacity of the bucket, $R$ as the amount of gas to add to the bucket per second, and $r$ as the amount of gas currently in the bucket.

Prior to the activation of this mechanism, $r$ is initialized:

$$r = 0$$

At the beginning of processing block $b$, $r$ is set:

$$r = \min\left(r + R \cdot \Delta{t}, C\right)$$

Where $\Delta{t}$ is the number of seconds between $b$'s block timestamp and $b$'s parent's block timestamp. The maximum gas consumed in a given $\Delta{t}$ is $r + R \cdot \Delta{t}$. The upper bound across all $\Delta{t}$ is $C + R \cdot \Delta{t}$.

After processing block $b$, the total gas consumed in $b$, or $G$, will be known. If $G \gt r$, $b$ is considered an invalid block. If $b$ is a valid block, $r$ is updated:

$$r = r - G$$

A block gas limit does not need to be set as it is implicitly derived from $r$.

The parameters at activation are:

| Parameter | P-Chain Configuration|
| - | - |
| $T$ - target gas consumed per second | 50,000 |
| $M$ - minimum gas price | 1 nAVAX |
| $K$ - gas price update constant | 2_164_043 |
| $C$ - maximum gas capacity | 1,000,000 |
| $R$ - gas capacity added per second | 100,000 |

$K$ was chosen such that at sustained maximum capacity ($R=100,000$ gas/second), the fee rate will double every ~30 seconds.

As the network gains capacity to handle additional load, this algorithm can be tuned to increase the gas consumption rate.

#### A note on $e^x$

There is a subtle reason why an exponential adjustment function was chosen: The adjustment function should be _equally_ reactive irrespective of the actual fee.

Define $b_n$ as the current block's gas fee, $b_{n+1}$ as the next block's gas fee, and $x$ as the excess gas consumption.

Let's use a linear adjustment function:

$$b_{n+1} = b_n + 10x$$

Assume $b_n = 100$ and the current block is 1 unit above target utilization, or $x = 1$. Then, $b_{n+1} = 100 + 10 \cdot 1 = 110$, an increase of `10%`. If instead $b_n = 10,000$, $b_{n+1} = 10,000 + 10 \cdot 1 = 10,010$, an increase of `0.1%`. The fee is _less_ reactive as the fee increases. This is because the rate of change _does not scale_ with $x$.

Now, let's use an exponential adjustment function:

$$b_{n+1} = b_n \cdot e^x$$

Assume $b_n = 100$ and the current block is 1 unit above target utilization, or $x = 1$. Then, $b_{n+1} = 100 \cdot e^1 \approx 271.828$, an increase of `171%`. If instead $b_n = 10,000$, $b_{n+1} = 10,000 \cdot e^1 \approx 27,182.8$, an increase of `171%` again. The fee is _equally_ reactive as the fee increases. This is because the rate of change _scales_ with $x$.

### Block Building Procedure

When a transaction is constructed on the P-Chain, the amount of $AVAX burned is given by `sum($AVAX outputs) - sum($AVAX inputs)`. The amount of gas consumed by the transaction can be deterministically calculated after construction. Dividing the amount of $AVAX burned by the amount of gas consumed yields the maximum gas price that the transaction can pay.

Instead of using a FIFO queue for the mempool (like the P-Chain does now), the mempool should use a priority queue ordered by the maximum gas price of each transaction. This ensures that higher paying transactions are included first.

## Backwards Compatibility

Modification of a fee mechanism is an execution change and requires a mandatory upgrade for activation. Implementers must take care to not alter the execution behavior prior to activation.

After this ACP is activated, any transaction issued on the P-Chain must account for the fee mechanism defined above. Users are responsible for reconstructing their transactions to include a larger fee for quicker inclusion when the fee increases.

## Reference Implementation

ACP-103 was implemented into AvalancheGo behind the `Etna` upgrade flag. The full body of work can be found tagged with the `acp103` label [here](https://github.com/ava-labs/avalanchego/pulls?q=is%3Apr+label%3Aacp103).

## Security Considerations

The current fixed fee mechanism on the X-Chain and P-Chain does not robustly handle spikes in load. Migrating the P-Chain to a dynamic fee mechanism will ensure that any additional load caused by demand for new P-Chain features (such as those introduced in [ACP-77](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/77-reinventing-subnets/README.md)) is properly priced given allotted processing capacity. The X-Chain, in comparison, currently has significantly lower usage, making it less likely for the demand for blockspace on it to exceed the current static fee rates. If necessary or desired, a future ACP can reuse the mechanism introduced here to add dynamic fee rates to the X-Chain.

## Acknowledgements

Thank you to [@aaronbuchwald](https://github.com/aaronbuchwald) and [@patrick-ogrady](https://github.com/patrick-ogrady) for providing feedback prior to publication.

Thank you to the authors of [EIP-4844](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-4844.md) for creating the fee design that inspired the above mechanism.

## Copyright

Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

# ACP-108: Evm Event Importing (/docs/acps/108-evm-event-importing)

---
title: "ACP-108: Evm Event Importing"
description: "Details for Avalanche Community Proposal 108: Evm Event Importing"
edit_url: https://github.com/avalanche-foundation/ACPs/edit/main/ACPs/108-evm-event-importing/README.md
---

| ACP | 108 |
| :--- | :--- |
| **Title** | EVM Event Importing Standard |
| **Author(s)** | Michael Kaplan ([@mkaplan13](https://github.com/mkaplan13)) |
| **Status** | Proposed ([Discussion](https://github.com/avalanche-foundation/ACPs/discussions/114)) |
| **Track** | Best Practices Track |

## Abstract

Defines a standard smart contract interface and abstract implementation for importing EVM events from any blockchain within Avalanche using [Avalanche Warp Messaging](https://docs.avax.network/build/cross-chain/awm/overview).

## Motivation

The implementation of Avalanche Warp Messaging within `coreth` and `subnet-evm` exposes a [mechanism for getting authenticated hashes of blocks](https://github.com/ava-labs/subnet-evm/blob/master/contracts/contracts/interfaces/IWarpMessenger.sol#L43) that have been accepted on blockchains within Avalanche. Proofs of acceptance of blocks, such as those introduced in [ACP-75](https://github.com/avalanche-foundation/ACPs/tree/main/ACPs/75-acceptance-proofs), can be used to prove arbitrary events and state changes that occured in those blocks. However, there is currently no clear standard for using authenticated block hashes in smart contracts within Avalanche, making it difficult to build applications that leverage this mechanism. In order to make effective use of authenticated block hashes, contracts must be provided encoded block headers that match the authenticated block hashes and also Merkle proofs that are verified against the state or receipts root contained in the block header. 

With a standard interface and abstract contract implemetation that handles the authentication of block hashes and verification of Merkle proofs, smart contract developers on Avalanche will be able to much more easily create applications that leverage data from other Avalanche blockchains. These type of cross-chain application do not require any direct interaction on the source chain.

## Specification

### Event Importing Interface

We propose that smart contracts importing EVM events emitted by other blockchains within Avalanche implement the following interface.

#### Methods

Imports the EVM event uniquely identified by the source blockchain ID, block header, transaction index, and log index.

The `blockHeader` must be validated to match the authenticated block hash from the `sourceBlockchainID`. The specification for EVM block headers can be found [here](https://github.com/ava-labs/subnet-evm/blob/master/core/types/block.go#L73).

The `txIndex` identifies the key of receipts trie of the given block header that the `receiptProof` must prove inclusion of. The value obtained by verifying the `receiptProof` for that key is the encoded transaction receipt. The specification for EVM transaction receipts can be found [here](https://github.com/ava-labs/subnet-evm/blob/master/core/types/receipt.go#L62).

The `logIndex` identifies which event log from the given transaction receipt is to be imported.

Must emit an `EventImported` event upon success. 

```solidity
function importEvent(
    bytes32 sourceBlockchainID,
    bytes calldata blockHeader,
    uint256 txIndex,
    bytes[] calldata receiptProof,
    uint256 logIndex
) external;
```

This interface does not require that the Warp precompile is used to authenticate block hashes. Implementations could:
- Use the Warp precompile to authenticate block hashes provided directly in the transaction calling `importEvent`.
- Check previously authenticated block hashes using an external contract. 
    - Allows for a block hash to be authenticated once and used in arbitrarily many transactions afterwards.
    - Allows for alternative authentication mechanisms to be used, such as trusted oracles.


#### Events

Must trigger when an EVM event is imported.

```solidity
event EventImported(
    bytes32 indexed sourceBlockchainID,
    bytes32 indexed sourceBlockHash,
    address indexed loggerAddress,
    uint256 txIndex,
    uint256 logIndex
);
```

### Event Importing Abstract Contract

Applications importing EVM events emitted by other blockchains within Avalanche should be able to use a standard abstract implementation of the `importEvent` interface. This abstract implementation must handle:
- Authenticating block hashes from other chains.
- Verifying that the encoded `blockHeader` matches the imported block hash.
- Verifying the Merkle `receiptProof` for the given `txIndex` against the receipt root of the provided `blockHeader`.
- Decoding the event log identified by `logIndex` from the receipt obtained from verifying the `receiptProof`.

As noted above, implementations could directly use the Warp precompile's `getVerifiedWarpBlockHash` interface method for authenticating block hashes, as is done in the reference implementation [here](https://github.com/ava-labs/event-importer-poc/blob/main/contracts/src/EventImporter.sol#L51). Alternatively, implementations could use the `sourceBlockchainID` and `blockHeader` provided in the parameters to check with an external contract that the block has been accepted on the given chain. The specifics of such an external contract are outside the scope of this ACP, but for illustrative purposes, this could look along the lines of:

```solidity
bool valid = blockHashRegistry.checkAuthenticatedBlockHash(
    sourceBlockchainID,
    keccack256(blockHeader)
);
require(valid, "Invalid block header");
```

Inheriting contracts should only need to define the logic to be executed when an event is imported. This is done by providing an implementation of the following internal function, called by `importEvent`.

```solidity
function _onEventImport(EVMEventInfo memory eventInfo) internal virtual;
```

Where the `EVMEventInfo` struct is defined as:

```solidity
struct EVMLog {
    address loggerAddress;
    bytes32[] topics;
    bytes data;
}

struct EVMEventInfo {
    bytes32 blockchainID;
    uint256 blockNumber;
    uint256 txIndex;
    uint256 logIndex;
    EVMLog log;
}
```

The `EVMLog` struct is meant to match the `Log` type definition in the EVM [here](https://github.com/ava-labs/subnet-evm/blob/master/core/types/log.go#L39).

## Reference Implementation

See reference implementation on [Github here](https://github.com/ava-labs/event-importer-poc).

In addition to implementing the interface and abstract contract described above, the reference implementation shows how transactions can be constructed to import events using Warp block hash signatures.

## Open Questions

See [here](https://github.com/ava-labs/event-importer-poc?tab=readme-ov-file#open-questions-and-considerations).

## Security Considerations

The correctness of a contract using block hashes to prove that a specific event was emitted within that block depends on the correctness of:
1. The mechanism for authenticating that a block hash was finalized on another blockchain.
2. The Merkle proof validation library used to prove that a specific transaction receipt was included in the given block.

For considerations on using Avalanche Warp Messaging to authenticate block hashes, see [here](https://github.com/avalanche-foundation/ACPs/tree/main/ACPs/30-avalanche-warp-x-evm#security-considerations).

To improve confidence in the correctness of the Merkle proof validation used in implementations, well-audited and widely used libraries should be used.

## Acknowledgements

Using Merkle proofs to verify events/state against root hashes is not a new idea. Protocols such as [IBC](https://ibc.cosmos.network/v8/), [Rainbow Bridge](https://github.com/Near-One/rainbow-bridge), and [LayerZero](https://layerzero.network/publications/LayerZero_Whitepaper_V1.1.0.pdf), among others, have previously suggested using Merkle proofs in a similar manner.

Thanks to [@aaronbuchwald](https://github.com/aaronbuchwald) for proposing the `getVerifiedWarpBlockHash` interface be included in the AWM implemenation within Avalanche EVMs, which enables this type of use case.

## Copyright

Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

# ACP-113: Provable Randomness (/docs/acps/113-provable-randomness)

---
title: "ACP-113: Provable Randomness"
description: "Details for Avalanche Community Proposal 113: Provable Randomness"
edit_url: https://github.com/avalanche-foundation/ACPs/edit/main/ACPs/113-provable-randomness/README.md
---

| ACP           | 113                                                                                   |
| :------------ | :------------------------------------------------------------------------------------ |
| **Title**     | Provable Virtual Machine Randomness                                                   |
| **Author(s)** | Tsachi Herman [http://github.com/tsachiherman](http://github.com/tsachiherman)                                        |
| **Status**    | Stale ([Discussion](https://github.com/avalanche-foundation/ACPs/discussions/142)) |
| **Track**     | Standards                                                                             |

## Future Work

This ACP was marked as stale due to its documented security concerns.

In order to safely utilize randomness produced by this mechanism, the consumer of the randomness must:

1. Define a security threshold `x` which is the maximum number of consecutive blocks which can be proposed by a malicious entity.
2. After committing to a request for randomness, the consumer must wait for `x` blocks.
3. After waiting for `x` blocks, the consumer must verify that the randomness was not biased during the `x` blocks.
4. If the randomness was biased, it would be insufficient to request randomness again, as this would allow the malicious block producer to discard any randomness that it did not like. If using the randomness mechanism proposed in this ACP, the consumer of the randomness must be able to terminate the request for randomness in such a way that no participant would desire the outcome. Griefing attacks would likely result from such a construction.

### Alternative Mechanisms

There are alternative mechanisms that would not result in such security concerns, such as:

- Utilizing a deterministic threshold signature scheme to finalize a block in consensus would allow the threshold signature to be used during the execution of the block.
- Utilizing threshold commit-reveal schemes that guarantee that committed values will always be revealed in a timely manner.

However, these mechanisms are likely too costly to be introduced into the Avalanche Primary Network due to its validator set size.

It is left to a future ACP to specify the implementation of one of these alternative schemes for L1 networks with smaller sized validator sets.

## Abstract

Avalanche offers developers flexibility through subnets and EVM-compatible smart contracts. However, the platform's deterministic block execution limits the use of traditional random number generators within these contracts.

To address this, a mechanism is proposed to generate verifiable, non-cryptographic random number seeds on the Avalanche platform. This method ensures uniformity while allowing developers to build more versatile applications.

## Motivation

Reliable randomness is essential for building exciting applications on Avalanche. Games, participant selection, dynamic content, supply chain management, and decentralized services all rely on unpredictable outcomes to function fairly. Randomness also fuels functionalities like unique identifiers and simulations. Without a secure way to generate random numbers within smart contracts, Avalanche applications become limited.

Avalanche's traditional reliance on external oracles for randomness creates complexity and bottlenecks. These oracles inflate costs, hinder transaction speed, and are cumbersome to integrate. As Avalanche scales to more Subnets, this dependence on external systems becomes increasingly unsustainable.

A solution for verifiable random number generation within Avalanche solves these problems. It provides fair randomness functionality across the chains, at no additional cost. This paves the way for a more efficient Avalanche ecosystem.

## Specification

### Changes Summary

The existing Avalanche protocol breaks the block building into two parts : external and internal. The external block is the Snowman++ block, whereas the internal block is the actual virtual machine block.

To support randomness, a BLS based VRF implementation is used, that would be recursively signing its own signatures as its message. Since the BLS signatures are deterministic, they provide a great way to construct a reliable VRF.

For proposers that do not have a BLS key associated with their node, the hash of the signature from the previous round is used in place of their signature.

In order to bootstrap the signatures chain, a missing signature would be replaced with a byte slice that is the hash product of a verifiable and trustable seed.

The changes proposed here would affect the way a blocks are validated. Therefore, when this change gets implemented, it needs to be deployed as a mandatory upgrade.

```
		+-----------------------+           +-----------------------+
		|  Block n              | <-------- |  Block n+1            |
		+-----------------------+           +-----------------------+
		|  VRF-Sig(n)           |           |  VRF-Sig(n+1)         |
		|  ...                  |           |  ...                  |
		+-----------------------+           +-----------------------+

		+-----------------------+           +-----------------------+
		|  VM n                 |           |  VM n+1               |
		+-----------------------+           +-----------------------+
		|  VRF-Out(n)           |           |  VRF-Out(n+1)         |
		+-----------------------+           +-----------------------+

		VRF-Sig(n+1) = Sign(VRF-Sig(n), Block n+1 proposer's BLS key)
		VRF-Out(n) = Hash(VRF-Sig(n))
```

### Changes Details

#### Step 1. Adding BLS signature to proposed blocks

```go
type statelessUnsignedBlock struct {
	…
	vrfSig    []byte `serialize:”true”`
}
```

#### Step 2. Populate signature

When a block proposer attempts to build a new block, it would need to use the parent block as a reference.

The `vrfSig` field within each block is going to be daisy-chained to the `vrfSig` field from it's parent block.

Populating the `vrfSig` would following this logic:

1. The current proposer has a BLS key

	a. If the parent block has an empty `vrfSig` signature, the proposer would sign the bootStrappingBlockSignature with its BLS key. See the bootStrappingBlockSignature details below. This is the base case.

	b. If the parent block does not have an empty `vrfSig` signature, that signature would be signed using the proposer’s BLS key. 

2. The current proposer does not have a BLS key
   
   a. If the parent block has a non-empty `vrfSig` signature, the proposer would set the proposed block `vrfSig` to the 32 byte hash result of the following preimage:
	```
	+-------------------------+----------+------------+
	|  prefix :               | [8]byte  | "rng-derv" |
	+-------------------------+----------+------------+
	|  vrfSig :               | [96]byte |  96 bytes  |
	+-------------------------+----------+------------+
	```

	b. If the parent block has an empty `vrfSig` signature, the proposer would leave the `vrfSig` on the new block empty.

The bootStrappingBlockSignature that would be used above is the hash of the following preimage:

```
+-----------------------+----------+------------+
|  prefix :             | [8]byte  | "rng-root" |
+-----------------------+----------+------------+
|  networkID:           | uint32   |  4 bytes   |
+-----------------------+----------+------------+
|  chainID :            | [32]byte |  32 bytes  |
+-----------------------+----------+------------+
```

#### Step 3. Signature Verification

This signature verification would perform the exact opposite of what was done in step 2, and would verify the cryptographic correctness of the operation.

Validating the `vrfSig` would following this logic:
1. The proposer has a BLS key

	a. If the parent block's `vrfSig` was non-empty , then the `vrfSig` in the proposed block is verified to be a valid BLS signature of the parent block's `vrfSig` value for the proposer's BLS public key.

	b. If the parent block's `vrfSig` was empty, then a BLS signature verification of the proposed block `vrfSig` against the proposer’s BLS public key and bootStrappingBlockSignature would take place.

2. The proposer does not have a BLS key

	a. If the parent block had a non-empty `vrfSig`, then the hash of the preimage ( as described above ) would be compared against the proposed `vrfSig`.

	b. If the parent block has an empty `vrfSig` then the proposer's `vrfSig` would be validated to be empty.

#### Step 4. Extract the VRF Out and pass to block builders

Calculating the VRF Out would be done by hashing the preimage of the following struct:

```
+-----------------------+----------+------------+
|  prefix :             | [8]byte  | "vrfout  " |
+-----------------------+----------+------------+
|  vrfout:              | [96]byte |  96 bytes  |
+-----------------------+----------+------------+
```

Before calculating the VRF Out, the method needs to explicitly check the case where the `vrfSig` is empty. In that case, the output of the VRF Out needs to be empty as well.

## Backwards Compatibility

The above design has taken backward compatibility considerations. The chain would keep working as before, and at some point, would have the newly added `vrfSig` populated.

From usage perspective, each VM would need to make its own decision on whether it should use the newly provided random seed. Initially, this random seed would be all zeros - and would get populated once the feature rolled out to a sufficient number of nodes.

Also, as mentioned in the summary, these changes would necessitate a network upgrade.

## Reference Implementation

A full reference implementation has not been provided yet. It will be provided once this ACP is considered `Implementable`.

## Security Considerations

Virtual machine random seeds, while appearing to offer a source of randomness within smart contracts, fall short when it comes to cryptographic security. Here's a breakdown of the critical issues:

- Limited Permutation Space: The number of possible random values is derived from the number of validators. While no validator, nor a validator set, would be able to manipulate the randomness into any single value, a nefarious actor(s) might be able to exclude specific numbers.
- Predictability Window: The seed value might be accessible to other parties before the smart contract can benefit from its uniqueness. This predictability window creates a vulnerability. An attacker could potentially observe the seed generation process and predict the sequence of "random" numbers it will produce, compromising the entire cryptographic foundation of your smart contract.

Despite these limitations appearing severe, attackers face significant hurdles to exploit them. First, the attacker can't control the random number, limiting the attack's effectiveness to how that number is used. Second, a substantial amount of AVAX is needed. And last, such an attack would likely decrease AVAX's value, hurting the attacker financially.

One potential attack vector involves collusion among multiple proposers to manipulate the random number selection. These attackers could strategically choose to propose or abstain from proposing blocks, effectively introducing a bias into the system. By working together, they could potentially increase their chances of generating a random number favorable to their goals.

However, the effectiveness of this attack is significantly limited for the following reasons:
- Limited options: While colluding attackers expand their potential random number choices, the overall pool remains immense (2^256 possibilities). This drastically reduces their ability to target a specific value.
- Protocol's countermeasure: The protocol automatically eliminates any bias introduced by previous proposals once an honest proposer submits their block.
- Detectability: Exploitation of this attack vector is readily identifiable. A successful attack necessitates coordinated collusion among multiple nodes to synchronize their proposer slots for a specific block height ( the proposer slot order are known in advance ). Subsequent to this alignment, a designated node constructs the block proposal. The network maintains a record of the proposer slot utilized for each block. A value of zero for the proposer slot unequivocally indicates the absence of an exploit. Increasing values correlate with a heightened risk of exploitation. It is important to note that non-zero slot numbers may also arise from transient network disturbances.

While this attack is theoretically possible, its practical impact is negligible due to the vast number of potential outcomes and the protocol's inherent safeguards.

## Open Questions

### How would the proposed changes impact the proposer selection and their inherit bias ?

The proposed modifications will not influence the selection process for block proposers.
Proposers retain the ability to determine which transactions are included in a block.
This inherent proposer bias remains unchanged and is unaffected by the proposed changes.

## Copyright

Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

# ACP-118: Warp Signature Request (/docs/acps/118-warp-signature-request)

---
title: "ACP-118: Warp Signature Request"
description: "Details for Avalanche Community Proposal 118: Warp Signature Request"
edit_url: https://github.com/avalanche-foundation/ACPs/edit/main/ACPs/118-warp-signature-request/README.md
---

| ACP | 118 |
| :--- | :--- |
| **Title** | Warp Signature Interface Standard |
| **Author(s)** | Cam Schultz ([@cam-schultz](https://github.com/cam-schultz)) |
| **Status** | Activated ([Discussion](https://github.com/avalanche-foundation/ACPs/discussions/123)) |
| **Track** | Best Practices Track |

## Abstract

Proposes a standard [AppRequest](https://github.com/ava-labs/avalanchego/blob/master/proto/p2p/p2p.proto#L385) payload format type for requesting Warp signatures for the provided bytes, such that signatures may be requested in a VM-agnostic manner. To make this concrete, this standard type should be defined in AvalancheGo such that VMs can import it at the source code level. This will simplify signature aggregator implementations by allowing them to depend only on AvalancheGo for message construction, rather than individual VM codecs.

## Motivation

Warp message signatures consist of an aggregate BLS signature composed of the individual signatures of a subnet's validators. Individual signatures need to be retreivable by the party that wishes to construct an aggregate signature. At present, this is left to VMs to implement, as is the case with [Subnet EVM](https://github.com/ava-labs/subnet-evm/blob/v0.6.7/plugin/evm/message/signature_request.go#20) and [Coreth](https://github.com/ava-labs/coreth/blob/v0.13.6-rc.0/plugin/evm/message/signature_request.go#L20)

This creates friction in applications that are intended to operate across many VMs (or distinct implementations of the same VM). As an example, the reference Warp message relayer implementation, [awm-relayer](https://github.com/ava-labs/awm-relayer), fetches individual signatures from validators and aggregates them before sending the Warp message to its destination chain for verification. However, Subnet EVM and Coreth have distinct codecs, requiring the relayer to [switch](https://github.com/ava-labs/awm-relayer/blob/v1.4.0-rc.0/relayer/application_relayer.go#L372) according to the target codebase.

Another example is ACP-75, which aims to implement acceptance proofs using Warp. The signature aggregation mechanism is not [specified](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/75-acceptance-proofs/README.md#signature-aggregation), which is a blocker for that ACP to be marked implementable.

Standardizing the Warp Signature Request interface by defining it as a format for `AppRequest` message payloads in AvalancheGo would simplify the implementation of ACP-75, and streamline signature aggregation for out-of-protocol services such as Warp message relayers.

## Specification

We propose the following types, implemented as Protobuf types that may be decoded from the `AppRequest`/`AppResponse` `app_bytes` field. By way of example, this approach is currently used to [implement](https://github.com/ava-labs/avalanchego/blob/v1.11.10-status-removal/proto/sdk/sdk.proto#7) and [parse](https://github.com/ava-labs/avalanchego/blob/v1.11.10-status-removal/network/p2p/gossip/message.go#22) gossip `AppRequest` types.

- `SignatureRequest` includes two fields. `message` specifies the payload that the returned signature should correspond to, namely a serialized unsigned Warp message. `justification` specifies arbitrary data that the requested node may use to decide whether or not it is willing to sign `message`. `justification` may not be required by every VM implementation, but `message` should always contain the bytes to be signed. It is up to the VM to define the validity requirements for the `message` and `justification` payloads.

    ```protobuf
    message SignatureRequest {
        bytes message = 1;
        bytes justification = 2;
    }
    ```

- `SignatureResponse` is the corresponding `AppResponse` type that returns the requested signature. 

    ```protobuf
    message SignatureResponse {
        bytes signature = 1;
    }
    ```

### Handlers

For each of the above types, VMs must implement corresponding `AppRequest` and `AppResponse` handlers. The `AppRequest` handler should be [registered](https://github.com/ava-labs/avalanchego/blob/v1.11.10-status-removal/network/p2p/network.go#L173) using the canonical handler ID, defined as `2`.

## Use Cases

Generally speaking, `SignatureRequest` can be used to request a signature over a Warp message by serializing the unsigned Warp message into `message`, and populating `justification` as needed.

### Sign a known Warp Message

Subnet EVM and Coreth store messages that have been seen (i.e. on-chain message sent through the [Warp Precompile](https://github.com/ava-labs/subnet-evm/tree/v0.6.7/precompile/contracts/warp) and [off-chain](https://github.com/ava-labs/subnet-evm/blob/v0.6.7/plugin/evm/config.go#L226) Warp messages) such that a signature over that message can be provided on request. `SignatureRequest` can be used for this case by specifying the Warp message in `message`. The queried node may then look up the Warp message in its database and return the signature. In this case, `justification` is not needed.

### Attest to an on-chain event

Subnet EVM and Coreth also support attesting to block hashes via Warp, by serving signature requests made using the following `AppRequest` type:

```
type BlockSignatureRequest struct {
	BlockID ids.ID
}
```

`SignatureRequest` can achieve this by specifying an unsigned Warp message with the `BlockID` as the payload, and serializing that message into `message`. `justification` may optionally be used to provide additional context, such as a the block height of the given block ID.

### Confirm that an event did not occur

With [ACP-77](https://github.com/avalanche-foundation/ACPs/tree/main/ACPs/77-reinventing-subnets), Subnets will have the ability to manage their own validator sets. The Warp message payload contained in a `RegisterSubnetValidatorTx` includes an `expiry`, after which the specified validation ID (i.e. a unique hash over the Subnet ID, node ID, stake weight, and expiry) becomes invalid. The Subnet needs to know that this validation ID is expired so that it can keep its locally tracked validator set in sync with the P-Chain. We also assume that the P-Chain will not persist expired or invalid validation IDs. 

We can use `SignatureRequest` to construct a Warp message attesting that the validation ID expired. We do so by serializing an unsigned Warp message containing the validation ID into `message`, and providing the validation ID hash preimage in `justification` for the P-Chain to reconstruct the expired validation ID.

## Security Considerations

VMs have full latitude when implementing `SignatureRequest` handlers, and should take careful consideration of what `message` payloads their implementation should be willing to sign, given a `justification`. Some considerations include, but are not limited to:
- Input validation. Handlers should validate `message` and `justification` payloads to ensure that they decode to coherent types, and that they contain only expected data.
- Signature DoS. AvalancheGo's peer-to-peer networking stack implements message rate limiting to mitigate the risk of DoS, but VMs should also consider the cost of parsing and signing a `message` payload.
- Payload collision. `message` payloads should be implemented as distinct types that do not overlap with one another within the context of signed Warp messages from the VM. For instance, a `message` payload specifying 32-byte hash may be interpreted as a transaction hash, a block hash, or a blockchain ID.

## Backwards Compatibility

This change is backwards compatible for VMs, as nodes running older versions that do not support the new message types will simply drop incoming messages.

## Reference Implementation

A reference implementation containing the Protobuf types and the canonical handler ID can be found [here](https://github.com/ava-labs/avalanchego/pull/3218).

## Acknowledgements

Thanks to @joshua-kim, @iansuvak, @aaronbuchwald, @michaelkaplan13, and @StephenButtolph for discussion and feedback on this ACP.

## Copyright

Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

# ACP-125: Basefee Reduction (/docs/acps/125-basefee-reduction)

---
title: "ACP-125: Basefee Reduction"
description: "Details for Avalanche Community Proposal 125: Basefee Reduction"
edit_url: https://github.com/avalanche-foundation/ACPs/edit/main/ACPs/125-basefee-reduction/README.md
---

| ACP | 125 |
| :--- | :--- |
| **Title** | Reduce C-Chain minimum base fee from 25 nAVAX to 1 nAVAX |
| **Author(s)** | Stephen Buttolph ([@StephenButtolph](https://github.com/StephenButtolph)), Darioush Jalali ([@darioush](https://github.com/darioush)) |
| **Status** | Activated ([Discussion](https://github.com/avalanche-foundation/ACPs/discussions/127)) |
| **Track** | Standards |

## Abstract

Reduce the minimum base fee on the Avalanche C-Chain from 25 nAVAX to 1 nAVAX.

## Motivation

With dynamic fees, the gas price is supposed to be a result of a continuous auction such that the consumed gas per second converges to the target gas usage per second.

When dynamic fees were first introduced, safeguards were added to ensure the mechanism worked as intended, such as a relatively high minimum gas price and a maximum gas price.

The maximum gas price has since been entirely removed. The minimum gas price has been reduced significantly. However, the base fee is often observed pinned to this minimum. This shows that it is higher than what the market demands, and therefore it is artificially reducing network usage.

## Specification

The dynamic fee calculation currently must enforce a minimum base fee of 25 nAVAX.

This change proposes reducing the minimum base fee to 1 nAVAX upon the next network upgrade activation.

## Backwards Compatibility

Modifies the consensus rules for the C-Chain, therefore it requires a network upgrade.

## Reference Implementation

A draft implementation of this ACP for the coreth VM can be found [here](https://github.com/ava-labs/coreth/pull/604/files).

## Security Considerations

Lower gas costs may increase state bloat. However, we note that the dynamic fee algorithm responded appropriately during periods of high use (such as Dec. 2023), which gives reasonable confidence that enforcing a 25 nAVAX minimum fee is no longer necessary.

## Open Questions

N/A

## Copyright

Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

# ACP-13: Subnet Only Validators (/docs/acps/13-subnet-only-validators)

---
title: "ACP-13: Subnet Only Validators"
description: "Details for Avalanche Community Proposal 13: Subnet Only Validators"
edit_url: https://github.com/avalanche-foundation/ACPs/edit/main/ACPs/13-subnet-only-validators/README.md
---

| ACP | 13 |
| :--- | :--- |
| **Title** | Subnet-Only Validators (SOVs) |
| **Author(s)** | Patrick O'Grady ([contact@patrickogrady.xyz](mailto:contact@patrickogrady.xyz)) |
| **Status** | Stale |
| **Track** | Standards |
| **Superseded-By** | [ACP-77](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/77-reinventing-subnets/README.md) |

## Abstract

Introduce a new type of staker, Subnet-Only Validators (SOVs), that can validate an Avalanche Subnet and participate in Avalanche Warp Messaging (AWM) without syncing or becoming a Validator on the Primary Network. Require SOVs to pay a refundable fee of 500 $AVAX on the P-Chain to register as a Subnet Validator instead of staking at least 2000 $AVAX, the minimum requirement to become a Primary Network Validator. Preview a future transition to Pay-As-You-Go Subnet Validation and $AVAX-Augmented Subnet Security.

_This ACP does not modify/deprecate the existing Subnet Validation semantics for Primary Network Validators._

## Motivation

Each node operator must stake at least 2000 $AVAX ($20k at the time of writing) to first become a Primary Network Validator before they qualify to become a Subnet Validator. Most Subnets aim to launch with at least 8 Subnet Validators, which requires staking 16000 $AVAX ($160k at time of writing). All Subnet Validators, to satisfy their role as Primary Network Validators, must also [allocate 8 AWS vCPU, 16 GB RAM, and 1 TB storage](https://github.com/ava-labs/avalanchego/blob/master/README.md#installation) to sync the entire Primary Network (X-Chain, P-Chain, and C-Chain) and participate in its consensus, in addition to whatever resources are required for each Subnet they are validating.

Avalanche Warp Messaging (AWM), the native interoperability mechanism for the Avalanche Network, provides a way for Subnets to communicate with each other/C-Chain without a trusted intermediary. Any Subnet Validator must be able to register a BLS key and participate in AWM, otherwise a Subnet may not be able to generate a BLS Multi-Signature with sufficient participating stake.

Regulated entities that are prohibited from validating permissionless, smart contract-enabled blockchains (like the C-Chain) can’t launch a Subnet because they can’t opt-out of Primary Network Validation. This deployment blocker prevents a large cohort of Real World Asset (RWA) issuers from bringing unique, valuable tokens to the Avalanche Ecosystem (that could move between C-Chain &lt;-&gt; Subnets using AWM/Teleporter).

A widely validated Subnet that is not properly metered could destabilize the Primary Network if usage spikes unexpectedly. Underprovisioned Primary Network Validators running such a Subnet may exit with an OOM exception, see degraded disk performance, or find it difficult to allocate CPU time to P/X/C-Chain validation. The inverse also holds for Subnets with the Primary Network (where some undefined behavior could bring a Subnet offline).

Although the fee paid to the Primary Network to operate a Subnet does not go up with the amount of activity on the Subnet, the fixed, upfront cost of setting up a Subnet Validator on the Primary Network deters new projects that prefer smaller, even variable, costs until demand is observed. _Unlike L2s that pay some increasing fee (usually denominated in units per transaction byte) to an external chain for data availability and security as activity scales, Subnets provide their own security/data availability and the only cost operators must pay from processing more activity is the hardware cost of supporting additional load._

Elastic Subnets allow any community to weight Subnet Validation based on some staking token and reward Subnet Validators with high uptime with said staking token. However, there is no way for $AVAX holders on the Primary Network to augment the security of such Subnets.

## Specification

### Required Changes

1) Introduce a new type of staker, Subnet-Only Validators (SOVs), that can validate an Avalanche Subnet and participate in Avalanche Warp Messaging (AWM) without syncing or becoming a Validator on the Primary Network
2) Introduce a refundable fee (called a "lock") of 500 $AVAX that nodes must pay to become an SOV
3) Introduce a non-refundable fee of 0.1 $AVAX that SOVs must pay to become an SOV
4) Introduce a new transaction type on the P-Chain to register as an SOV (i.e. `AddSubnetOnlyValidatorTx`)
5) Add a mode to ANCs that allows SOVs to optionally disable full Primary Network verification (only need to verify P-Chain)
6) ANCs track IPs for SOVs to ensure Subnet Validators can find peers whether or not they are Primary Network Validators
7) Provide a guaranteed rate limiting allowance for SOVs like Primary Network Validators

Because SOVs do not validate the Primary Network, they will not be rewarded with $AVAX for "locking" the 500 $AVAX required to become an SOV. This enables people interested in validating Subnets to opt for a lower upfront $AVAX commitment and lower infrastructure costs instead of $AVAX rewards. Additionally, SOVs will only be required to sync the P-chain (not X/C-Chain) to track any validator set changes in their Subnet and to support Cross-Subnet communication via AWM (see “Primary Network Partial Sync” mode introduced in [Cortina 8](https://github.com/ava-labs/avalanchego/releases/tag/v1.10.8)). The lower resource requirement in this "minimal mode" will provide Subnets with greater flexibility of validation hardware requirements as operators are not required to reserve any resources for C-Chain/X-Chain operation. If an SOV wishes to sync the entire Primary Network, they still can.

### Future Work

The previously described specification is a minimal, additive change to Subnet Validation semantics that prepares the Avalanche Network for a more flexible Subnet model. It alone, however, fails to communicate this flexibility nor provides an alternative use of $AVAX that would have otherwise been used to create Subnet Validators.

Below are two high-level ideas (Pay-As-You-Go Subnet Validation Registration Fees and $AVAX-Augmented Security) that highlight how this initial change could be extended in the future. If the Avalanche Community is interested in their adoption, they should each be proposed as a unique ACP where they can be properly specified. **These ideas are only suggestions for how the Avalanche Network could be modified in the future if this ACP is adopted. Supporting this ACP does not require supporting these ideas or committing to their rollout.**

#### Pay-As-You-Go Subnet Validation Registration Fees

_Transition Subnet Validator registration to a dynamically priced, continuously charged fee (that doesn't require locking large amounts of $AVAX upfront)._

While it would be possible to just transition to a lower required "lock" amount, many think that it would be more competitive to transition to a dynamically priced, continuous payment mechanism to register as a Subnet Validator. This new mechanism would target some $Y nAVAX fee that would be paid by each Subnet Validator per Subnet per second (pulling from a "Subnet Validator's Account") instead of requiring a large upfront lockup of $AVAX.

The rate of nAVAX/second should be set by the demand for validating Subnets on Avalanche compared to some usage target per Subnet and across all Subnets. This rate should be locked for each Subnet Validation period to ensure operators are not subject to surprise costs if demand rises significantly over time. The optimization work outlined in [BLS Multi-Signature Voting](https://hackmd.io/@patrickogrady/100k-subnets#How-will-BLS-Multi-Signature-uptime-voting-work) should allow the min rate to be set as low as ~512-4096 nAVAX/second (or 1.3-10.6 $AVAX/month).

Fees paid to the Avalanche Network for PAYG could be burned, like all other P-Chain, X-Chain, and C-Chain transactions, or they could be partially rewarded to Primary Network Validators as a "boost" over the existing staking rewards. The nice byproduct of the latter approach is that it better aligns Primary Network Validators with the growth of Subnets.

#### $AVAX-Augmented Subnet Security

_Allow pledging unstaked $AVAX to Subnet Validators on Elastic Subnets that can be slashed if said Subnet Validator commits an attributable fault (i.e. proposes/signs conflicting blocks/AWM payloads). Reward locked $AVAX associated with Subnet Validators that were not slashed with Elastic Subnet staking rewards._

Currently, the only way to secure an Elastic Subnet is to stake its custom staking token (defined in the `TransformSubnetTx`). Many have requested the option to use $AVAX for this token, however, this could easily allow an adversary to take over small Elastic Subnets (where the amount of $AVAX staked may be much less than the circulating supply).

$AVAX-Augmented Subnet Security would allow anyone holding $AVAX to lock it to specific Subnet Validators and earn Elastic Subnet reward tokens for supporting honest participants. Recall, all stake management on the Avalanche Network (even for Subnets) occurs on the P-Chain. Thus, staked tokens ($AVAX and/or custom staking tokens used in Elastic Subnets) and stake weights (used for AWM verification) are secured by the full $AVAX stake of the Primary Network. $AVAX-Augmented Subnet Security, like staking, would be implemented on the P-Chain and enjoy the full security of the Primary Network. This approach means locking $AVAX occurs on the Primary Network (no need to transfer $AVAX to a Subnet, which may not be secured by meaningful value yet) and proofs of malicious behavior are processed on the Primary Network (a colluding Subnet could otherwise choose not to process a proof that would lead to their "lockers" being slashed).

_This native approach is comparable to the idea of using $ETH to secure DA on [EigenLayer](https://www.eigenlayer.xyz/) (without reusing stake) or $BTC to secure Cosmos Zones on [Babylon](https://babylonchain.io/) (but not using an external ecosystem)._

## Backwards Compatibility

* Existing Subnet Validation semantics for Primary Network Validators are not modified by this ACP. This means that All existing Subnet Validators can continue validating both the Primary Network and whatever Subnets they are validating. This change would just provide a new option for Subnet Validators that allows them to sacrifice their staking rewards for a smaller upfront $AVAX commitment and lower infrastructure costs.
* Support for this ACP would require adding a new transaction type to the P-Chain (i.e. `AddSubnetOnlyValidatorTx`). This new transaction is an execution-breaking change that would require a mandatory Avalanche Network upgrade to activate.

## Reference Implementation

A full implementation will be provided once this ACP is considered `Implementable`. However, some initial ideas are presented below.

### `AddSubnetOnlyValidatorTx`

```text
type AddSubnetOnlyValidatorTx struct {
	// Metadata, inputs and outputs
	BaseTx `serialize:"true"`
	// Describes the validator
	// The NodeID included in [Validator] must be the Ed25519 public key.
	Validator `serialize:"true" json:"validator"`
	// ID of the subnet this validator is validating
	Subnet ids.ID `serialize:"true" json:"subnetID"`
	// [Signer] is the BLS key for this validator.
	// Note: We do not enforce that the BLS key is unique across all validators.
	//       This means that validators can share a key if they so choose.
	//       However, a NodeID does uniquely map to a BLS key
	Signer signer.Signer `serialize:"true" json:"signer"`
	// Where to send locked tokens when done validating
	LockOuts []*avax.TransferableOutput `serialize:"true" json:"lock"`
	// Where to send validation rewards when done validating
	ValidatorRewardsOwner fx.Owner `serialize:"true" json:"validationRewardsOwner"`
	// Where to send delegation rewards when done validating
	DelegatorRewardsOwner fx.Owner `serialize:"true" json:"delegationRewardsOwner"`
	// Fee this validator charges delegators as a percentage, times 10,000
	// For example, if this validator has DelegationShares=300,000 then they
	// take 30% of rewards from delegators
	DelegationShares uint32 `serialize:"true" json:"shares"`
}
```

_`AddSubnetOnlyValidatorTx` is almost the same as [`AddPermissionlessValidatorTx`](https://github.com/ava-labs/avalanchego/blob/638000c42e5361e656ffbc27024026f6d8f67810/vms/platformvm/txs/add_permissionless_validator_tx.go#L33-L58), the only exception being that `StakeOuts` are now `LockOuts`._

### `GetSubnetPeers`

To support tracking SOV IPs, a new message should be added to the P2P specification that allows Subnet Validators to request the IP of all peers a node knows about on a Subnet (these Signed IPs won't be gossiped like they are for Primary Network Validators because they don't need to be known by the entire Avalanche Network):

```text
message GetSubnetPeers {
    bytes subnet_id = 1;
}
```

_It would be a nice addition if a bloom filter could also be provided here so that an ANC only sends IPs of peers that the original sender does not know._

ANCs should respond to this incoming message with a [`PeerList` message](https://github.com/ava-labs/avalanchego/blob/638000c42e5361e656ffbc27024026f6d8f67810/proto/p2p/p2p.proto#L135-L148).

## Security Considerations

* Any Subnet Validator running in "Partial Sync Mode" will not be able to verify Atomic Imports on the P-Chain and will rely entirely on Primary Network consensus to only accept valid P-Chain blocks.
* High-throughput Subnets will be better isolated from the Primary Network and should improve its resilience (i.e. surges of traffic on some Subnet cannot destabilize a Primary Network Validator).
* Avalanche Network Clients (ANCs) must track IPs and provide allocated bandwidth for SOVs even though they are not Primary Network Validators.

## Open Questions

* To help orient the Avalanche Community around this wide-ranging and likely to be long-running conversation around the relationship between the Primary Network and Subnets, should we come up with a project name to describe the effort? I've been casually referring to all of these things as the _Astra Upgrade Track_ but definitely up for discussion (may be more confusing than it is worth to do this).

## Appendix

A draft of this ACP was posted on in the ["Ideas" Discussion Board](https://github.com/avalanche-foundation/ACPs/discussions/10#discussioncomment-7373486), as suggested by the [ACP README](https://github.com/avalanche-foundation/ACPs#step-1-post-your-idea-to-github-discussions). Feedback on this draft was collected and addressed on both the "Ideas" Discussion Board and on [HackMD](https://hackmd.io/@patrickogrady/100k-subnets#Feedback-to-Draft-Proposal).

## Acknowledgements

Thanks to @luigidemeo1, @stephenbuttolph, @aaronbuchwald, @dhrubabasu, and @abi87 for their feedback on these ideas.

## Copyright

Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

# ACP-131: Cancun Eips (/docs/acps/131-cancun-eips)

---
title: "ACP-131: Cancun Eips"
description: "Details for Avalanche Community Proposal 131: Cancun Eips"
edit_url: https://github.com/avalanche-foundation/ACPs/edit/main/ACPs/131-cancun-eips/README.md
---

| ACP | 131 |
| :--- | :--- |
| **Title** | Activate Cancun EIPs on C-Chain and Subnet-EVM chains |
| **Author(s)** | Darioush Jalali ([@darioush](https://github.com/darioush)), Ceyhun Onur ([@ceyonur](https://github.com/ceyonur)) |
| **Status** | Activated ([Discussion](https://github.com/avalanche-foundation/ACPs/discussions/139)) |
| **Track** | Standards, Subnet |

## Abstract

Enable new EVM opcodes and opcode changes in accordance with the following EIPs on the Avalanche C-Chain and Subnet-EVM chains:
- [EIP-4844: BLOBHASH opcode](https://eips.ethereum.org/EIPS/eip-4844)
- [EIP-7516: BLOBBASEFEE opcode](https://eips.ethereum.org/EIPS/eip-7516)
- [EIP-1153: Transient storage](https://eips.ethereum.org/EIPS/eip-1153)
- [EIP-5656: MCOPY opcode](https://eips.ethereum.org/EIPS/eip-5656)
- [EIP-6780: SELFDESTRUCT only in same transaction](https://eips.ethereum.org/EIPS/eip-6780)

Note blob transactions from EIP-4844 are excluded and blocks containing them will still be considered invalid.

## Motivation

The listed EIPs were activated on Ethereum mainnet as part of the [Cancun upgrade](https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/cancun.md#included-eips). This proposal is to activate them on the Avalanche C-Chain in the next network upgrade, to maintain compatibility with upstream EVM tooling, infrastructure, and developer experience (e.g., Solidity compiler defaults &gt;= [0.8.25](https://github.com/ethereum/solidity/releases/tag/v0.8.25)). Additionally, it recommends the activation of the same EIPs on Subnet-EVM chains.

## Specification & Reference Implementation

The opcodes (EVM exceution modifications) and block header modifications should be adopted as specified in the EIPs themselves. Other changes such as enabling new transaction types or mempool modifications are not in scope (specifically blob transactions from EIP-4844 are excluded and blocks containing them are considered invalid). ANCs (Avalanche Network Clients) can adopt the implementation as specified in the [coreth](https://github.com/ava-labs/coreth) repository, which was adopted from the [go-ethereum v1.13.8](https://github.com/ethereum/go-ethereum/releases/tag/v1.13.8) release in this [PR](https://github.com/ava-labs/coreth/pull/550). In particular, note the following code:

- [Activation of new opcodes](https://github.com/ava-labs/coreth/blob/7b875dc21772c1bb9e9de5bc2b31e88c53055e26/core/vm/jump_table.go#L93)
- Activation of Cancun in next Avalanche upgrade:
  - [C-Chain](https://github.com/ava-labs/coreth/pull/610)
  - [Subnet-EVM chains](https://github.com/ava-labs/subnet-evm/blob/fa909031ed148484c5072d949c5ed73d915ce1ed/params/config_extra.go#L186)
- `ParentBeaconRoot` is enforced to be included and the zero value [here](https://github.com/ava-labs/coreth/blob/7b875dc21772c1bb9e9de5bc2b31e88c53055e26/plugin/evm/block_verification.go#L287-L288). This field is retained for future use and compatibility with upstream tooling.
- Forbids blob transactions by enforcing `BlobGasUsed` to be 0 [here](https://github.com/ava-labs/coreth/pull/611/files#diff-532a2c6a5365d863807de5b435d8d6475552904679fd611b1b4b10d3bf4f5010R267).

_Note:_ Subnets are sovereign in regards to their validator set and state transition rules, and can choose to opt out of this proposal by making a code change in their respective Subnet-EVM client.

## Backwards Compatibility

The original EIP authors highlighted the following considerations. For full details, refer to the original EIPs:

- [EIP-4844](https://eips.ethereum.org/EIPS/eip-4844#backwards-compatibility): Blob transactions are not proposed to be enabled on Avalanche, so concerns related to mempool or transaction data availability are not applicable.
- [EIP-6780](https://eips.ethereum.org/EIPS/eip-6780#backwards-compatibility) "Contracts that depended on re-deploying contracts at the same address using CREATE2 (after a SELFDESTRUCT) will no longer function properly if the created contract does not call SELFDESTRUCT within the same transaction."

Adoption of this ACP modifies consensus rules for the C-Chain, therefore it requires a network upgrade. It is recommended that Subnet-EVM chains also adopt this ACP and follow the same upgrade time as Avalanche's next network upgrade.

## Security Considerations

Refer to the original EIPs for security considerations:
- [EIP 1153](https://eips.ethereum.org/EIPS/eip-1153#security-considerations)
- [EIP 4788](https://eips.ethereum.org/EIPS/eip-4788#security-considerations)
- [EIP 4844](https://eips.ethereum.org/EIPS/eip-4844#security-considerations)
- [EIP 5656](https://eips.ethereum.org/EIPS/eip-5656#security-considerations)
- [EIP 6780](https://eips.ethereum.org/EIPS/eip-6780#security-considerations)
- [EIP 7516](https://eips.ethereum.org/EIPS/eip-7516#security-considerations)

## Open Questions

No open questions.

## Copyright

Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

# ACP-151: Use Current Block Pchain Height As Context (/docs/acps/151-use-current-block-pchain-height-as-context)

---
title: "ACP-151: Use Current Block Pchain Height As Context"
description: "Details for Avalanche Community Proposal 151: Use Current Block Pchain Height As Context"
edit_url: https://github.com/avalanche-foundation/ACPs/edit/main/ACPs/151-use-current-block-pchain-height-as-context/README.md
---

| ACP           | 151                                                                                        |
| :------------ | :----------------------------------------------------------------------------------------- |
| **Title**     | Use current block P-Chain height as context for state verification                         |
| **Author(s)** | Ian Suvak ([@iansuvak](https://github.com/iansuvak))                                       |
| **Status**    | Activated ([Discussion](https://github.com/avalanche-foundation/ACPs/discussions/152)) |
| **Track**     | Standards                                                                                  |

## Abstract

Proposes that the ProposerVM passes inner VMs the P-Chain block height of the current block being built rather than the P-Chain block height of the parent block. Inner VMs use this P-Chain height for verifying aggregated signatures of Avalanche Interchain Messages (ICM). This will allow for a more reliable way to determine which validators should participate in signing the message, and remove unnecessary waiting periods.

## Motivation

Currently the ProposerVM passes the P-Chain height of the parent block to inner VMs, which use the value to verify ICM messages in the current block. Using the parent block's P-Chain height is necessary for verifying the proposer and reaching consensus on the current block, but it is not necessary for verifying ICM messages within the block.

Using the P-Chain height of the current block being built would make operations using ICM messages to modify the validator set, such as ones specified in [ACP-77](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/77-reinventing-subnets/README.md) be verifiable sooner and more reliably. Currently at least two new P-Chain blocks need to be produced after the relevant state change for it to be reflected for purposes of ICM aggregate signature verification.

## Specification

The [block context](https://github.com/ava-labs/avalanchego/blob/d2e9d12ed2a1b6581b8fd414cbfb89a6cfa64551/snow/engine/snowman/block/block_context_vm.go#L14) contains a `PChainHeight` field that is passed from the ProposerVM to the inner VMs building the block. It is later used by the inner VMs to fetch the canonical validator set for verification of ICM aggregated signatures.

The `PChainHeight` currently passed in by the ProposerVM is the P-Chain height of the parent block. The proposed change is to instead have the ProposerVM pass in the P-Chain height of the current block.

## Backwards Compatibility

This change requires an upgrade to make sure that all validators verifying the validity of the ICM messages use the same P-Chain height and therefore the same validator set. Prior to activation nodes should continue to use P-Chain height of the parent block.

## Reference Implementation

An implementation of this ACP for avalanchego can be found [here](https://github.com/ava-labs/avalanchego/pull/3459)

## Security Considerations

ProposerVM needs to use the parent block's P-Chain height to verify proposers for security reasons but we don't have such restrictions for verifying ICM message validity in the current block being built. Therefore, this should be a safe change.

## Acknowledgments

Thanks to [@StephenButtolph](https://github.com/StephenButtolph) and [@michaelkaplan13](https://github.com/michaelkaplan13) for discussion and feedback on this ACP.

## Copyright

Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

# ACP-176: Dynamic Evm Gas Limit And Price Discovery Updates (/docs/acps/176-dynamic-evm-gas-limit-and-price-discovery-updates)

---
title: "ACP-176: Dynamic Evm Gas Limit And Price Discovery Updates"
description: "Details for Avalanche Community Proposal 176: Dynamic Evm Gas Limit And Price Discovery Updates"
edit_url: https://github.com/avalanche-foundation/ACPs/edit/main/ACPs/176-dynamic-evm-gas-limit-and-price-discovery-updates/README.md
---

| ACP | 176 |
| :- | :- |
| **Title** | Dynamic EVM Gas Limits and Price Discovery Updates |
| **Author(s)** | Stephen Buttolph ([@StephenButtolph](https://github.com/StephenButtolph)), Michael Kaplan ([@michaelkaplan13](https://github.com/michaelkaplan13)) |
| **Status** | Activated ([Discussion](https://github.com/avalanche-foundation/ACPs/discussions/178)) |
| **Track** | Standards |

## Abstract

Proposes that the C-Chain and Subnet-EVM chains adopt a dynamic fee mechanism similar to the one [introduced on the P-Chain as part of ACP-103](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/103-dynamic-fees/README.md), with modifications to allow for block proposers (i.e. validators) to dynamically adjust the target gas consumption per unit time.

## Motivation

Currently, the C-Chain has a static gas target of [15,000,000 gas](https://github.com/ava-labs/coreth/blob/39ec874505b42a44e452b8809a2cc6d09098e84e/params/avalanche_params.go#L32) per [10 second rolling window](https://github.com/ava-labs/coreth/blob/39ec874505b42a44e452b8809a2cc6d09098e84e/params/avalanche_params.go#L36), and uses a modified version of the [EIP-1559](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1559.md) dynamic fee mechanism to adjust the base fee of blocks based on the gas consumed in the previous 10 second window. This has two notable drawbacks:

1. The windower mechanism used to determine the base fee of blocks can lead to outsized spikes in the gas price when there is a large block. This is because after a large block that uses all of its gas limit, blocks that follow in the same window continue to result in increased gas prices even if they are relatively small blocks that are under the target gas consumption.
2. The static gas target necessitates a required network upgrade in order to modify. This is cumbersome and makes it difficult for the network to adjust its capacity in response to performance optimizations or hardware requirement increases.

To better position Avalanche EVM chains, including the C-Chain, to be able to handle future increases in load, we propose replacing the above mechanism with one that better handles blocks that consume a large amount of gas, and that allows for validators to dynamically adjust the target rate of consumption.

## Specification

### Gas Price Determination

The mechanism to determine the base fee of a block is the same as the one used in [ACP-103](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/103-dynamic-fees/README.md) to determine the gas price of a block on the P-Chain. This mechanism calculates the gas price for a given block $b$ based on the following parameters:

<div align="center">

| | |
|---|---|
| $T$ | the target gas consumed per second |
| $M$ | minimum gas price |
| $K$ | gas price update constant |
| $C$ | maximum gas capacity |
| $R$ | gas capacity added per second |

</div>

### Making $T$ Dynamic

As noted above, the gas price determination mechanism relies on a target gas consumption per second, $T$, in order to calculate the gas price for a given block. $T$ will be adjusted dynamically according to the following specification.

Let $q$ be a non-negative integer that is initialized to 0 upon activation of this mechanism. Let the target gas consumption per second be expressed as:

$$T = P \cdot e^{\frac{q}{D}}$$

where $P$ is the global minimum allowed target gas consumption rate for the network, and $D$ is a constant that helps control the rate of change of the target gas consumption.

After the execution of transactions in block $b$, the value of $q$ can be increased or decreased up to $Q$. It must be the case that $\left|\Delta q\right| \leq Q$, or block $b$ is considered invalid. The amount by which $q$ changes after executing block $b$ is specified by the block builder.

Block builders (i.e. validators), may set their desired value for $T$ (i.e. their desired gas consumption rate) in their configuration, and their desired value for $q$ can then be calculated as:

$$q_{desired} = D \cdot ln\left(\frac{T_{desired}}{P}\right)$$

Note that since $q_{desired}$ is only used locally and can be different for each node, it is safe for implementations to approximate the value of $ln\left(\frac{T_{desired}}{P}\right)$, and round the resulting value to the nearest integer.

When building a block, builders can calculate their next preferred value for $q$ based on the network's current value (`q_current`) according to:

  ```python
  # Calculates a node's new desired value for q given for a given block
  def calc_next_q(q_current: int, q_desired: int, max_change: int) -> int:
    if q_desired > q_current:
        return q_current + min(q_desired - q_current, max_change)
    else:
        return q_current - min(q_current - q_desired, max_change)
  ```

As $q$ is updated after the execution of transactions within the block, $T$ is also updated such that $T = P \cdot e^{\frac{q}{D}}$ at all times. As the value of $T$ adjusts, the value of $R$ (capacity added per second) is also updated such that:

$$R = 2 \cdot T$$

This ensures that the gas price can increase and decrease at the same rate.

The value of $C$ must also adjust proportionately, so we set:

$$C = 10 \cdot T$$

This means that the maximum stored gas capacity would be reached after 5 seconds where no blocks have been accepted.

In order to keep roughly constant the time it takes for the gas price to double at sustained maximum network capacity usage, the value of $K$ used in the gas price determination mechanism must be updated proportionally to $T$ such that:

$$K = 87 \cdot T$$

In order to have the gas price not be directly impacted by the change in $K$, we also update $x$ (excess gas consumption) proportionally. When updating $x$ after executing a block, instead of setting $x = x + G$ as specified in ACP-103, we set:

$$x_{n+1} = (x + G) \cdot \frac{K_{n+1}}{K_{n}}$$

Note that the value of $q$ (and thus also $T$, $R$, $C$, $K$, and $x$) are updated **after** the execution of block $b$, which means they only take effect in determining the gas price of block $b+1$. The change to each of these values in block $b$ does not effect the gas price for transactions included in block $b$ itself.

Allowing block builders to adjust the target gas consumption rate in blocks that they produce makes it such that the effective target gas consumption rate should converge over time to the point where 50% of the voting stake weight wants it increased and 50% of the voting stake weight wants it decreased. This is because the number of blocks each validator produces is proportional to their stake weight.

As noted in ACP-103, the maximum gas consumed in a given period of time $\Delta{t}$, is $r + R \cdot \Delta{t}$, where $r$ is the remaining gas capacity at the end of previous block execution. The upper bound across all $\Delta{t}$ is $C + R \cdot \Delta{t}$. Phrased differently, the maximum amount of gas that can be consumed by any given block $b$ is:

$$gasLimit_{b} = min(r + R \cdot \Delta{t}, C)$$ 

### Configuration Parameters

As noted above, the gas price determination mechanism depends on the values of $T$, $M$, $K$, $C$, and $R$ to be set as parameters. $T$ is adjusted dynamically from its initial value based on $D$ and $P$, and the values of $R$ and $C$ are derived from $T$. 

Parameters at activation on the C-Chain are:

<div align="center">

| Parameter | Description | C-Chain Configuration|
| - | - | - |
| $P$ | minimum target gas consumption per second | $1,000,000$ |
| $D$ | target gas consumption rate update constant | $2^{25}$ |
| $Q$ | target gas consumption rate update factor change limit | $2^{15}$ |
| $M$ | minimum gas price | $1*10^{-18}$ AVAX  |
| $K$ | initial gas price update factor | $87,000,000$ |

</div>

$P$ was chosen as a safe bound on the minimum target gas usage on the C-Chain. The current gas target of the C-Chain is $1,500,000$ per second. The target gas consumption rate will only stay at $P$ if the majority of stake weight of the network specifies $P$ as their desired gas consumption rate target. 

$D$ and $Q$ were chosen to give each block builder the ability to adjust the value of $T$ by roughly $\frac{1}{1024}$ of its current value, which matches the [gas limit bound divisor that Ethereum currently uses](https://github.com/ethereum/go-ethereum/blob/52766bedb9316cd6cddacbb282809e3bdfba143e/params/protocol_params.go#L26) to limit the amount that validators can change the execution layer gas limit in a single block. $D$ and $Q$ were scaled up by a factor of $2^{15}$ to provide block builders more granularity in the adjustments to $T$ that they can make.

$M$ was chosen as the minimum possible denomination of the native EVM asset, such that the gas price will be more likely to consistently be in a range of price discovery. The price discovery mechanism has already been battle tested on the P-Chain (and prior to that on Ethereum for blob gas prices as defined by EIP-4844), giving confidence that it will correctly react to any increase in network usage in order to prevent a DOS attack.

$K$ was chosen such that at sustained maximum capacity ($T*2$ gas/second), the fee rate will double every ~60.3 seconds. For comparison, EIP-1559 can double about ~70 seconds, and the C-Chain's current implementation can double about every ~50 seconds, depending on the time between blocks.

The maximum instantaneous price multiplier is:

$$e^\frac{C}{K} = e^\frac{10 \cdot T}{87 \cdot T} = e^\frac{10}{87} \simeq 1.12$$

### Choosing $T_{desired}$

As mentioned above, this new mechanism allows for validators to specify their desired target gas consumption rate ($T_{desired}$) in their configuration, and the value that they set impacts the effective target gas consumption rate of the network over time. The higher the value of $T$, the more resources (storage, compute, etc) that are able to be used by the network. When choosing what value makes sense for them, validators should consider the resources that are required to properly support that level of gas consumption, the utility the network provides by having higher transaction per second throughput, and the stability of network should it reach that level of utilization.

While Avalanche Network Clients can set default configuration values for the desired target gas consumption rate, each validator can choose to set this value independently based on their own considerations.

## Backwards Compatibility

The changes proposed in this ACP require a required network upgrade in order to take effect. Prior to its activation, the current gas limit and price discovery mechanisms will continue to be used. Its activation should have relatively minor compatibility effects on any developer tooling. Notably, transaction formats, and thus wallets, are not impacted. After its activation, given that the value of $C$ is dynamically adjusted, the maximum possible gas consumed by an individual block, and thus maximum possible consumed by an individual transaction, will also dynamically adjust. The upper bound on the amount of gas consumed by a single transaction fluctuating means that transactions that are considered invalid at one time may be considered valid at a different point in time, and vice versa. While potentially unintuitive, as long as the minimum gas consumption rate is set sufficiently high this should not have significant practical impact, and is also currently the case on the Ethereum mainnet.

> [!NOTE]
> After the activation of this ACP, concerns were raised around the latency of inclusion for large transactions when the fee is increasing. To address these concerns, block producers SHOULD only produce blocks when there is sufficient capacity to include large transactions. Prior to this ACP, the maximum size of a transaction was $15$ million gas. Therefore, the recommended heuristic is to only produce blocks when there is at least $\min(8 \cdot T, 15 \text{ million})$ capacity. _At the time of writing, this ensures transactions with up to 12.8 million gas will be able to bid for block space._

## Reference Implementation

This ACP was implemented and merged into Coreth behind the `Fortuna` upgrade flag. The full implementation can be found in [coreth@v0.14.1-acp-176.1](https://github.com/ava-labs/coreth/releases/tag/v0.14.1-acp-176.1).

## Security Considerations

This ACP changes the mechanism for determining the gas price on Avalanche EVM chains. The gas price is meant to adapt dynamically to respond to changes in demand for using the chain. If it does not react as expected, the chain could be at risk for a DOS attack (if the usage price is too low), or over charge users during period of low activity. This price discovery mechanism has already been employed on the P-Chain, but should again be thoroughly tested for use on the C-Chain prior to activation on the Avalanche Mainnet.

Further, this ACP also introduces a mechanism for validators to change the gas limit of the C-Chain. If this limit is set too high, it is possible that validator nodes will not be able to keep up in the processing of blocks. An upper bound on the maximum possible gas limit could be considered to try to mitigate this risk, though it would then take further required network upgrades to scale the network past that limit. 

## Acknowledgments

Thanks to the following non-exhaustive list of individuals for input, discussion, and feedback on this ACP.
- [Emin Gün Sirer](https://x.com/el33th4xor)
- [Luigi D'Onorio DeMeo](https://x.com/luigidemeo)
- [Darioush Jalali](https://github.com/darioush)
- [Aaron Buchwald](https://github.com/aaronbuchwald)
- [Geoff Stuart](https://github.com/geoff-vball)
- [Meag FitzGerald](https://github.com/meaghanfitzgerald)
- [Austin Larson](https://github.com/alarso16)

## Copyright

Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

# ACP-181: P Chain Epoched Views (/docs/acps/181-p-chain-epoched-views)

---
title: "ACP-181: P Chain Epoched Views"
description: "Details for Avalanche Community Proposal 181: P Chain Epoched Views"
edit_url: https://github.com/avalanche-foundation/ACPs/edit/main/ACPs/181-p-chain-epoched-views/README.md
---

| ACP           | 181                                                                                        |
| :------------ | :----------------------------------------------------------------------------------------- |
| **Title**     | P-Chain Epoched Views                                                                      |
| **Author(s)** | Cam Schultz [@cam-schultz](https://github.com/cam-schultz)                                 |
| **Status**    | Implementable ([Discussion](https://github.com/avalanche-foundation/ACPs/discussions/211)) |
| **Track**     | Standards                                                                                  |

## Abstract

Proposes a standard P-Chain epoching scheme such that any VM that implements it uses a P-Chain block height known prior to the generation of its next block. This would enable VMs to optimize validator set retrievals, which currently must be done during block execution. This standard does *not* introduce epochs to the P-Chain's VM directly. Instead, it provides a standard that may be implemented by layers that inject P-Chain state into VMs, such as the ProposerVM.

## Motivation

The P-Chain maintains a registry of L1 and Subnet validators (including Primary Network validators). Validators are added, removed, or their weights changed by issuing P-Chain transactions that are included in P-Chain blocks. When describing an L1 or Subnet's validator set, what is really being described are the weights, BLS keys, and Node IDs of the active validators at a particular P-Chain height. Use cases that require on-demand views of L1 or Subnet validator sets need to fetch validator sets at arbitrary P-Chain heights, while use cases that require up-to-date views need to fetch them as often as every P-Chain block.

Epochs during which the P-Chain height is fixed would widen this window to a predictable epoch duration, allowing these use cases to implement optimizations such as pre-fetching validator sets once per epoch, or allowing more efficient backwards traversal of the P-Chain to fetch historical validator sets.

## Specification

### Assumptions

In the following specification, we assume that a block $b_m$ has timestamp $t_m$ and P-Chain height $p_m$.

### Epoch Definition

An epoch is defined as a contiguous range of blocks that share the same three values:
- An Epoch Number
- An Epoch P-Chain Height
- An Epoch Start Time

Let $E_N$ denote an epoch with epoch number $N$. $E_N$'s start time is denoted as $T_{start}^N$, and its P-Chain height as $P_N$. 

Let block $b_a$ be the block that activates this ACP. The first epoch ($E_0$) has $T_{start}^0 = t_{a-1}$, and $P_0 = p_{a-1}$. In other words, the first epoch start time is the timestamp of the last block prior to the activation of this ACP, and similarly, the first epoch P-Chain height is the P-Chain height of last block prior to the activation of this ACP.

### Epoch Sealing

An epoch $E_N$ is *sealed* by the first block with a timestamp greater than or equal to $T_{start}^N + D$, where $D$ is a constant defined in the network upgrade that activates this ACP. Let $B_{S_N}$ denote the block that sealed $E_N$.

The sealing block is defined to be a member of the epoch it seals. This guarantees that every epoch will contain at least one block. 

### Advancing an Epoch

We advance from the current epoch $E_N$ to the next epoch $E_{N+1}$ when the next block after $B_{S_N}$ is produced. This block will be a member of $E_{N+1}$, and will have the values:
- $P_{N+1}$ equal to the P-Chain height of $B_{S_N}$
- $T_{start}^{N+1}$ equal to $B_{S_N}$'s timestamp
- The epoch number, $N+1$ increments the previous epoch's epoch number by exactly $1$

## Properties

### Epoch Duration Bounds

Since an epoch's start time is set to the [timestamp of the sealing block of the previous epoch](#advancing-an-epoch), all epochs are guaranteed to have a duration of at least $D$, as measured from the epoch's starting time to the timestamp of the epoch's sealing block. However, since a sealing block is [defined](#epoch-sealing) to be a member of the epoch it seals, there is no upper bound on an epoch's duration, since that sealing block may be produced at any point in the future beyond $T_{start}^N + D$.

### Fixing the P-Chain Height

When building a block, Avalanche blockchains use the P-Chain height [embedded in the block](#assumptions) to determine the validator set. If instead the epoch P-Chain height is used, then we can ensure that when a block is built, the validator set to be used for the next block is known. To see this, suppose block $b_m$ seals epoch $E_N$. Then the next block, $b_{m+1}$ will begin a new epoch, $E_{N+1}$ with $P_{N+1}$ equal to $b_m$'s P-Chain height, $p_m$. If instead $b_m$ does not seal $E_N$, then $b_{m+1}$ will continue to use $P_{N}$. Both candidates for $b_{m+1}$'s P-Chain height ($p_m$ and $P_N$) are known at $b_m$ build time.

## Use Cases

### ICM Verification Optimization

For a validator to verify an ICM message, the signing L1/Subnet's validator set must be retrieved during block verification by traversing backward from the current P-Chain height to the P-Chain height provided by the ProposerVM. The traversal depth is highly variable, so to account for the worst case, VM implementations charge a large amount of gas to perform this verification.

With epochs, validator set retrieval occurs at fixed P-Chain heights that increment at regular intervals, which provides opportunities to optimize this retrieval. For instance, validator retrieval may be done asynchronously from block verification as soon as an epoch has been sealed. Further, validator sets at a given height can be more effectively cached or otherwise kept in memory, because the same height will be used verify all ICM messages for the remainder of an epoch. Each of these VM optimizations allow for the potential of ICM verification costs to be safely reduced by a significant amount within VM implementations.

### Improved Relayer Reliability

Current ICM VM implementations verify ICM messages against the local P-Chain state, as determined by the P-Chain height set by the ProposerVM. Off-chain relayers perform the following steps to deliver ICM messages:
1. Fetch the sending chain's validator set at the verifying chain's current proposed height
1. Collect BLS signatures from that validator set to construct the signed ICM message
1. Submit the transaction containing the signed message to the verifying chain

If the validator set changes between steps 1 and 3, the ICM message will fail verification.

Epochs improve upon this by fixing the P-Chain height used to verify ICM messages for a duration of time that is predictable to off-chain relayers. A relayer should be able to derive the epoch boundaries based on the specification above, or they could retrieve that information via a node API. Relayers could use that information to decide the validator set to query, knowing that it will be stable for the duration of the epoch. Further, VMs could relax the verification rules to allow ICM messages to be verified against the previous epoch as a fallback, eliminating edge cases around the epoch boundary.

## EVM ICM Verification Gas Cost Updates

Since the activation of [ACP-30](https://github.com/avalanche-foundation/ACPs/tree/60cbfc32e7ee2cffed33d8daee980d7a85dded48/ACPs/30-avalanche-warp-x-evm#gas-costs), the cost to verify ICM messages in the Avalanche EVM implementations (i.e. `coreth` and `subnet-evm`) using the `WarpPrecompile` have been based on the worst-case verification flow, including the relatively expensive lookup of the source chain's validator set at an aribtrary P-Chain height used by each new block. This ACP allows for optimizing this verification, as described above.

Prior to this ACP, the gas costs of relevant `WarpPrecompile` functions were:
```
const (
	GetVerifiedWarpMessageBaseCost  = 2
	GetBlockchainIDGasCost          = 2
	GasCostPerWarpSigner            = 500
	GasCostPerWarpMessageChunk      = 3_200
	GasCostPerSignatureVerification = 200_000
)
```

With optimizations implemented, based on the results of [new benchmarks](https://github.com/ava-labs/coreth/pull/1331) of the `WarpPrecompile` and roughly targeting processing 150 million gas per second, Avalanche EVM chains with this ACP activated use the following gas costs for the `WarpPrecompile`.
```
const (
	GetVerifiedWarpMessageBaseCost  = 750
	GetBlockchainIDGasCost          = 200
	GasCostPerWarpSigner            = 250
	GasCostPerWarpMessageChunk      = 512
	GasCostPerSignatureVerification = 125_000
)
```

While the performance of `GetVerifiedWarpMessageBaseCost`, `GetBlockchainIDGasCost`, and `GasCostPerWarpMessageChunk` are not directly impacted by this ACP, updated benchmark numbers show the new gas costs to be better aligned with relative time that the operations take to perform.

## Backwards Compatibility

This change requires a network upgrade and is therefore not backwards compatible.

Any downstream entities that depend on a VM's view of the P-Chain will also need to account for epoched P-Chain views. For instance, ICM messages are signed by an L1's validator set at a specific P-Chain height. Currently, the constructor of the signed message can in practice use the validator set at the P-Chain tip, since all deployed Avalanche VMs are at most behind the P-Chain by a fixed number of blocks. With epoching, however, the ICM message constructor must take into account the epoch P-Chain height of the verifying chain, which may be arbitrarily far behind the P-Chain tip.

## Reference Implementation

The following pseudocode illustrates how an epoch may be calculated for a block:

```go
// Epoch Duration
const D time.Duration

type Epoch struct {
    PChainHeight uint64
    Number uint64
    StartTime time.Time
}

type Block interface {
    Timestamp() time.Time
    PChainHeight() uint64
    Epoch() Epoch
}

func GetPChainEpoch(parent Block) Epoch {
	parentTimestamp := parent.Timestamp()
	parentEpoch := parent.Epoch()
	epochEndTime := parentEpoch.StartTime.Add(D)
	if parentTimestamp.Before(epochEndTime) {
		// If the parent was issued before the end of its epoch, then it did not
		// seal the epoch.
		return parentEpoch
	}

	// The parent sealed the epoch, so the child is the first block of the new
	// epoch.
	return Epoch{
		PChainHeight: parent.PChainHeight(),
		Number:       parentEpoch.Number + 1,
		StartTime:    parentTimestamp,
	}
}
```

- If the parent sealed its epoch, the current block [advances the epoch](#advancing-an-epoch), refreshing the epoch height, incrementing the epoch number, and setting the epoch starting time.
- Otherwise, the current block uses the current epoch height, number, and starting time, regardless of whether it seals the epoch.

A full reference implementation of this ACP for avalanchego can be found [here](https://github.com/ava-labs/avalanchego/pull/4238).

### Setting the Epoch Duration

The epoch duration $D$ is set on a network-wide level. For both Fuji (network ID 5) and Mainnet (network ID 1), $D$ will be set to 5 minutes upon activation of this ACP. Any changes to $D$ in the future would require another network upgrade.

#### Changing the Epoch Duration

Future network upgrades may change the value of $D$ to some new duration $D'$. $D'$ should not take effect until the end of the current epoch, rather than the activation time of the network upgrade that defines $D'$. This ensures an in progress epoch at the upgrade activation time cannot have a realized duration less than both $D$ and $D'$.

## Security Considerations

### Epoch P-Chain Height Skew

Because epochs may have [unbounded duration](#epoch-duration-bounds), it is possible for a block's `PChainEpochHeight` to be arbitrarily far behind the tip of the P-Chain. This does not affect the *validity* of ICM verification within a VM that implements P-Chain epoched views, since the validator set at `PChainEpochHeight` is always known. However, the following considerations should be made under this scenario:
1. As validators exit the validator set, their physical nodes may be unavailable to serve BLS signature requests, making it more difficult to construct a valid ICM message
1. A valid ICM message may represent an attestation by a stale validator set. Signatures from validators that have exited the validator set between `PChainEpochHeight` and the current P-Chain tip will not represent active stake.

Both of these scenarios may be mitigated by having shorter epoch lengths, which limit the delay in time between when the P-Chain is updated and when those updates are taken into account for ICM verification on a given L1, and by ensuring consistent block production, so that epochs always advance soon after $D$ time has passed.

### Excessive Validator Churn

If an epoched view of the P-Chain is used by the consensus engine, then validator set changes over an epoch's duration will be concentrated into a single block at the epoch's boundary. Excessive validator churn can cause consensus failures and other dangerous behavior, so it is imperative that the amount of validator weight change at the epoch boundary is limited. One strategy to accomplish this is to queue validator set changes and spread them out over multiple epochs. Another strategy is to batch updates to the same validator together such that increases and decreases to that validator's weight cancel each other out. Given the primary use case of ICM verification improvements, which occur at the VM level, mechanisms to mitigate against this are omitted from this ACP.

## Open Questions

- What should the epoch duration $D$ be set to?

- Is it safe for `PChainEpochHeight` and `PChainHeight` to differ significantly within a block, due to [unbounded epoch duration](#epoch-duration-bounds)?

## Acknowledgements

Thanks to [@iansuvak](https://github.com/iansuvak),  [@geoff-vball](https://github.com/geoff-vball), [@yacovm](https://github.com/yacovm), [@michaelkaplan13](https://github.com/michaelkaplan13), [@StephenButtolph](https://github.com/StephenButtolph), and [@aaronbuchwald](https://github.com/aaronbuchwald) for discussion and feedback on this ACP.

## Copyright

Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

# ACP-191: Seamless L1 Creation (/docs/acps/191-seamless-l1-creation)

---
title: "ACP-191: Seamless L1 Creation"
description: "Details for Avalanche Community Proposal 191: Seamless L1 Creation"
edit_url: https://github.com/avalanche-foundation/ACPs/edit/main/ACPs/191-seamless-l1-creation/README.md
---

| ACP | 191 |
| :- | :- |
| **Title** | Seamless L1 Creations (CreateL1Tx) |
| **Author(s)** | Martin Eckardt ([@martineckardt](https://github.com/martineckardt)), Aaron Buchwald ([@aaronbuchwald](https://github.com/aaronbuchwald)), Michael Kaplan ([@michaelkaplan13](https://github.com/michaelkaplan13)), Meaghan FitzGerald ([@meaghanfitzgerald](https://github.com/meaghanfitzgerald)) |
| **Status** | Proposed ([Discussion](https://github.com/avalanche-foundation/ACPs/discussions/197))|
| **Track** | Standards |

## Abstract

This ACP introduces a new P-Chain transaction type called `CreateL1Tx` that simplifies the creation of Avalanche L1s. It consolidates three existing transaction types (`CreateSubnetTx`, `CreateChainTx`, and `ConvertSubnetToL1Tx`) into a single atomic operation. This streamlines the L1 creation process, removes the need for the intermediary Subnet creation step, and eliminates the management of temporary `SubnetAuth` credentials.

## Motivation

[ACP-77](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/77-reinventing-subnets/README.md) introduced Avalanche L1s, providing greater sovereignty and flexibility compared to Subnets. However, creating an L1 currently requires a three-step process:

1. `CreateSubnetTx`: Create the Subnet record on the P-Chain and specify the `SubnetAuth`
2. `CreateChainTx`: Add a blockchain to the Subnet (can be called multiple times)  
3. `ConvertSubnetToL1Tx`: Convert the Subnet to an L1, specifying the initial validator set and the validator manager location

This process has several drawbacks:

* It requires orchestrating three separate transactions that could be handled in one.
* The `SubnetAuth` must be managed during creation but becomes irrelevant after conversion.
* The multi-step process increases complexity and potential for errors.
* It introduces unnecessary state transitions and storage overhead on the P-Chain.

By introducing a single `CreateL1Tx` transaction, we can simplify the process, reduce overhead, and improve the developer experience for creating L1s.

## Specification

### New Transaction Type

The following new transaction type is introduced:

```go
// ChainConfig represents the configuration for a chain to be created
type ChainConfig struct {
    // A human readable name for the chain; need not be unique
    ChainName string `serialize:"true" json:"chainName"`
    // ID of the VM running on the chain
    VMID ids.ID `serialize:"true" json:"vmID"`
    // IDs of the feature extensions running on the chain
    FxIDs []ids.ID `serialize:"true" json:"fxIDs"`
    // Byte representation of genesis state of the chain
    GenesisData []byte `serialize:"true" json:"genesisData"`
}

// CreateL1Tx is an unsigned transaction to create a new L1 with one or more chains
type CreateL1Tx struct {
    // Metadata, inputs and outputs
    BaseTx `serialize:"true"`
    
    // Chain configurations for the L1 (can be multiple)
    Chains []ChainConfig `serialize:"true" json:"chains"`
    
    // Chain where the L1 validator manager lives
    ManagerChainID ids.ID `serialize:"true" json:"managerChainID"`
    
    // Address of the L1 validator manager
    ManagerAddress types.JSONByteSlice `serialize:"true" json:"managerAddress"`
    
    // Initial pay-as-you-go validators for the L1
    Validators []*L1Validator `serialize:"true" json:"validators"`
}
```

The `L1Validator` structure follows the same definition as in [ACP-77](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/77-reinventing-subnets/README.md#convertsubnettol1tx).

### Transaction Processing

When a `CreateL1Tx` transaction is processed, the P-Chain performs the following operations atomically:

1. Create a new L1.
2. Create chain records for each chain configuration in the `Chains` array.  
3. Set up the L1 validator manager with the specified `ManagerChainID` and `ManagerAddress`.  
4. Register the initial validators specified in the `Validators` array.

### IDs

* `subnetID`: The `subnetID` of the L1 is the transaction hash.
* `blockchainID`: the `blockchainID` for each blockchain is is defined as the SHA256 hash of the 37 bytes resulting from concatenating the 32 byte `subnetID` with the `0x00` byte and the 4 byte `chainIndex` (index in the `Chains` array within the transaction)
* `validationID`: The `validationID` for the initial validators added through `CreateL1Tx` is defined as the SHA256 hash of the 36 bytes resulting from concatenating the 32 byte `subnetID` with the 4 byte `validatorIndex` (index in the `Validators` array within the transaction).

Note: Even with this updated definition of the `blockchainID`s for chains created using this new flow, the `validationID`s of the L1s initial set of validators is still compatible with the existing reference validator manager contracts as defined [here](https://github.com/ava-labs/icm-contracts/blob/4a897ba913958def3f09504338a1b9cd48fe5b2d/contracts/validator-manager/ValidatorManager.sol#L247).

### Restrictions and Validation

The `CreateL1Tx` transaction has the following restrictions and validation criteria:

1. The `Chains` array must contain at least one chain configuration  
2. The `ManagerChainID` must be a valid blockchain ID, but cannot be the P-Chain blockchain ID 
3. Validator nodes must have unique NodeIDs within the transaction  
4. Each validator must have a non-zero weight and a non-zero balance  
5. The transaction inputs must provide sufficient AVAX to cover the transaction fee and all validator balances

### Warp Message

After the transaction is accepted, the P-Chain must be willing to sign a `SubnetToL1ConversionMessage` with a `conversionID` corresponding to the new L1, similar to what would happen after a `ConvertSubnetToL1Tx`. This ensures compatibility with existing systems that expect this message, such as the validator manager contracts.

## Backwards Compatibility

This ACP introduces a new transaction type and does not modify the behavior of existing transaction types. Existing Subnets and L1s created through the three-step process will continue to function as before. This change is purely additive and does not require any changes to existing L1s or Subnets.

The existing transactions `CreateSubnetTx`, `CreateChainTx` and `ConvertSubnetToL1Tx` remain unchanged for now, but may be removed in a future ACP to ensure systems have sufficient time to update to the new process.

## Reference Implementation

A reference implementation must be provided in order for this ACP to be considered implementable.

## Security Considerations

The `CreateL1Tx` transaction follows the same security model as the existing three-step process. By making the L1 creation atomic, it reduces the risk of partial state transitions that could occur if one of the transactions in the three-step process fails.

The same continuous fee mechanism introduced in ACP-77 applies to L1s created through this new transaction type, ensuring proper metering of validator resources.

The transaction verification process must ensure that all validator properties are properly validated, including unique NodeIDs, valid BLS signatures, and sufficient balances.

## Rationale and Alternatives

The primary alternative is to maintain the status quo \- requiring three separate transactions to create an L1. However, this approach has clear disadvantages in terms of complexity, transaction overhead, and user experience.

Another alternative would be to modify the existing `ConvertSubnetToL1Tx` to allow specifying chain configurations directly. However, this would complicate the conversion process for existing Subnets and would not fully address the desire to eliminate the Subnet intermediary step for new L1 creation.

The chosen approach of introducing a new transaction type provides a clean solution that addresses all identified issues while maintaining backward compatibility.

## Acknowledgements

The idea for this PR was originally formulated by Aaron Buchwald in our discussion about the creation of L1s. Special thanks to the authors of ACP-77 for their groundbreaking work on Avalanche L1s, and to the projects that have shared their experiences and challenges with the current validator manager framework.

## Copyright

Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

# ACP-194: Streaming Asynchronous Execution (/docs/acps/194-streaming-asynchronous-execution)

---
title: "ACP-194: Streaming Asynchronous Execution"
description: "Details for Avalanche Community Proposal 194: Streaming Asynchronous Execution"
edit_url: https://github.com/avalanche-foundation/ACPs/edit/main/ACPs/194-streaming-asynchronous-execution/README.md
---

| ACP | 194 |
| :--- | :--- |
| **Title** | Streaming Asynchronous Execution |
| **Author(s)** | Arran Schlosberg ([@ARR4N](https://github.com/ARR4N)), Stephen Buttolph ([@StephenButtolph](https://github.com/StephenButtolph)) |
| **Status** | Proposed ([Discussion](https://github.com/avalanche-foundation/ACPs/discussions/196)) |
| **Track** | Standards |


## Abstract

Streaming Asynchronous Execution (SAE) decouples consensus and execution by introducing a queue upon which consensus is performed.
A concurrent execution stream is responsible for clearing the queue and reporting a delayed state root for recording by later rounds of consensus.
Validation of transactions to be pushed to the queue is lightweight but guarantees eventual execution.

## Motivation

### Performance improvements

1. Concurrent consensus and execution streams eliminate node context switching, reducing latency caused by each waiting on the other.
In particular, "VM time" (akin to CPU time) more closely aligns with wall time since it is no longer eroded by consensus.
This increases gas per wall-second even without an increase in gas per VM-second.
2. Lean, execution-only clients can rapidly execute the queue agreed upon by consensus, providing accelerated receipt issuance and state computation.
Without the need to compute state _roots_, such clients can eschew expensive Merkle data structures.
End users see expedited but identical transaction results.
3. Irregular stop-the-world events like database compaction are amortised over multiple blocks.
4. Introduces additional bursty throughput by eagerly accepting transactions, without a reduction in security guarantees.
5. Third-party accounting of non-data-dependent transactions, such as EOA-to-EOA transfers of value, can be performed prior to execution.

### Future features

Performing transaction execution after consensus sequencing allows the usage of consensus artifacts in execution. This unblocks some additional future improvements:

1. Exposing a real-time VRF during transaction execution.
2. Using an encrypted mempool to reduce front-running.

This ACP does not introduce these, but some form of asynchronous execution is required to correctly implement them.

### User stories

1. A sophisticated DeFi trader runs a highly optimised execution client, locally clearing the transaction queue well in advance of the network—setting the stage for HFT DeFi.
2. A custodial platform filters the queue for only those transactions sent to one of their EOAs, immediately crediting user balances.

## Description

In all execution models, a block is _proposed_ and then verified by validators before being _accepted_. To assess a block's validity in _synchronous_ execution, its transactions are first _executed_ and only then _accepted_ by consensus. This immediately and implicitly _settles_ all of the block's transactions by including their execution results at the time of _acceptance_.

<Mermaid chart={`flowchart LR
    I[Proposed] --> E[Executed] --> A[Accepted/Settled]`} />

Under SAE, a block is considered valid if all of its transactions can be paid for when eventually _executed_, after which the block is _accepted_ by consensus. The act of _acceptance_ enqueues the block to be _executed_ asynchronously. In the future, some as-yet-unknown later block will reference the execution results and _settle_ all transactions from the _executed_ block.

<Mermaid chart={`flowchart LR
    I[Proposed] --> A[Accepted]
    A -->|variable delay| E[Executed]
    E -->|τ seconds| S[Settled]
    A -. guarantees .-> S`} />

### Block lifecycle

#### Proposing blocks

The validator selection mechanism for block production is unchanged. However, block builders are no longer expected to execute transactions during block building.

The block builder is expected to include transactions by building upon the most recently settled state and to apply worst-case bounds on the execution of the ancestor blocks prior to the most recently settled block.

The worst-case bounds enforce minimum balances of sender accounts and the maximum required base fee. The worst-case bounds are described [below](#block-validity-and-building).

Prior to adding a proposed block to consensus, all validators MUST verify that the block builder correctly enforced the worst-case bounds while building the block. This guarantees that the block can be executed successfully if it is accepted.

> [!NOTE]
> The worst-case bounds guarantee does not provide assurance about whether or not a transaction will revert nor whether its computation will run out of gas by reaching the specified limit. The verification only ensures the transaction is capable of paying for the accrued fees.

#### Accepting blocks

Once a block is marked as accepted by consensus, the block is put in a FIFO execution queue.

#### Executing blocks

Each client runs a block executor in parallel, which constantly executes the blocks from the FIFO queue.

In addition to executing the blocks, the executor provides deterministic timestamps for the beginning and end of each block's execution.

Time is measured two ways by the block executor:

1. The timestamp included in the block header.
2. The amount of gas charged during the execution of blocks.

> [!NOTE]
> Execution timestamps are more granular than block header timestamps to allow sub-second block execution times.

As soon as there is a block available in the execution queue, the block executor starts processing the block.

If the executor's current timestamp is prior to the current block's timestamp, the executor's timestamp is advanced to match the block's.
Advancing the timestamp in this scenario results in unused gas capacity, reducing the gas _excess_ from which the price is determined.

The block is then executed on top of the last executed (not settled) state.

After executing the block, the executor advances its timestamp based on the gas usage of the block, also increasing the gas _excess_ for the pricing algorithm.

The block's execution time is now timestamped and the block is available to be settled.

#### Settling blocks

Already-executed blocks are settled once a following block that includes the results of the executed block is accepted.
The results are included by setting the state root to that of the last executed block and the receipt root to that of a MPT of all receipts since last settlement, possibly from more than one block.
The following block's timestamp is used to determine which blocks to settle—blocks are settled if said timestamp is greater than or equal to the execution time of the executed block plus a constant delay.

The additional delay amortises any sporadic slowdowns the block executor may have encountered.

## Specification

### Background

ACP-103 introduced the following variables for calculating the gas price:

<div align="center">

| | |
|---|---|
| $T$ | the target gas consumed per second |
| $M$ | minimum gas price |
| $K$ | gas price update constant |
| $R$ | gas capacity added per second |

</div>

ACP-176 provided a mechanism to make $T$ dynamic and set:

$$
\begin{align}
R &= 2 \cdot T \\
K &= 87 \cdot T
\end{align}
$$

The _excess_ actual consumption $x \ge 0$ beyond the target $T$ is tracked via numerical integration and used to calculate the gas price as:

$$M \cdot \exp\left(\frac{x}{K}\right)$$

### Gas charged

We introduce $g_L$, $g_U$, and $g_C$ as the gas _limit_, _used_, and _charged_ per transaction, respectively. We define

$$
g_C := \max\left(g_U, \frac{g_L}{\lambda}\right)
$$

where $\lambda$ enforces a lower bound on the gas charged based on the gas limit.

> [!NOTE]
> $\dfrac{g_L}{\lambda}$ is rounded up by actually calculating $\dfrac{g_L + \lambda - 1}{\lambda}$

In all previous instances where execution referenced gas used, from now on, we will reference gas charged. For example, the gas excess $x$ will be modified by $g_C$ rather than $g_U$.

### Block size

The constant time delay between block execution and settlement is defined as $\tau$ seconds.

The maximum allowed size of a block is defined as:

$$
\omega_B ~:= R \cdot \tau \cdot \lambda
$$

Any block whose total sum of gas limits for transactions exceed $\omega_B$ MUST be considered invalid.

### Queue size

The maximum allowed size of the execution queue _prior_ to adding a new block is defined as:

$$
\omega_Q ~:= 2 \cdot \omega_B
$$

Any block that attempts to be enqueued while the current size of the queue is larger than $\omega_Q$ MUST be considered invalid.

> [!NOTE]
> By restricting the size of the queue _prior_ to enqueueing the new block, $\omega_B$ is guaranteed to be the only limitation on block size.

### Block executor

During the activation of SAE, the block executor's timestamp $t_e$ is initialised to the timestamp of the last accepted block.

Prior to executing a block with timestamp $t_b$, the executor's timestamp and excess is updated:

$$
\begin{align}
\Delta{t} &~:= \max\left(0, t_b - t_e\right) \\
t_e &~:= t_e + \Delta{t} \\
x &~:= \max\left(x - T \cdot \Delta{t}, 0\right) \\
\end{align}
$$

The block is then executed with the gas price calculated from the current value of $x$.

After executing a block that charged $g_C$ gas in total, the executor's timestamp and excess is updated:

$$
\begin{align}
\Delta{t} &~:= \frac{g_C}{R} \\
t_e &~:= t_e + \Delta{t} \\
x &~:= x + \Delta{t} \cdot (R - T) \\
\end{align}
$$

> [!NOTE]
> The update rule here assumes that $t_e$ is a timestamp that tracks the passage of time both by gas and by wall-clock time. $\frac{g_C}{R}$ MUST NOT be simply rounded. Rather, the gas accumulation MUST be left as a fraction.

$t_e$ is now this block's execution timestamp.

### Handling gas target changes

When a block is produced that modifies $T$, both the consensus thread and the execution thread will update to the modified $T$ after their own handling of the block.

For example, restrictions of the queue size MUST be calculated based on the parent block's $T$.

Similarly, the time spent executing a block MUST be calculated based on the parent block's $T$.

### Block settlement

For a _proposed_ block that includes timestamp $t_b$, all ancestors whose execution timestamp $t_e$ is $t_e \leq t_b - \tau$ are considered settled.
Note that $t_e$ is not an integer as it tracks fractional seconds with gas consumption, which is not the case for $t_b$.

The _proposed_ block MUST include the `stateRoot` produced by the execution of the most recently settled block.

For any _newly_ settled blocks, the _proposed_ block MUST include all execution artifacts:
- `receiptsRoot`
- `logsBloom`
- `gasUsed`

The receipts root MUST be computed as defined in [EIP-2718](https://eips.ethereum.org/EIPS/eip-2718) except that the tree MUST be built from the concatenation of receipts from all blocks being settled.

> [!NOTE]
> If the block executor has fallen behind, the node may not be able to determine precisely which ancestors should be considered settled. If this occurs, validators MUST allow the block executor to catch up prior to deciding the block's validity.

### Block validity and building

After determining which blocks to settle, all remaining ancestors of the new block must be inspected to determine the worst-case bounds on $x$ and account balances. Account nonces are able to be known immediately.

The worst-case bound on $x$ can be calculated by following the block executor update rules using $g_L$ rather than $g_C$.

The worst-case bound on account balances can be calculated by charging the worst-case gas cost to the sender of a transaction along with deducting the value of the transaction from the sender's account balance.

The `baseFeePerGas` field MUST be populated with the gas price based on the worst-case bound on $x$ at the start of block execution.

### Configuration Parameters

As noted above, SAE depends on the values of $\tau$ and $\lambda$ to be set as parameters and the values of $\omega_B$ and $\omega_Q$ are derived from $T$.

Parameters to specify for the C-Chain are:

<div align="center">

| Parameter | Description | C-Chain Configuration|
| - | - | - |
| $\tau$ | duration between execution and settlement | $5s$ |
| $\lambda$ | minimum conversion from gas limit to gas charged | $2$ |

</div>

## Backwards Compatibility

This ACP modifies the meaning of multiple fields in the block. A comprehensive list of changes will be produced once a reference implementation is available.

Likely fields to change include:
- `stateRoot`
- `receiptsRoot`
- `logsBloom`
- `gasUsed`
- `extraData`

## Reference Implementation

A reference implementation is still a work-in-progress. This ACP will be updated to include a reference implementation once one is available.

## Security Considerations

### Worst-case transaction validity

To avoid a DoS vulnerability on execution, we require an upper bound on transaction gas cost (i.e. amount $\times$ price) beyond the regular requirements for transaction validity (e.g. nonce, signature, etc.). We therefore introduced "worst-case cost" validity.

We can prove that if every transaction were to use its full gas limit this would result in the greatest possible:

1. Consumption of gas units (by definition of the gas limit); and
2. Gas excess $x$ (and therefore gas price) at the time of execution.

For a queue of blocks $Q = \\{i\\}_ {i \ge 0}$ the gas excess $x_j$ immediately prior to execution of block $j \in Q$ is a monotonic, non-decreasing function of the gas usage of all preceding blocks in the queue; i.e. $x_j~:=~f(\\{g_i\\}_{i<j})$.

To see this, consider block $0 \le k<j$ consuming gas $g_k$.
A decrease in $g_k$ reduces the immediate increase of $x$.
Furthermore, this lowered consumption might further reduce $x$ at the start of executing the next block if $t_e^k < t_b^{k+1}$ and therefore $\Delta t > 0$.
Hence any decrease of $x$ is $\ge$ predicted.
The excess, and hence gas price, for every later block $x_{i>k}$ is therefore reduced:

$$
\downarrow g_k \implies
\begin{cases}
    \downarrow \Delta^+x \propto g_k \\
    \uparrow \Delta^-x \propto R-g_k
\end{cases}
\implies \downarrow \Delta x_k
\implies \downarrow M \cdot \exp\left(\frac{x_{i>k}}{K}\right)
$$

Given maximal gas consumption under (1), the monotonicity of $f$ implies (2).

Since we are working with non-negative integers, it follows that multiplying a transaction's gas limit by the hypothetical gas price of (2) results in its worst-case gas cost.
Any sender able to pay for this upper bound (in addition to value transfers) is guaranteed to be able to pay for the actual execution cost.
Transaction _acceptance_ under worst-case cost validity is therefore a guarantee of _settlement_.

### Queue DoS protection

Worst-case cost validity only protects against DoS at the point of execution but leaves the queue vulnerable to high-limit, low-usage transactions.

For example, a malicious user could send a transfer-only transaction (21k gas) with a limit set to consume the block's full gas limit.

Although they would have to have sufficient funds to theoretically pay for all the reserved gas, they would never actually be charged this amount. Pushing a sufficient number of such transactions to the queue would artificially inflate the worst-case cost of other users.

Therefore, the gas charged was modified from being equal to the gas usage to the above $g_C := \max\left(g_U, \frac{g_L}{\lambda}\right)$

The gas limit is typically set higher than the predicted gas consumption to allow for a buffer should the prediction be imprecise.
This precludes setting $\lambda := 1$.
Conversely, setting $\lambda := \infty$ would allow users to attack the queue with high-limit, low-consumption transactions.

Setting $\lambda ~:= 2$ allows for a 100% buffer on gas-usage estimates without penalising the sender, while still disincentivising falsely high limits.

#### Upper bound on queue DoS

Recall $R$ (gas capacity per second) for rate and $g_C$ (gas charged) as already defined.

The actual gas excess $x_A$ has an upper bound of the worst-case excess $x_W$, both of which can be used to calculate respective base fees $f_A$ and $f_W$ (the variable element of gas prices) from the existing exponential function:

$$
f := M \cdot \exp\left( \frac{x}{K} \right).
$$

Mallory is attempting to maximize the DoS ratio

$$
D := \frac{f_W}{f_A}
$$

by maximizing $\Sigma_{\forall i} (g_L - g_U)_i$ to maximize $x_W - x_A$.

> [!TIP]
> Although $D$ shadows a variable in ACP-176, that one is very different to anything here so there won't be confusion.

Recall that the increasing excess occurs such that

$$
x := x + g \cdot \frac{(R - T)}{R}
$$

Since the largest allowed size of the queue when enqueuing a new block is $\omega_Q$, we can derive an upper bound on the difference in the changes to worst-case and actual gas excess caused by the transactions in the queue before the new block is added:

$$
\begin{align}
\Delta x_A &\ge \frac{\omega_Q}{\lambda} \cdot \frac{(R - T)}{R} \\
\Delta x_W &= \omega_Q \cdot \frac{(R - T)}{R} \\
\Delta x_W - \Delta x_A &\le \omega_Q \cdot \frac{(R - T)}{R} - \frac{\omega_Q}{\lambda} \cdot \frac{(R - T)}{R} \\
&= \omega_Q \cdot \frac{(R - T)}{R} \cdot \left(1-\frac{1}{\lambda}\right) \\
&= \omega_Q \cdot \frac{(2 \cdot T - T)}{2 \cdot T} \cdot \left(1-\frac{1}{\lambda}\right) \\
&= \omega_Q \cdot \frac{T}{2 \cdot T} \cdot \left(1-\frac{1}{\lambda}\right) \\
&= \frac{\omega_Q}{2} \cdot \left(1-\frac{1}{\lambda}\right) \\
&= \frac{2 \cdot \omega_B}{2} \cdot \left(1-\frac{1}{\lambda}\right) \\
&= \omega_B \cdot \left(1-\frac{1}{\lambda}\right) \\
&= R \cdot \tau \cdot \lambda \cdot \left(1-\frac{1}{\lambda}\right) \\
&= R \cdot \tau \cdot (\lambda-1) \\
&= 2 \cdot T \cdot \tau \cdot (\lambda-1)
\end{align}
$$

Note that we can express Mallory's DoS quotient as:

$$
\begin{align}
D &= \frac{f_W}{f_A} \\
&= \frac{ M \cdot \exp \left( \frac{x_W}{K} \right)}{ M \cdot \exp \left( \frac{x_A}{K} \right)} \\
& = \exp \left( \frac{x_W - x_A}{K} \right).
\end{align}
$$

When the queue is empty (i.e. the execution stream has caught up with accepted transactions), the worst-case fee estimate $f_W$ is known to be the actual base fee $f_A$; i.e. $Q = \emptyset \implies D=1$. The previous bound on $\Delta x_W - \Delta x_A$ also bounds Mallory's ability such that:

$$
\begin{align}
D &\le \exp \left( \frac{2 \cdot T \cdot \tau \cdot (\lambda-1)}{K} \right)\\
&= \exp \left( \frac{2 \cdot T \cdot \tau \cdot (\lambda-1)}{87 \cdot T} \right)\\
&= \exp \left( \frac{2 \cdot \tau \cdot (\lambda-1)}{87} \right)\\
\end{align}
$$

Therefore, for the values suggested by this ACP:

$$
\begin{align}
D &\le \exp \left( \frac{2 \cdot 5 \cdot (2 - 1)}{87} \right)\\
&= \exp \left( \frac{10}{87} \right)\\
&\simeq 1.12\\
\end{align}
$$

In summary, Mallory can require users to increase their gas price by at most ~12%. In practice, the gas price often fluctuates more than 12% on a regular basis. Therefore, this does not appear to be a significant attack vector.

However, any deviation that dislodges the gas price bidding mechanism from a true bidding mechanism is of note.

## Appendix

### JSON RPC methods

Although asynchronous execution decouples the transactions and receipts recorded by a specific block, APIs MUST NOT alter their behavior to mirror this.
In particular, the API method `eth_getBlockReceipts` MUST return the receipts corresponding to the block's transactions, not the receipts settled in the block.

#### Named blocks

The Ethereum Mainnet APIs allow for retrieving blocks by named parameters that the API server resolves based on their consensus mechanism.
Other than the _earliest_ (genesis) named block, which MUST be interpreted in the same manner, all other named blocks are mapped to SAE in terms of the _execution_ status of blocks and MUST be interpreted as follows:

 * _pending_: the most recently _accepted_ block;
 * _latest_: the block that was most recently _executed_;
 * _safe_ and _finalized_: the block that was most recently _settled_.

> [!NOTE]
> The finality guarantees of Snowman consensus remove any distinction between _safe_ and _finalized_. 
> Furthermore, the _latest_ block is not at risk of re-org, only of a negligible risk of data corruption local to the API node.

### Observations around transaction prioritisation

As EOA-to-EOA transfers of value are entirely guaranteed upon _acceptance_, block builders MAY choose to prioritise other transactions for earlier execution.

A reliable marker of such transactions is a gas limit of 21,000 as this is an indication from the sender that they do not intend to execute bytecode.

However, this could delay the ability to issue transactions that depend on these EOA-to-EOA transfers.

Block builders are free to make their own decisions around which transactions to include.

## Acknowledgments

Thank you to the following non-exhaustive list of individuals for input, discussion, and feedback on this ACP.

* [Aaron Buchwald](https://github.com/aaronbuchwald)
* [Angharad Thomas](https://x.com/divergenceharri)
* [Martin Eckardt](https://github.com/martineckardt)
* [Meaghan FitzGerald](https://github.com/meaghanfitzgerald)
* [Michael Kaplan](https://github.com/michaelkaplan13)
* [Yacov Manevich](https://github.com/yacovm)

## Copyright

Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

# ACP-20: Ed25519 P2p (/docs/acps/20-ed25519-p2p)

---
title: "ACP-20: Ed25519 P2p"
description: "Details for Avalanche Community Proposal 20: Ed25519 P2p"
edit_url: https://github.com/avalanche-foundation/ACPs/edit/main/ACPs/20-ed25519-p2p/README.md
---

| ACP | 20 |
| :--- | :--- |
| **Title** | Ed25519 p2p |
| **Author(s)** | Dhruba Basu ([@dhrubabasu](https://github.com/dhrubabasu)) |
| **Status** | Proposed ([Discussion](https://github.com/avalanche-foundation/ACPs/discussions/21))|
| **Track** | Standards |

## Abstract

Support Ed25519 TLS certificates for p2p communications on the Avalanche network. Permit usage of Ed25519 public keys for Avalanche Network Client (ANC) NodeIDs. Support Ed25519 signatures in the ProposerVM.

## Motivation

Avalanche Network Clients (ANCs) rely on TLS handshakes to facilitate p2p communications. AvalancheGo (and by extension, the Avalanche Network) only supports TLS certificates that use RSA or ECDSA as the signing algorithm and explicitly prohibits any other signing algorithms.

If a TLS certificate is not present, AvalancheGo will generate and persist to disk a 4096 bit RSA private key on start-up. This key is subsequently used to generate the TLS certificate which is also persisted to disk. Finally, the TLS certificate is hashed to generate a 20 byte NodeID. Authenticated p2p messaging was required when the network started and it was sufficient to simply use a hash of the TLS certificate. With the introduction of Snowman++, validators were then required to produce shareable message signatures. The Snowman++ block headers (specified [here](https://github.com/ava-labs/avalanchego/blob/v1.10.15/vms/proposervm/README.md#snowman-block-extension)) were then required to include the full TLS `Certificate` along with the `Signature`.

However, TLS certificates support Ed25519 as their signing algorithm. Ed25519 are IETF recommendations ([RFC8032](https://datatracker.ietf.org/doc/html/rfc8032)) with some very nice properties, a large one being their size:

- 32 byte public key
- 64 byte private key
- 64 byte signature

Because of the small size of the public key, it can be used for the NodeID directly with a marginal hit to size (an additional 12 bytes). Additionally, the brittle reliance on static TLS certificates can be removed. Using the Ed25519 private key, a TLS certificate can be generated in-memory on node startup and used for p2p communications. This reduces the maintenance burden on node operators as they will only need to backup the Ed25519 private key instead of the TLS certificate and the RSA private key.

Ed25519 has wide adoption, including in the crypto industry. A non-exhaustive list of things that use Ed25519 can be found [here](https://ianix.com/pub/ed25519-deployment.html). More information about the Ed25519 protocol itself can be found [here](https://ed25519.cr.yp.to).

## Specification

### Required Changes

1. Support registration of 32-byte NodeIDs on the P-chain
2. Generate an Ed25519 key by default (`staker.key`) on node startup
3. Use the Ed25519 key to generate a TLS certificate on node startup
4. Add support for Ed25519 keys + signatures to the proposervm
5. Remove the TLS certificate embedding in proposervm blocks when an Ed25519 NodeID is the proposer
6. Add support for Ed25519 in `PeerList` messages

Changes to the p2p layer will be minimal as TLS handshakes are used to do p2p communication. Ed25519 will need to be added as a supported algorithm.

The P-chain will also need to be modified to support registration of 32-byte NodeIDs. During serialization, the length of the NodeID is not serialized and was assumed to always be 20 bytes. Implementers of this ACP must take care to continue parsing old transactions correctly.

This ACP could be implemented by adding a new tx type that requires Ed25519 NodeIDs only. If the implementer chooses to do this, a separate follow-up ACP must be submitted detailing the format of that transaction.

### Future Work

In the future, usage of non-Ed25519 TLS certificates should be prohibited to remove any dependency on them. This will further secure the Avalanche network by reducing complexity. The path to doing so is not outlined in this ACP.

## Backwards Compatibility

An implementation of this proposal should not introduce any backwards compatibility issues. NodeIDs that are 20 bytes should continue to be treated as hashes of TLS certificates. NodeIDs of 32 bytes (size of Ed25519 public key) should be supported following implementation of this proposal.

## Reference Implementation

TLS certificate generation using an Ed25519 private key is standard. The golang standard library has a reference [implementation](https://github.com/golang/go/blob/go1.20.10/src/crypto/tls/generate_cert.go).

Parsing TLS certificates and extracting the public key is also standard. AvalancheGo already contains [code](https://github.com/ava-labs/avalanchego/blob/638000c42e5361e656ffbc27024026f6d8f67810/staking/verify.go#L55-L65) to verify the public key from a TLS certificate.

## Security Considerations

### Validation Criteria

Although Ed25519 is standardized in [RFC8032](https://datatracker.ietf.org/doc/html/rfc8032), it does not define strict validation criteria. This has led to inconsistencies in the validation criteria across implementations of the signature scheme. This is unacceptable for any protocol that requires participants to reach consensus on signature validity. Henry de Valance highlights the complexity of this issue [here](https://hdevalence.ca/blog/2020-10-04-its-25519am). 

From [Chalkias et al. 2020](https://eprint.iacr.org/2020/1244.pdf):

* The RFC 8032 and the NIST FIPS186-5 draft both require to reject non-canonically encoded points, but not all of the implementations follow those guidelines.
* The RFC 8032 allows optionality between using a permissive verification equation and a more strict verification equation. Different implementations use different equations meaning validation results can vary even across implementations that follow RFC 8032.

Zcash adopted [ZIP-215](https://zips.z.cash/zip-0215) (proposed by Henry de Valance) to explicitly define the Ed25519 validation criteria. Implementers of this ACP _*must*_ use the ZIP-215 validation criteria.

The [`ed25519consensus`](https://github.com/hdevalence/ed25519consensus) golang library is a minimal fork of golang's `crypto/ed25519` package with support for ZIP-215 verification. It is maintained by [Filippo Valsorda](https://github.com/FiloSottile) who also maintains many golang stdlib cryptography packages. It is strongly recommended to use this library for golang implementations.

## Open Questions

_Can this Ed25519 key be used in alternative communication protocols?_

Yes. Ed25519 can be used for alternative communication protocols like [QUIC](https://datatracker.ietf.org/group/quic/about) or [NOISE](http://www.noiseprotocol.org/noise.html). This ACP removes the reliance on TLS certificates and associates a Ed25519 public key with NodeIDs. This allows for experimentation with different communication protocols that may be better suited for a high throughput blockchain like Avalanche.

_Can this Ed25519 key be used for Verifiable Random Functions?_

Yes. VRFs, as specified in [RFC9381](https://datatracker.ietf.org/doc/html/rfc9381), can be constructed using elliptic curves that are secure in the cryptographic random oracle model. Ed25519 test vectors are provided in the RFC for implementers of an Elliptic Curve VRF (ECVRF). This allows for Avalanche validators to generate a VRF per block using their associated Ed25519 keys, including for Subnets.

## Acknowledgements

Thanks to [@StephenButtolph](https://github.com/StephenButtolph) and [@patrick-ogrady](https://github.com/patrick-ogrady) for their feedback on these ideas.

## Copyright

Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

# ACP-204: Precompile Secp256r1 (/docs/acps/204-precompile-secp256r1)

---
title: "ACP-204: Precompile Secp256r1"
description: "Details for Avalanche Community Proposal 204: Precompile Secp256r1"
edit_url: https://github.com/avalanche-foundation/ACPs/edit/main/ACPs/204-precompile-secp256r1/README.md
---

# ACP-204: Precompile for secp256r1 Curve Support

| ACP | 204 |
| :--- | :--- |
| **Title** | Precompile for secp256r1 Curve Support |
| **Author(s)** | [Santiago Cammi](https://github.com/scammi), [Arran Schlosberg](https://github.com/ARR4N)  |
| **Status** | Implementable ([Discussion](https://github.com/avalanche-foundation/ACPs/discussions/212)) |
| **Track** | Standards |

## Abstract

This proposal introduces a precompiled contract that performs signature verifications for the secp256r1 elliptic curve on Avalanche's C-Chain. The precompile will be implemented at address `0x0000000000000000000000000000000000000100` and will enable native verification of P-256 signatures, significantly improving gas efficiency for biometric authentication systems, WebAuthn, and modern device-based signing mechanisms.

## Motivation

The secp256r1 (P-256) elliptic curve is the standard cryptographic curve used by modern device security systems, including Apple's Secure Enclave, Android Keystore, WebAuthn, and Passkeys. However, Avalanche currently only supports secp256k1 natively, forcing developers to use expensive Solidity-based verification that costs [200k-330k gas per signature verification](https://hackmd.io/@1ofB8klpQky-YoR5pmPXFQ/SJ0nuzD1T#Smart-Contract-Based-Verifiers).

This ACP proposes implementing EIP-7951's secp256r1 precompiled contract to unlock significant ecosystem benefits:

### Enterprise & Institutional Adoption

- Reduced onboarding friction: Enterprises can leverage existing biometric authentication infrastructure instead of managing seed phrases or hardware wallets
- Regulatory compliance: Institutions can utilize their approved device security standards and identity management systems
- Cost optimization: ~50x gas reduction (from 200k-330k to 6,900 gas) makes enterprise-scale applications economically viable

The 100x gas cost reduction makes these use cases economically viable while maintaining the security properties institutions and users expect from their existing devices. 

Adding the precompiled contract at the same address as used in [RIP-7212](https://github.com/ethereum/RIPs/blob/master/RIPS/rip-7212.md) provides consistency across ecosystems, and allows for any libraries that have been developed to interact with the precompile to be used unmodified across ecosystems.

## Specification

This ACP implements [EIP-7951](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-7951.md) for secp256r1 signature verification on Avalanche. The specification follows EIP-7951 exactly, with the precompiled contract deployed at address `0x0000000000000000000000000000000000000100`.

### Core Functionality

- Input: 160 bytes (message hash + signature components r,s + public key coordinates x,y)
- Output: success: 32 bytes `0x...01`; failure: no data returned
- Gas Cost: 6,900 gas (based on EIP-7951 benchmarking)
- Validation: Full compliance with NIST FIPS 186-3 specification

### Activation

This precompile may be activated as part of Avalanche's next network upgrade. Individual Avalanche L1s and subnets could adopt this enhancement independently through their respective client software updates.

For complete technical specifications, validation requirements, and implementation details, refer to [EIP-7951](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-7951.md).

## Backwards Compatibility

This ACP introduces a new precompiled contract and does not modify existing functionality. No backwards compatibility issues are expected since:

1. The precompile uses a previously unused address
2. No existing opcodes or consensus rules are modified
3. The change is additive and opt-in for applications

Adoption requires a coordinated network upgrade for the C-Chain. Other EVM L1s can adopt this enhancement independently by upgrading their client software.

## Security Considerations

### Cryptographic Security

- The secp256r1 curve is standardized by NIST and widely vetted
- Security properties are comparable to secp256k1 (used by ECRECOVER)
- Implementation follows NIST FIPS 186-3 specification exactly

### Implementation Security
 
- Signature verification (vs public-key recovery) approach maximizes compatibility with existing P-256 ecosystem
- No malleability check included to match NIST specification, but wrapper libraries may choose to add this
- Input validation prevents invalid curve points and out-of-range signature components

### Network Security

- Gas cost prevents potential DoS attacks through expensive computation
- No consensus-level security implications beyond standard precompile considerations

## Reference Implementation

The implementation builds upon existing work:

1. EIP-7951 Reference: The [Go-Ethereum implementation]https://github.com/ethereum/go-ethereum/pull/31991) of EIP-7951 provides the foundation
2. Coreth Implementation: Integration with Avalanche's C-Chain (Avalanche's fork of go-ethereum)
3. Cryptographic Library: Implementation utilizes Go's standard library `crypto/ecdsa` and `crypto/elliptic` packages, which implement NIST P-256 per FIPS 186-3 ([Go documentation](https://pkg.go.dev/crypto/elliptic#P256))


The implementation follows established patterns for precompile integration, adding the contract to the precompile registry and implementing the verification logic using established cryptographic libraries.

This ACP was implemented and merged into Coreth and Subnet-EVM behind the `Granite` upgrade flag. The full implementation can be found in [coreth@v0.15.4-rc.4](https://github.com/ava-labs/coreth/releases/tag/v0.15.4-rc.4), [subnet-evm@v0.8.0-fuji-rc.2](https://github.com/ava-labs/subnet-evm/releases/tag/v0.8.0-fuji-rc.2) and [libevm@v1.13.14-0.3.0.release](https://github.com/ava-labs/libevm/releases/tag/v1.13.14-0.3.0.release).

## Copyright

Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

# ACP-209: Eip7702 Style Account Abstraction (/docs/acps/209-eip7702-style-account-abstraction)

---
title: "ACP-209: Eip7702 Style Account Abstraction"
description: "Details for Avalanche Community Proposal 209: Eip7702 Style Account Abstraction"
edit_url: https://github.com/avalanche-foundation/ACPs/edit/main/ACPs/209-eip7702-style-account-abstraction/README.md
---

| ACP | 209 |
| :--- | :--- |
| **Title** | EIP-7702-style Set Code for EOAs |
| **Author(s)** | Stephen Buttolph ([@StephenButtolph](https://github.com/StephenButtolph)), Arran Schlosberg ([@ARR4N](https://github.com/ARR4N)), Aaron Buchwald ([@aaronbuchwald](https://github.com/aaronbuchwald)), Michael Kaplan ([@michaelkaplan13](https://github.com/michaelkaplan13)) |
| **Status** | Proposed ([Discussion](https://github.com/avalanche-foundation/ACPs/discussions/216)) |
| **Track** | Standards |

## Abstract

[EIP-7702](https://github.com/ethereum/EIPs/blob/e17d216b4e8b359703ddfbc84499d592d65281fb/EIPS/eip-7702.md) was activated on the Ethereum mainnet in May 2025 as part of the Pectra upgrade, and introduced a new "set code transaction" type that allows Externally Owned Accounts (EOAs) to set the code in their account. This enabled several UX improvements, including batching multiple operations into a single atomic transaction, sponsoring transactions on behalf of another account, and privilege de-escalation for EOAs.

This ACP proposes adding a similar transaction type and functionality to Avalanche EVM implementations in order to have them support the same style of UX available on Ethereum. Modifications to the handling of account nonce and balances are required in order for it to be safe when used in conjunction with the streaming asynchronous execution (SAE) mechanism proposed in [ACP-194](https://github.com/avalanche-foundation/ACPs/tree/4a9408346ee408d0ab81050f42b9ac5ccae328bb/ACPs/194-streaming-asynchronous-execution).

## Motivation

The motivation for this ACP is the same as the motivation described in [EIP-7702](https://github.com/ethereum/EIPs/blob/e17d216b4e8b359703ddfbc84499d592d65281fb/EIPS/eip-7702.md#motivation). However, EIP-7702 as implemented for Ethereum breaks invariants required for EVM chains that use the ACP-194 SAE mechanism.

There has been strong community feedback in support of ACP-194 for its potential to:
- Allow for increasing the target gas rate of Avalanche EVM chains, including the C-Chain
- Enable the use of an encrypted mempool to prevent front-running
- Enable the use of real time VRF during transaction execution

Given the strong support for ACP-194, bringing EIP-7702-style functionality to Avalanche EVMs requires modifications to preserve its necessary invariants, described below.

### Invariants needed for ACP-194

There are [two invariants explicitly broken by EIP-7702](https://github.com/ethereum/EIPs/blob/e17d216b4e8b359703ddfbc84499d592d65281fb/EIPS/eip-7702.md#backwards-compatibility) that are required for SAE. They are:

1. An account balance can only decrease as a result of a transaction originating from that account.
1. An EOA nonce may not increase after transaction execution has begun.

These invariants are required for SAE in order to be able to statically analyze (i.e. determine without executing the transaction) that a transaction:
- Has the proper nonce
- Will have sufficient balance to pay for its worst case transaction fee plus the balance it sends

As described in the ACP-194, this lightweight analysis of transactions in blocks allows blocks to be accepted by consensus with the guarantee that they can be executed successfully. Only after block acceptance are the transactions within the block then put into a queue to be executed asynchronously. If the execution of transactions in the queue can decrease an EOA's account balance or change an EOA's current nonce, then block verification is unable to ensure that transactions in the block will be valid when executed. If transactions accepted into blocks can be invalidated prior to their execution, this poses DOS vulnerabilities because the invalidated transactions use up space in the pending execution queue according to their gas limits, but they do not pay any fees.

Notably, EIP-7702's violation of these invariants already presents challenges for mempool verification on Ethereum. As [noted in the security considerations section](https://github.com/ethereum/EIPs/blob/e17d216b4e8b359703ddfbc84499d592d65281fb/EIPS/eip-7702.md#transaction-propagation), EIP-7702 makes it "possible to cause transactions from other accounts to become stale" and this "poses some challenges for transaction propagation" because nodes now cannot "statically determine the validity of transactions for that account". In synchronous execution environments such as Ethereum, these issues only pose potential DOS risks to the public transaction mempool. Under an asynchronous execution scheme, the issues pose DOS risks to the chain itself since the invalidated transactions can be included in blocks prior to their execution.

## Specification

The same [set code transaction as specified in EIP-7702](https://github.com/ethereum/EIPs/blob/e17d216b4e8b359703ddfbc84499d592d65281fb/EIPS/eip-7702.md?ref=blockhead.co#set-code-transaction) will be added to Avalanche EVM implementations. The behavior of the transaction is the same as specified in EIP-7702. However, in order to keep the guarantee of transaction validity upon inclusion in an accepted block, two modifications are made to the transaction verification and execution rules.
1. Delegated accounts must maintain a "reserved balance" to ensure they can always pay for the transaction fees and transferred balance of transactions sent from the account. The reserved balances are managed via a new `ReservedBalanceManager` precompile, as specified below.
1. The handling of account nonces during execution is separated from the verification of nonces during block verification, as specified below.

### Reserved balances

To ensure that all transactions can cover their worst case transaction fees and transferred balances upon inclusion in an accepted block, a "reserved balance" mechanism is introduced for accounts. Reserved balances are required for delegated accounts to guarantee that subsequent transactions they send after setting code for their account can still cover their fees and transfer amounts, even if transactions from other accounts reduce the account's balance prior to their execution.

To allow for managing reserved balances, a new `ReservedBalanceManager` stateful precompile will be added at address `0x0200000000000000000000000000000000000006`. The `ReservedBalanceManager` precompile will have the following interface:

```solidity
interface IReservedBalanceManager {
    /// @dev Emitted whenever an account's reserved balance is modified. 
    event ReservedBalanceUpdated(address indexed account, uint256 newBalance);

    /// @dev Called to deposit the native token balance provided into the account's
    /// reserved balance.
    function depositReservedBalance(address account) external payable;

    /// @dev Returns the current reserved balance for the given account.
    function getReservedBalance(address account) external view returns (uint256 balance);
}
```

The precompile will maintain a mapping of accounts to their current reserved balances. The precompile itself intentionally only allows for _increasing_ an account's reserved balance. Reducing an account's reserved balance is only ever done by the EVM when a transaction is sent from the account, as specified below.

During transaction verification, the following rules are applied:
- If the sender EOA account has not set code via an EIP-7702 transaction, no reserved balance is required.
    - The transaction is confirmed to be able to pay for its worst case transaction fee and transferred balance by looking at the sender account's regular balance and accounting for prior transactions it has sent that are still in the pending execution queue, as specified in ACP-194.
- Otherwise, if the sender EOA account has previously been delegated via an EIP-7702 transaction (even if that transaction is still in the pending execution queue), then the account's current "[settled](https://github.com/avalanche-foundation/ACPs/tree/4a9408346ee408d0ab81050f42b9ac5ccae328bb/ACPs/194-streaming-asynchronous-execution#settling-blocks)" reserved balance must be sufficient to cover the sum of the worst case transaction fees and balances sent for all of the transactions in the pending execution queue after the set code transaction.

During transaction execution, the following rules are applied:
- When initially deducting balance from the sender EOA account for the maximum transaction fee and balance sent with the transaction, the account's regular balance is used first. The account's reserved balance is only reduced if the regular balance is insufficient.
- In the execution of code as part of a transaction, only regular account balances are available. The only possible modification to reserved balances during code execution is increases via calls to the `ReservedBalanceManager` precompile `depositReservedBalance` function.
- If there is a gas refund at the end of the transaction execution, the balance is first credited to the sender account's reserved balance, up to a maximum of the account's reserved balance prior to the transaction. Any remaining refund is credited to the account's regular balance.

### Handling of nonces

To account for EOA account nonces being incremented during contract execution and potentially invalidating transactions from that EOA that have already been accepted, we separate the rules for how nonces are verified during block verification and how they are handled during execution.

During block verification, all transactions must be verified to have a correct nonce value based on the latest "settled" state root, as defined in ACP-194, and the number of transactions from the sender account in the pending execution queue. Specifically, the required nonce is derived from the settled state root and incremented by one for each of the sender’s transactions already accepted into the pending execution queue or current block.

During execution, the nonce used must be one greater than the latest nonce used by the account, accounting for both all transactions from the account and all contracts created by the account. This means that the actual nonce used by a transaction may differ from the nonce assigned in the raw transaction itself and used in verification.

Separating the nonce values used for block verification and execution ensures that transactions accepted in blocks cannot be invalidated by the execution of transactions before them in the pending execution queue. It still provides the same level of replay protection to transactions, as a transaction with a given nonce from an EOA can be accepted at most once. However, this separation has a subtle potential impact on contract creation. Previously, the resulting address of a contract could be deterministically derived from a contract creation transaction based on its sender address and the nonce set in the transaction. Now, since the nonce used in execution is separate from that set in the transaction, this is no longer guaranteed. 

## Backwards Compatibility

The introduction of EIP-7702 transactions will require a network upgrade to be scheduled.

Upon activation, a few invariants will be broken:
- (From EIP-7702) `tx.origin == msg.sender` can only be true in the topmost frame of execution.
    - Once an account has been delegated, it can invoke multiple calls per transaction.
- (From EIP-7702) An EOA nonce may not increase after transaction execution has begun.
    - Once an account has been delegated, the account may call a create operation during execution, causing the nonce to increase.
- The contract address of a contract deployed by an EOA (via transaction with an empty "to" address) can be derived from the sender address and the transaction's nonce.
    - If earlier transactions cause the nonce to increase before execution, the actual nonce used in a contract creation transaction may differ from the one in the transaction payload, altering the resulting contract address.
    - Note that this can only occur for accounts that have been delegated, and whose delegated code involves contract creation.

Additionally, at all points after the acceptance of a set code transaction, an EOA must have sufficient reserved balance to cover the sum of the worst case transactions fees and balances sent for all transactions in the pending execution queue after the set code transaction. Notably, this means that:
- If a delegated account has zero reserved balance at any point, it will be unable to send any further transactions until a different account provides it with reserved balance via the `ReservedBalanceManager` precompile. 
    - In order to initially "self-fund" its own reserved balance, an account must deposit reserved balance via the `ReservedBalanceManager` precompile prior to sending a set code transaction.
- In order to transfer its full (regular + reserved) account balance, a delegated account must first deposit all of its regular balance into reserved balance.

In order to support wallets as seamlessly as possible, the `eth_getBalance` RPC implementations should be updated to return the sum of an accounts regular and reserved balances. Additionally, clients should provide a new `eth_getReservedBalance` RPC method to allow for querying the reserved balance of a given account.

## Reference Implementation

A reference implementation is not yet available and must be provided for this ACP to be considered implementable.

## Security Considerations

All of the [security considerations from the EIP-7702 specification](https://github.com/ethereum/EIPs/blob/e17d216b4e8b359703ddfbc84499d592d65281fb/EIPS/eip-7702.md?ref=blockhead.co#security-considerations) apply here as well, except for the considerations regarding "sponsored transaction relayers" and "transaction propagation". Those two considerations do not apply here, as they are accounted for by the modifications made to introduce reserved balances and separate the handling of nonces in execution from verification.

Additionally, given that an account's reserved balance may need be updated in state when a transfer is sent from the account it must be confirmed that 21,000 gas is still a sufficiently high cost for the potential more expensive operation. Charging more gas for basic transfer transactions in this case could otherwise be an option, but would likely cause further backwards compatibility issues for smart contracts and off-chain services.

## Open Questions

1. Are the implementation and UX complexities regarding the `ReservedBalanceManager` precompile worth the UX improvements introduced by the new set code transaction type?
   - Except for having a contract spend an account's native token balance, most, if not all, of the UX improvements associated with the new transaction type could theoretically be implemented at the contract layer rather than the protocol layer. However, not all contracts provide support for account abstraction functionality via standards such as [ERC-2771](https://eips.ethereum.org/EIPS/eip-2771).
2. Are the implementation and UX complexities regarding the `ReservedBalanceManager` precompile worth giving delegate contracts the ability to spend native token balances?
   - An alternative may be to disallow delegate contracts from spending native token balances at all, and revert if they attempt to. They could use "wrapped native token" ERC20 implementations (i.e. WAVAX) to achieve the same effect. However, this may be equally or more complex at the implementation level, and would cause incompatibilies in delegate contract implementations for Ethereum.

## Copyright

Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

# ACP-224: Dynamic Gas Limit In Subnet Evm (/docs/acps/224-dynamic-gas-limit-in-subnet-evm)

---
title: "ACP-224: Dynamic Gas Limit In Subnet Evm"
description: "Details for Avalanche Community Proposal 224: Dynamic Gas Limit In Subnet Evm"
edit_url: https://github.com/avalanche-foundation/ACPs/edit/main/ACPs/224-dynamic-gas-limit-in-subnet-evm/README.md
---

| ACP | 224 |
| :--- | :--- |
| **Title** | Introduce ACP-176-Based Dynamic Gas Limits and Fee Manager Precompile in Subnet-EVM  |
| **Author(s)** | Ceyhun Onur ([@ceyonur](https://github.com/ceyonur)), Michael Kaplan ([@michaelkaplan13](https://github.com/michaelkaplan13)) |
| **Status** | Proposed ([Discussion](https://github.com/avalanche-foundation/ACPs/discussions/230)) |
| **Track** | Standards |

## Abstract

Proposes implementing [ACP-176](https://github.com/avalanche-foundation/ACPs/blob/aa3bea24431b2fdf1c79f35a3fd7cc57eeb33108/ACPs/176-dynamic-evm-gas-limit-and-price-discovery-updates/README.md) in Subnet-EVM, along with the addition of a new optional `ACP224FeeManagerPrecompile` that can be used to configure fee parameters on-chain dynamically after activation, in the same way that the existing `FeeManagerPrecompile` can be used today prior to ACP-176.

## Motivation

ACP-176 updated the EVM dynamic fee mechanism to more accurately achieve the target gas consumption on-chain. It also added a mechanism for the target gas consumption rate to be dynamically updated. Until now, ACP-176 was only added to Coreth (C-Chain), primarily because most L1s prefer to control their fees and gas targets through the `FeeManagerPrecompile` and `FeeConfig` in genesis chain configuration, and the existing `FeeManagerPrecompile` is not compatible with the ACP-176 fee mechanism.

[ACP-194](https://github.com/avalanche-foundation/ACPs/blob/aa3bea24431b2fdf1c79f35a3fd7cc57eeb33108/ACPs/194-streaming-asynchronous-execution/README.md) (SAE) depends on having a gas target and capacity mechanism aligned with ACP-176. Specifically, there must be a known gas capacity added per second, and maximum gas capacity. The existing windower fee mechanism employed by Subnet-EVM does not provide these properties because it does not have a fixed capacity rate, making it difficult to calculate worst-case bounds for gas prices. As such, adding ACP-176 into Subnet-EVM is a functional requirement for L1s to be able to use SAE in the future. Adding ACP-176 fee dynamics to Subnet-EVM also has the added benefit of aligning with Coreth such that only a single mechanism needs to be maintained on a go-forwards basis.

While both ACP-176 and ACP-194 will be required upgrades for L1s, this ACP aims to provide similar controls for chains with a new precompile. A new dynamic fee configuration and fee manager precompile that maps well into the ACP-176 mechanism will be added, optionally allowing admins to adjust fee parameters dynamically.

## Specification

### ACP-176 Parameters

This ACP uses the same parameters as in the [ACP-176 specification](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/176-dynamic-evm-gas-limit-and-price-discovery-updates/README.md#configuration-parameters), and allows their values to be configured on a chain-by-chain basis. The parameters and their current values used by the C-Chain are as follows:

| Parameter | Description | C-Chain Configuration |
| :--- | :--- | :--- |
| $T$ | target gas consumed per second | dynamic |
| $R$ | gas capacity added per second | 2*T |
| $C$ | maximum gas capacity | 10*T |
| $P$ | minimum target gas consumption per second | 1,000,000 |
| $D$ | target gas consumption rate update constant | 2^25 |
| $Q$ | target gas consumption rate update factor change limit | 2^15 |
| $M$ | minimum gas price | 1x10^-18 AVAX |
| $K$ | initial gas price update factor | 87*T |

### Prior Subnet-EVM Fee Configuration Parameters

Prior to this ACP, the Subnet-EVM fee configuration and fee manager precompile used the following parameters to control the fee mechanism:

**GasLimit**:
  Sets the max amount of gas consumed per block.

**TargetBlockRate**:
  Sets the target rate of block production in seconds used for fee adjustments. If the actual block rate is faster than this target, block gas cost will be increased, and vice versa.

**MinBaseFee**:
  The minimum base fee sets a lower bound on the EIP-1559 base fee of a block. Since the block's base fee sets the minimum gas price for any transaction included in that block, this effectively sets a minimum gas price for any transaction.

**TargetGas**:
  Specifies the targeted amount of gas (including block gas cost) to consume within a rolling 10s window. When the dynamic fee algorithm observes that network activity is above/below the `TargetGas`, it increases/decreases the base fee proportionally to how far above/below the target actual network activity is.

**BaseFeeChangeDenominator**:
  Divides the difference between actual and target utilization to determine how much to increase/decrease the base fee. A larger denominator indicates a slower changing, stickier base fee, while a lower denominator allows the base fee to adjust more quickly.

**MinBlockGasCost**:
  Sets the minimum amount of gas to charge for the production of a block.

**MaxBlockGasCost**:
  Sets the maximum amount of gas to charge for the production of a block.

**BlockGasCostStep**:
  Determines how much to increase/decrease the block gas cost depending on the amount of time elapsed since the previous block. If the block is produced at the target rate, the block gas cost will stay the same as the block gas cost for the parent block. If it is produced faster/slower, the block gas cost will be increased/decreased by the step value for each second faster/slower than the target block rate accordingly.
  Note: if the `BlockGasCostStep` is set to a very large number, it effectively requires block production to go no faster than the `TargetBlockRate`.
  Ex: if a block is produced two seconds faster than the target block rate, the block gas cost will increase by `2 * BlockGasCostStep`.

### ACP-176 Parameters in Subnet-EVM

ACP-176 will make `GasLimit` and `BaseFeeChangeDenominator` configurations obsolete in Subnet-EVM.

`TargetBlockRate`, `MinBlockGasCost`, `MaxBlockGasCost`, and `BlockGasCostStep` will be also removed by [ACP-226](https://github.com/avalanche-foundation/ACPs/tree/ce51dfab/ACPs/226-dynamic-minimum-block-times).

`MinGasPrice` is equivalent to `M` in ACP-176 and will be used to set the minimum gas price for ACP-176. This is similar to `MinBaseFee` in old Subnet-EVM fee configuration, and roughly gives the same effect. Currently the default value is `25 * 10^-18` (25 nAVAX/Gwei). This default will be changed to the minimum possible denomination of the native EVM asset (1 Wei), which is aligned with the C-Chain.

`TargetGas` is equivalent to `T` (target gas consumed per second) in ACP-176 and will be used to set the target gas consumed per second for ACP-176.

`MaxCapacityFactor` is equivalent to the factor in `C` in ACP-176 and controls the maximum gas capacity (i.e. block gas limit). This determines the `C` as `C = MaxCapacityFactor * T`. The default value will be 10, which is aligned with the C-Chain.

`TimeToDouble` will be used to control the speed of the fee adjustment (`K`). This determines the `K` as `K = (RMult * TimeToDouble) / ln(2)`, where `RMult` is the factor in `R` which is defined as 2. The default value for `TimeToDouble` will be 60 (seconds), making `K=~87*T`, which is aligned with the C-Chain.

As a result parameters will be set as follows:

| Parameter | Description | Default Value | Is Configurable |
| :--- | :--- | :--- | :--- |
| $T$ | target gas consumed per second | 1,000,000 | :white_check_mark: |
| $R$ | gas capacity added per second | 2*T | :x:
| $C$ | maximum gas capacity | 10*T | :white_check_mark: Through `MaxCapacityFactor` (default 10)
| $P$ | minimum target gas consumption per second | 1,000,000 | :x:
| $D$ | target gas consumption rate update constant | 2^25 | :x:
| $Q$ | target gas consumption rate update factor change limit | 2^15 | :x:
| $M$ | minimum gas price | 1 Wei | :white_check_mark:
| $K$ | gas price update constant | ~87*T | :white_check_mark: Through `TimeToDouble` (default 60s)

The gas capacity added per second (`R`) always being equal to `2*T` keeps it such that the gas price is capable of increases and decrease at the same rate. The values of `Q` and `D` affect the magnitude of change to `T` that each block can have, and the granularity at which the target gas consumption rate can be updated. The proposed values match the C-Chain, allowing each block to modify the current gas target by roughly $\frac{1}{1024}$ of its current value. This has provided sufficient responsiveness and granularity as is, removing the need to make `D` and `Q` dynamic or configurable. Similarly, 1,000,000 gas/second should be a low enough minimum target gas consumption for any EVM L1. The target gas for a given L1 will be able to be increased from this value dynamically and has no maximum.

### Genesis Configuration

There will be a new genesis chain configuration to set the parameters for the chain without requiring the ACP224FeeManager precompile to be activated. This will be similar to the existing fee configuration parameters in chain configuration. If there is no genesis configuration for the new fee parameters the default values for the C-Chain will be used. This will look like the following:

```json
{
  ...
  "acp224Timestamp": uint64
  "acp224FeeConfig": {
    "minGasPrice": uint64
    "maxCapacityFactor": uint64
    "timeToDouble": uint64
  }
}

```

### Dynamic Gas Target Via Validator Preference

For L1s that want their gas target to be dynamically adjusted based on the preferences of their validator sets, the same mechanism introduced on the C-Chain in ACP-176 will be employed. Validators will be able to set their `gas-target` preference in their node's configuration, and block builders can then adjust the target excess in blocks that they propose based on their preference.

### Dynamic Gas Target & Fee Configuration Via `ACP224FeeManagerPrecompile`

For L1s that want an "admin" account to be able to dynamically configuration their gas target and other fee parameters, a new optional `ACP224FeeManagerPrecompile` will be introduced and can be activated. The precompile will offer similar controls as the existing `FeeManagerPrecompile` implemented in Subnet-EVM [here](https://github.com/ava-labs/subnet-evm/tree/53f5305/precompile/contracts/feemanager). The solidity interface will be as follows:

```solidity
//SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;
import "./IAllowList.sol";

/// @title ACP-224 Fee Manager Interface
/// @notice Interface for managing dynamic gas limit and fee parameters
/// @dev Inherits from IAllowList for access control
interface IACP224FeeManager is IAllowList {
    /// @notice Configuration parameters for the dynamic fee mechanism
    struct FeeConfig {
        uint256 targetGas;           // Target gas consumption per second
        uint256 minGasPrice;         // Minimum gas price in wei
        uint256 maxCapacityFactor;   // Maximum capacity factor (C = factor * T)
        uint256 timeToDouble;        // Time in seconds for gas price to double at max capacity
    }

    /// @notice Emitted when fee configuration is updated
    /// @param sender Address that triggered the update
    /// @param oldFeeConfig Previous configuration
    /// @param newFeeConfig New configuration
    event FeeConfigUpdated(address indexed sender, FeeConfig oldFeeConfig, FeeConfig newFeeConfig);

    /// @notice Set the fee configuration
    /// @param config New fee configuration parameters
    function setFeeConfig(FeeConfig calldata config) external;

    /// @notice Get the current fee configuration
    /// @return config Current fee configuration
    function getFeeConfig() external view returns (FeeConfig memory config);

    /// @notice Get the block number when fee config was last changed
    /// @return blockNumber Block number of last configuration change
    function getFeeConfigLastChangedAt() external view returns (uint256 blockNumber);
}
```
For chains with the precompile activated, `setFeeConfig` can be used to dynamically change each of the values in the fee configurations. Importantly, any updates made via calls to `setFeeConfig` in a transaction will take effect only as of _settlement_ of the transaction, not as of _acceptance_ or _execution_ (for transaction life cycles/status, refer to ACP-194 [here](https://github.com/avalanche-foundation/ACPs/tree/61d2a2a/ACPs/194-streaming-asynchronous-execution#description)). This ensures that all nodes apply the same worst-case bounds validation on transactions being accepted into the queue, since the worst-case bounds are affected by changes to the fee configuration.

In addition to storing the latest fee configuration to be returned by `getFeeConfig`, the precompile will also maintain state storing the latest values of $q$ and $K$. These values can be derived from the `targetGas` and `timeToDouble` values given to the precompile, respectively. The value of $q$ can be deterministically calculated using the same method as Coreth currently employs to calculate a node's desired target excess [here](https://github.com/ava-labs/coreth/blob/b4c8300490afb7f234df704fdcc446f227e4ec2f/plugin/evm/upgrade/acp176/acp176.go#L170). Similarly, the value of $K$ could be computed directly according to:

$$ K = \frac{targetGas \cdot timeToDouble}{ln(2)} $$

However, floating point math may introduce inaccuracies. Instead, a similar approach will be employed using binary search to determine the closest integer solution for $K$.

Similar to the [desired target excess calculation in Coreth](https://github.com/ava-labs/coreth/blob/0255516f25964cf4a15668946f28b12935a50e0c/plugin/evm/upgrade/acp176/acp176.go#L170), which takes a node's desired gas target and calculates its desired target excess value, the `ACP224FeeManagerPrecompile` will use binary search to determine the resulting dynamic target excess value given the `targetGas` value passed to `setFeeConfig`. All blocks accepted after the settlement of such a call must have the correct target excess value as derived from the binary search result.

Block building logic can follow the below diagram for determining the target excess of blocks.
<Mermaid chart={`flowchart TD
    A[ACP-224 activated] --> B{Is ACP224FeeManager precompile active?}

    B -- Yes --> C[Use targetExcess from precompile storage at latest settled root]

    B -- No --> D{Is gas-target set in node chain config file?}
    D -- Yes --> E[Calculate targetExcess from configured preference and allowed update bounds]

    D -- No --> F{Does parent block have ACP176 fields?}
    F -- Yes --> G[Use parent block ACP176 gas target]
    F -- No --> H[Use MinTargetPerSecond]`} />

#### Adjustment to ACP-176 calculations for price discovery

ACP-176 defines the gas price for a block as:

$$gas\_price = M \cdot e^{\frac{x}{K}}$$

Now, whenever $M$ (`minGasPrice`) or $K$ (derived from `timeToDouble`) are changed via the `ACP224FeeManagerPrecompile`, $x$ must also be updated.

Specifically, when $M$ is updated from $M_0$ to $M_1$, $x$ must also be updated from $x_0$ (the current excess) to $x_1$. $x_1$ theoretically could be calculated directly as:

$$x_1 = ln(\frac{M_0}{M_1}) \cdot K + x_0$$

However, this would introduce floating point inaccuracies. Instead $x_1$ can be approximated using binary search to find the minimum non-negative integer such that the resulting gas price calculated using $M_1$ is greater than or equal to the current gas price prior to the change in $M$. In effect, this means that both reducing the minimum gas price and increasing the minimum gas price to a value less than the current gas price have no immediate effect on the current gas price. However, increasing the minimum gas price to value greater than the current gas price will cause the gas price to immediately step up to the new minimum value.

Similarly, when $K$ is updated from $K_0$ to $K_1$, $x$ must also be updated from $x_0$ (the current excess) to $x_1$, where $x_1$ is calculated as:

$$x_1 = x_0 \cdot \frac{K_1}{K_0}$$

This makes it such that the current gas price stays the same when $K$ is changed. Changes to $K$ only impact how quickly or slowly the gas price can change going forward based on usage.

## Backwards Compatibility

ACP-224 will require a network update in order to activate the new fee mechanism. Another activation will also be required to activate the new fee manager precompile. The activation of precompile should never occur before the activation of ACP-224 (the fee mechanism) since the precompile depends on ACP-224’s fee update logic to function correctly.

Activation of ACP-224 mechanism will deactivate the prior fee mechanism and the prior fee manager precompile. This ensures that there is no ambiguity or overlap between legacy and new pricing logic. In order to provide a configuration for existing networks, a network upgrade override for both activation time and ACP-176 configuration parameters will be introduced.

These upgrades will be optional at the moment. However, with introduction of ACP-194 (SAE), it will be required to activate this ACP; otherwise the network will not be able to use ACP-194.

## Reference Implementation

A reference implementation is not yet available and must be provided for this ACP to be considered implementable.

## Security Considerations

Generally, this has the same security considerations as ACP-176. However, due to the dynamic nature of parameters exposed in the `ACP224FeeManagerPrecompile` there is an additional risk of misconfiguration.  Misconfiguration of parameters could leave the network vulnerable to a DoS attack or result in higher transaction fees than necessary.

## Open Questions

* Should activation of the `ACP224FeeManager` precompile disable the old precompile itself or should we require it to be manually disabled as a separate upgrade?
* Should we use `targetGas` in genesis/chain config as an optional field signaling whether the chain config should have a precedence over the validator preferences?
* Similarly above, should we have a toggle in `ACP224FeeManager` precompile to give control to validators for `targetGas`?

## Acknowledgements

* [Stephen Buttolph](https://github.com/StephenButtolph)
* [Arran Schlosberg](https://github.com/ARR4N)
* [Austin Larson](https://github.com/alarso16)

## Copyright

Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

# ACP-226: Dynamic Minimum Block Times (/docs/acps/226-dynamic-minimum-block-times)

---
title: "ACP-226: Dynamic Minimum Block Times"
description: "Details for Avalanche Community Proposal 226: Dynamic Minimum Block Times"
edit_url: https://github.com/avalanche-foundation/ACPs/edit/main/ACPs/226-dynamic-minimum-block-times/README.md
---

| ACP | 226 |
| :- | :- |
| **Title** | Dynamic Minimum Block Times |
| **Author(s)** | Stephen Buttolph ([@StephenButtolph](https://github.com/StephenButtolph)), Michael Kaplan ([@michaelkaplan13](https://github.com/michaelkaplan13)) |
| **Status** | Implementable ([Discussion](https://github.com/avalanche-foundation/ACPs/discussions/228)) |
| **Track** | Standards |

## Abstract

Proposes replacing the current block production rate limiting mechanism on Avalanche EVM chains with a new mechanism where validators collectively and dynamically determine the minimum time between blocks.

## Motivation

Currently, Avalanche EVM chains employ a mechanism to limit the rate of block production by increasing the "block gas cost" that must be burned if blocks are produced more frequently than the target block rate specified for the chain. The block gas cost is paid by summing the "priority fee" amounts that all transactions included in the block collectively burn. This mechanism has a few notable suboptimal aspects:

1. There is no explicit minimum block delay time. Validators are capable of producing blocks as frequently as they would like by paying the additional fee, and too rapid block production could cause network stability issues.
1. The target block rate can only be changed in a required network upgrade, which makes updates difficult to coordinate and operationalize.
1. The target block rate can only be specified with 1-second granularity, which does not allow for configuring sub-second block times as performance improvements are made to make them feasible.

With the prospect of ACP-194 removing block execution from consensus and allowing for increases to the gas target through the dynamic ACP-176 mechanism, Avalanche EVM chains would be better suited by having a dynamic minimum block delay time denominated in milliseconds. This allows networks to ensure that blocks are never produced more frequently than the minimum block delay, and allows validators to dynamically influence the minimum block delay value by setting their preference.

## Specification

### Block Header Changes

Upon activation of this ACP, the `blockGasCost` field in block headers will be required to be set to 0. This means that no validation of the cumulative priority fee amounts of transactions within the block exceeding the block gas cost is required. Additionally, two new fields are added to EVM block headers: `timestampMilliseconds` and `minimumBlockDelayExcess`.

#### `timestampMilliseconds`

The canonical serialization and interpretation of EVM blocks already contains a block timestamp specified in seconds. Altering this would require deep changes to the EVM codebase, as well as cause breaking changes to tooling such as indexers and block explorers. Instead, a new field is added representing the unix timestamp in milliseconds. Header verification should verify the `block.timestamp` (in seconds) is aligned with the `block.timeMilliseconds`, more precisely: `block.timestampMilliseconds / 1000 == block.timestamp`.

Existing tools that do not need millisecond granularity do not need to parse the new field, which limits the amount of breaking changes.

The `timestampMilliseconds` field is represented in block headers as a `uint64`.

#### `minimumBlockDelayExcess`

The new `minimumBlockDelayExcess` field in the block header is used to derive the minimum number of milliseconds that must pass before the next block is allowed to be accepted. Specifically, if block $B$ has a `minimumBlockDelayExcess` of $q$, then the effective timestamp of block $B+1$ in milliseconds must be at least $M * e^{\frac{q}{D}}$ greater than the effective timestamp of block $B$ in milliseconds. $M$, $q$, and $D$ are defined below in the mechanism specification.

The `minimumBlockDelayExcess` field is represented in block headers as a `uint64`.

The value of `minimumBlockDelayExcess` can be updated in each block, similar to the gas target excess field introduced in ACP-176. The mechanism is specified below.

### Dynamic `minimumBlockDelay` mechanism

The `minimumBlockDelay` can be defined as:

$$ m = M * e^{\frac{q}{D}} $$

Where:
- $M$ is the global minimum `minimumBlockDelay` value in milliseconds
- $q$ is a non-negative integer that is initialized upon the activation of this mechanism, referred to as the `minimumBlockDelayExcess`
- $D$ is a constant that helps control the rate of change of `minimumBlockDelay`

After the execution of transactions in block $b$, the value of $q$ can be increased or decreased by up to $Q$. It must be the case that $\left|\Delta q\right| \leq Q$, or block $b$ is considered invalid. The amount by which $q$ changes after executing block $b$ is specified by the block builder.

Block builders (i.e., validators) may set their desired value for $M$ (i.e., their desired `minimumBlockDelay`) in their configuration, and their desired value for $q$ can then be calculated as:

$$q_{desired} = D \cdot ln\left(\frac{M_{desired}}{M}\right)$$

Note that since $q_{desired}$ is only used locally and can be different for each node, it is safe for implementations to approximate the value of $ln\left(\frac{M_{desired}}{M}\right)$ and round the resulting value to the nearest integer. Alternatively, client implementations can choose to use binary search to find the closest integer solution, as `coreth` [does to calculate a node's desired target excess](https://github.com/ava-labs/coreth/blob/ebaa8e028a3a8747d11e6822088b4af7863451d8/plugin/evm/upgrade/acp176/acp176.go#L170).

When building a block, builders can calculate their next preferred value for $q$ based on the network's current value (`q_current`) according to:

  ```python
  # Calculates a node's new desired value for q for a given block
  def calc_next_q(q_current: int, q_desired: int, max_change: int) -> int:
    if q_desired > q_current:
        return q_current + min(q_desired - q_current, max_change)
    else:
        return q_current - min(q_current - q_desired, max_change)
  ```

As $q$ is updated after the execution of transactions within the block, $m$ is also updated such that $m = M \cdot e^{\frac{q}{D}}$ at all times. As noted above, the change to $m$ only takes effect for subsequent block production, and cannot change the time at which block $b$ can be produced itself.

### Gas Accounting Updates

Currently, the amount of gas capacity available is only incremented on a per second basis, as defined by ACP-176. With this ACP, it is expected for chains to be able to have sub-second block times. However, in the case when a chain's gas capacity is fully consumed (i.e. during period of heavy transaction load), blocks would not be able to produced at sub-second intervals because at least one second would need to elapse for new gas capacity to be added. To correct this, upon activation of this ACP, gas capacity is added on a per millisecond basis.

The ACP-176 mechanism for determining the target gas consumption per second remains unchanged, but its result is now used to derive the target gas consumption per millisecond by dividing by 1000, and gas capacity is added at that rate as each block advances time by some number of milliseconds.

### Activation Parameters for the C-Chain

Parameters at activation on the C-Chain are:

<div align="center">

| Parameter | Description | C-Chain Configuration|
| - | - | - |
| $M$ | minimum `minimumBlockDelay` value | 1 millisecond |
| $q$ | initial `minimumBlockDelayExcess` | 7,970,124 |
| $D$ | `minimumBlockDelay` update constant | $2^{20}$ |
| $Q$ | `minimumBlockDelay` update factor change limit | 200 |

</div>

$M$ was chosen as a lower bound for `minimumBlockDelay` values to allow high-performance Avalanche L1s to be able to realize maximum performance and minimal transaction latency.

Based on the 1 millisecond value for $M$, $q$ was chosen such that the effective `minimumBlockDelay` value at time of activation is as close as possible to the current target block rate of the C-Chain, which is 2 seconds.

$D$ and $Q$ were chosen such that it takes approximately 3,600 consecutive blocks of the maximum allowed change in $q$ for the effective `minimumBlockDelay` value to either halve or double.

### ProposerVM `MinBlkDelay`

The ProposerVM currently offers a static, configurable `MinBlkDelay` seconds for consecutive blocks. With this ACP enforcing a dynamic minimum block delay time, any EVM instance adopting this ACP that also leverages the ProposerVM should ensure that the ProposerVM `MinBlkDelay` is set to 0.

### Note on Block Building

While there is no longer a requirement for blocks to burn a minimum block gas cost after the activation of this ACP, block builders should still take priority fees into account when building blocks to allow for transaction prioritization and to maximize the amount of native token (AVAX) burned in the block. 

From a user (transaction issuer) perspective, this means that a non-zero priority fee would only ever need to be set to ensure inclusion during periods of maximum gas utilization.

## Backwards Compatibility

While this proposal requires a network upgrade and updates the EVM block header format, it does so in a way that tries to maintain as much backwards compatibility as possible. Specifically, applications that currently parse and use the existing timestamp field that is denominated in seconds can continue to do so. The `timestampMilliseconds` header value only needs to be used in cases where more granular timestamps are required.

## Reference Implementation

This ACP was implemented and merged into Coreth and Subnet-EVM behind the `Granite` upgrade flag. The full implementation can be found in [coreth@v0.15.4-rc.4](https://github.com/ava-labs/coreth/releases/tag/v0.15.4-rc.4) and [subnet-evm@v0.8.0-fuji-rc.0](https://github.com/ava-labs/subnet-evm/releases/tag/v0.8.0-fuji-rc.0).

## Security Considerations

Too rapid block production may cause availability issues if validators of the given blockchain are not able to keep up with blocks being proposed to consensus. This new mechanism allows validators to help influence the maximum frequency at which blocks are allowed to be produced, but potential misconfiguration or overly aggressive settings may cause problems for some validators.

The mechanism for the minimum block delay time to adapt based on validator preference has already been used previously to allow for dynamic gas targets based on validator preference on the C-Chain, providing more confidence that it is suitable for controlling this network parameter as well. However, because each block is capable of changing the value of the minimum block delay by a certain amount, the lower the minimum block delay is, the more blocks that can be produced in a given time, and the faster the minimum block delay value will be able to change. This creates a dynamic where the mechanism for controlling `minimumBlockDelay` is more reactive at lower values, and less reactive at higher values. The global minimum `minimumBlockDelay` ($M$) provides a lower bound of how quickly blocks can ever be produced, but it is left to validators to ensure that the effective value does not exceed their collective preference.

## Acknowledgments

Thanks to [Luigi D'Onorio DeMeo](https://x.com/luigidemeo) for continually bringing up the idea of reducing block times to provide better UX for users of Avalanche blockchains.

## Copyright

Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

# ACP-23: P Chain Native Transfers (/docs/acps/23-p-chain-native-transfers)

---
title: "ACP-23: P Chain Native Transfers"
description: "Details for Avalanche Community Proposal 23: P Chain Native Transfers"
edit_url: https://github.com/avalanche-foundation/ACPs/edit/main/ACPs/23-p-chain-native-transfers/README.md
---

| ACP | 23 |
| :--- | :--- |
| **Title** | P-Chain Native Transfers |
| **Author(s)** | Dhruba Basu ([@dhrubabasu](https://github.com/dhrubabasu)) |
| **Status** | Activated |
| **Track** | Standards |

## Abstract

Support native transfers on P-chain. This enables users to transfer P-chain assets without leaving the P-chain or using a transaction type that's not meant for native transfers.

## Motivation

Currently, the P-chain has no simple transfer transaction type. The X-chain supports this functionality through a `BaseTx`. Although the P-chain contains transaction types that extend `BaseTx`, the `BaseTx` transaction type itself is not a valid transaction. This leads to abnormal implementations of P-chain native transfers like in the AvalancheGo wallet which abuses [`CreateSubnetTx`](https://github.com/ava-labs/avalanchego/blob/v1.10.15/wallet/chain/p/builder.go#L54-L63) to replicate the functionality contained in `BaseTx`.

With the growing number of subnets slated for launch on the Avalanche network, simple transfers will be demanded more by users. While there are work-arounds as mentioned before, the network should support it natively to provide a cheaper option for both validators and end-users.

## Specification

To support `BaseTx`, Avalanche Network Clients (like AvalancheGo) must register `BaseTx` with the type ID `0x22` in codec version `0x00`.

For the specification of the transaction itself, see [here](https://github.com/ava-labs/avalanchego/blob/v1.10.15/vms/platformvm/txs/base_tx.go#L29). Note that most other P-chain transactions extend this type, the only change in this ACP is to register it as a valid transaction itself.

## Backwards Compatibility

Adding a new transaction type is an execution change and requires a mandatory upgrade for activation. Implementors must take care to reject this transaction prior to activation. This ACP only details the specification of the added `BaseTx` transaction type.

## Reference Implementation

An implementation of `BaseTx` support was created [here](https://github.com/ava-labs/avalanchego/pull/2232) and subsequently merged into AvalancheGo. Since the "D" Upgrade is not activated, this transaction will be rejected by AvalancheGo.

If modifications are made to the specification of the transaction as part of the ACP process, the code must be updated prior to activation.

## Security Considerations

The P-chain has fixed fees which does not place any limits on chain throughput. A potentially popular transaction type like `BaseTx` may cause periods of high usage. The reference implementation in AvalancheGo sets the transaction fee to 0.001 AVAX as a deterrent (equivalent to `ImportTx` and `ExportTx`). This should be sufficient for the time being but a dynamic fee mechanism will need to be added to the P-chain in the future to mitigate this security concern. This is not addressed in this ACP as it requires a larger change to the fee dynamics on the P-chain as a whole.

## Open Questions

No open questions.

## Acknowledgements

Thanks to [@StephenButtolph](https://github.com/StephenButtolph) and [@abi87](https://github.com/abi87) for their feedback on the reference implementation.

## Copyright

Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

# ACP-24: Shanghai Eips (/docs/acps/24-shanghai-eips)

---
title: "ACP-24: Shanghai Eips"
description: "Details for Avalanche Community Proposal 24: Shanghai Eips"
edit_url: https://github.com/avalanche-foundation/ACPs/edit/main/ACPs/24-shanghai-eips/README.md
---

| ACP | 24 |
| :--- | :--- |
| **Title** | Activate Shanghai EIPs on C-Chain |
| **Author(s)** | Darioush Jalali ([@darioush](https://github.com/darioush)) |
| **Status** | Activated |
| **Track** | Standards |

## Abstract

This ACP proposes the adoption of the following EIPs on the Avalanche C-Chain network:
- [EIP-3651: Warm COINBASE](https://eips.ethereum.org/EIPS/eip-3651)
- [EIP-3855: PUSH0 instruction](https://eips.ethereum.org/EIPS/eip-3855)
- [EIP-3860: Limit and meter initcode](https://eips.ethereum.org/EIPS/eip-3860)
- [EIP-6049: Deprecate SELFDESTRUCT](https://eips.ethereum.org/EIPS/eip-6049)

## Motivation

The listed EIPs were activated on Ethereum mainnet as part of the [Shanghai upgrade](https://github.com/ethereum/execution-specs/blob/master/network-upgrades/mainnet-upgrades/shanghai.md#included-eips). This ACP proposes their activation on the Avalanche C-Chain in the next network upgrade. This maintains compatibility with upstream EVM tooling, infrastructure, and developer experience (e.g., Solidity compiler &gt;= [0.8.20](https://github.com/ethereum/solidity/releases/tag/v0.8.20)).

## Specification & Reference Implementation

This ACP proposes the EIPs be adopted as specified in the EIPs themselves. ANCs (Avalanche Network Clients) can adopt the implementation as specified in the [coreth](https://github.com/ava-labs/coreth) repository, which was adopted from the [go-ethereum v1.12.0](https://github.com/ethereum/go-ethereum/releases/tag/v1.12.0) release in this [PR](https://github.com/ava-labs/coreth/pull/277). In particular, note the following code:

- [Activation of new opcode and dynamic gas calculations](https://github.com/ava-labs/coreth/blob/bf2051729c7aa0c4ed8848ad3a78e241a791b968/core/vm/jump_table.go#L92)
- [EIP-3860 intrinsic gas calculations](https://github.com/ava-labs/coreth/blob/bf2051729c7aa0c4ed8848ad3a78e241a791b968/core/state_transition.go#L112-L113)
- [EIP-3651 warm coinbase](https://github.com/ava-labs/coreth/blob/bf2051729c7aa0c4ed8848ad3a78e241a791b968/core/state/statedb.go#L1197-L1199)
- Note EIP-6049 marks SELFDESTRUCT as deprecated, but does not remove it. The implementation in coreth is unchanged.

## Backwards Compatibility

The following backward compatibility considerations were highlighted by the original EIP authors:

- [EIP-3855](https://eips.ethereum.org/EIPS/eip-3855#backwards-compatibility): "... introduces a new opcode which did not exist previously. Already deployed contracts using this opcode could change their behaviour after this EIP".
- [EIP-3860](https://eips.ethereum.org/EIPS/eip-3860#backwards-compatibility) "Already deployed contracts should not be effected, but certain transactions (with initcode beyond the proposed limit) would still be includable in a block, but result in an exceptional abort."

Adoption of this ACP modifies consensus rules for the C-Chain, therefore it requires a network upgrade.

## Security Considerations

Refer to the original EIPs for security considerations:
- [EIP 3855](https://eips.ethereum.org/EIPS/eip-3855#security-considerations)
- [EIP 3860](https://eips.ethereum.org/EIPS/eip-3860#security-considerations)

## Open Questions

No open questions.

## Copyright

Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

# ACP-25: Vm Application Errors (/docs/acps/25-vm-application-errors)

---
title: "ACP-25: Vm Application Errors"
description: "Details for Avalanche Community Proposal 25: Vm Application Errors"
edit_url: https://github.com/avalanche-foundation/ACPs/edit/main/ACPs/25-vm-application-errors/README.md
---

| ACP | 25 |
| :--- | :--- |
| **Title** | Virtual Machine Application Errors |
| **Author(s)** | Joshua Kim ([@joshua-kim](https://github.com/joshua-kim)) |
| **Status** | Activated |
| **Track** | Standards |

## Abstract

Support a way for a Virtual Machine (VM) to signal application-defined error conditions to another VM.

## Motivation

VMs are able to build their own peer-to-peer application protocols using the `AppRequest`, `AppResponse`, and `AppGossip` primitives.

`AppRequest` is a message type that requires a corresponding `AppResponse` to indicate a successful response. In the unhappy path where an `AppRequest` is unable to be served, there currently is no native way for a peer to signal an error condition. VMs currently resort to timeouts in failure cases, where a client making a request will fallback to marking its request as failed after some timeout period has expired.

Having a native application error type would offer a more powerful abstraction where Avalanche nodes would be able to score peers based on perceived errors. This is not currently possible because Avalanche networking isn't aware of the specific implementation details of the messages being delivered to VMs. A native application error type would also guarantee that all clients can potentially expect an `AppError` message to unblock an unsuccessful `AppRequest` and only rely on a timeout when absolutely necessary, significantly decreasing the latency for a client to unblock its request in the unhappy path.

## Specification

### Message 

This modifies the p2p specification by introducing a new [protobuf](https://protobuf.dev/) message type:

```
message AppError {
  bytes chain_id = 1;
  uint32 request_id = 2;
  uint32 error_code = 3;
  string error_message = 4;
}
```

1. `chain_id`: Reserves field 1. Senders **must** use the same chain id of from the original `AppRequest` this `AppError` message is being sent in response to.
2. `request_id`: Reserves field 2. Senders **must** use the same request id from the original `AppRequest` this `AppError` message is being sent in response to.
3. `error_code`: Reserves field 3. Application defined error code. Implementations _should_ use the same error codes for the same conditions to allow clients to error match. Negative error codes are reserved for protocol defined errors. VMs may reserve any error code greater than zero.
4. `error_message`: Reserves field 4. Application defined human-readable error message that _should not_ be used for error matching. For error matching, use `error_code`.

### Reserved Errors
The following error codes are currently reserved by the Avalanche protocol:
| Error Code | Description     |
| ---------- | --------------- |
| 0          | undefined       |
| -1         | network timeout |

### Handling

Clients **must** respond to an inbound `AppRequest` message with either a corresponding `AppResponse` to indicate a successful response, or an `AppError` to indicate an error condition by the requested `deadline` in the original `AppRequest`.

## Backwards Compatibility

This new message type requires a network activation to require either an `AppResponse` or an `AppError` as a required response to an `AppRequest`.

## Reference Implementation

- Message definition: https://github.com/ava-labs/avalanchego/pull/2111
- Handling: https://github.com/ava-labs/avalanchego/pull/2248

## Security Considerations

Optional section that discusses the security implications/considerations relevant to the proposed change.

Clients should be aware that peers can arbitrarily send `AppError` messages to invoke error handling logic in a VM.

## Open Questions

Optional section that lists any concerns that should be resolved prior to implementation.

## Copyright

Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

# ACP-30: Avalanche Warp X Evm (/docs/acps/30-avalanche-warp-x-evm)

---
title: "ACP-30: Avalanche Warp X Evm"
description: "Details for Avalanche Community Proposal 30: Avalanche Warp X Evm"
edit_url: https://github.com/avalanche-foundation/ACPs/edit/main/ACPs/30-avalanche-warp-x-evm/README.md
---

| ACP | 30 |
| :--- | :--- |
| **Title** | Integrate Avalanche Warp Messaging into the EVM |
| **Author(s)** | Aaron Buchwald ([aaron.buchwald56@gmail.com](mailto:aaron.buchwald56@gmail.com)) |
| **Status** | Activated |
| **Track** | Standards |

## Abstract

Integrate Avalanche Warp Messaging into the C-Chain and Subnet-EVM in order to bring Cross-Subnet Communication to the EVM on Avalanche.

## Motivation

Avalanche Subnets enable the creation of independent blockchains within the Avalanche Network. Each Avalanche Subnet registers its validator set on the Avalanche P-Chain, which serves as an effective "membership chain" for the entire Avalanche Ecosystem.

By providing read access to the validator set of every Subnet on the Avalanche Network, any Subnet can look up the validator set of any other Subnet within the Avalanche Ecosystem to verify an Avalanche Warp Message, which replaces the need for point-to-point exchange of validator set info between Subnets. This enables a light weight protocol that allows seamless, on-demand communication between Subnets.

For more information on the Avalanche Warp Messaging message and payload formats see here:

- [AWM Message Format](https://github.com/ava-labs/avalanchego/tree/v1.10.15/vms/platformvm/warp/README.md)
- [Payload Format](https://github.com/ava-labs/avalanchego/tree/v1.10.15/vms/platformvm/warp/payload/README.md)

This ACP proposes to activate Avalanche Warp Messaging on the C-Chain and offer compatible support in Subnet-EVM to provide the first standard implementation of AWM in production on the Avalanche Network.

## Specification

The specification will be broken down into the Solidity interface of the Warp Precompile, a Golang example implementation, the predicate verification, and the proposed gas costs for the Warp Precompile.

The Warp Precompile address is `0x0200000000000000000000000000000000000005`.

### Precompile Solidity Interface

```solidity
// (c) 2022-2023, Ava Labs, Inc. All rights reserved.
// See the file LICENSE for licensing terms.

// SPDX-License-Identifier: MIT

pragma solidity ^0.8.0;

struct WarpMessage {
  bytes32 sourceChainID;
  address originSenderAddress;
  bytes payload;
}

struct WarpBlockHash {
  bytes32 sourceChainID;
  bytes32 blockHash;
}

interface IWarpMessenger {
  event SendWarpMessage(address indexed sender, bytes32 indexed messageID, bytes message);

  // sendWarpMessage emits a request for the subnet to send a warp message from [msg.sender]
  // with the specified parameters.
  // This emits a SendWarpMessage log from the precompile. When the corresponding block is accepted
  // the Accept hook of the Warp precompile is invoked with all accepted logs emitted by the Warp
  // precompile.
  // Each validator then adds the UnsignedWarpMessage encoded in the log to the set of messages
  // it is willing to sign for an off-chain relayer to aggregate Warp signatures.
  function sendWarpMessage(bytes calldata payload) external returns (bytes32 messageID);

  // getVerifiedWarpMessage parses the pre-verified warp message in the
  // predicate storage slots as a WarpMessage and returns it to the caller.
  // If the message exists and passes verification, returns the verified message
  // and true.
  // Otherwise, returns false and the empty value for the message.
  function getVerifiedWarpMessage(uint32 index) external view returns (WarpMessage calldata message, bool valid);

  // getVerifiedWarpBlockHash parses the pre-verified WarpBlockHash message in the
  // predicate storage slots as a WarpBlockHash message and returns it to the caller.
  // If the message exists and passes verification, returns the verified message
  // and true.
  // Otherwise, returns false and the empty value for the message.
  function getVerifiedWarpBlockHash(
    uint32 index
  ) external view returns (WarpBlockHash calldata warpBlockHash, bool valid);

  // getBlockchainID returns the snow.Context BlockchainID of this chain.
  // This blockchainID is the hash of the transaction that created this blockchain on the P-Chain
  // and is not related to the Ethereum ChainID.
  function getBlockchainID() external view returns (bytes32 blockchainID);
}
```

### Warp Predicates and Pre-Verification

Signed Avalanche Warp Messages are encoded in the [EIP-2930 Access List](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-2930.md) of a transaction, so that they can be pre-verified before executing the transactions in the block.

The access list can specify any number of access tuples: a pair of an address and an array of storage slots in EIP-2930. Warp Predicate verification borrows this functionality to encode signed warp messages according to the serialization format defined [here](https://github.com/ava-labs/subnet-evm/blob/v0.5.9/predicate/Predicate.md).

Each Warp specific access tuple included in the access list specifies the Warp Precompile address as the address. The first tuple that specifies the Warp Precompile address is considered to be at index. Each subsequent access tuple that specifies the Warp Precompile address increases the Warp Message index by 1. Access tuples that specify any other address are not included in calculating the index for a specific warp message.

Avalanche Warp Messages are pre-verified (prior to block execution), and outputs a bitset for each transaction where a 1 indicates an Avalanche Warp Message that failed verification at that index. Throughout the EVM execution, the Warp Precompile checks the status of the resulting bit set to determine whether pre-verified messages are considered valid. This has the additional benefit of encoding the Warp pre-verification results in the block, so that verifying a historical block can use the encoded results instead of needing to access potentially old P-Chain state. The result bitset is encoded in the block according to the predicate result specification [here](https://github.com/ava-labs/subnet-evm/blob/v0.5.9/predicate/Results.md).

Each Warp Message in the access list is charged gas to pay for verifying the Warp Message (gas costs are covered below) and is verified with the following steps (see [here](https://github.com/ava-labs/subnet-evm/blob/v0.5.9/x/warp/config.go#L218) for reference implementation):

1. Unpack the predicate bytes
2. Parse the signed Avalanche Warp Message
3. Verify the signature according to the AWM spec in AvalancheGo [here](https://github.com/ava-labs/subnet-evm/blob/v0.5.9/x/warp/config.go#L218) (the quorum numerator/denominator for the C-Chain is 67/100 and is configurable in Subnet-EVM)

### Precompile Implementation

All types, events, and function arguments/outputs are encoded using the ABI package according to the official [Solidity ABI Specification](https://docs.soliditylang.org/en/latest/abi-spec.html).

When the precompile is invoked with a given `calldata` argument, the first four bytes (`calldata[0:4]`) are read as the [function selector](https://docs.soliditylang.org/en/latest/abi-spec.html#function-selector). If the function selector matches the function selector of one of the functions defined by the Solidity interface, the contract invokes the corresponding execution function with the remaining calldata ie. `calldata[4:]`.

For the full specification of the execution functions defined in the Solidity interface, see the reference implementation here:

- [sendWarpMessage](https://github.com/ava-labs/subnet-evm/blob/v0.5.9/x/warp/contract.go#L226)
- [getVerifiedWarpMessage](https://github.com/ava-labs/subnet-evm/blob/v0.5.9/x/warp/contract.go#L187)
- [getVerifiedWarpBlockHash](https://github.com/ava-labs/subnet-evm/blob/v0.5.9/x/warp/contract.go#L145)
- [getBlockchainID](https://github.com/ava-labs/subnet-evm/blob/v0.5.9/x/warp/contract.go#L96)

### Gas Costs

The Warp Precompile charges gas during the verification of included Avalanche Warp Messages, which is included in the intrinsic gas cost of the transaction, and during the execution of the precompile.

#### Verification Gas Costs

Pre-verification charges the following costs for each Avalanche Warp Message:

- GasCostPerSignatureVerification: 20000
- GasCostPerWarpMessageBytes: 100
- GasCostPerWarpSigner: 500

These numbers were determined experimentally using the benchmarks available [here](https://github.com/ava-labs/subnet-evm/blob/master/x/warp/predicate_test.go#L687) to target approximately the same mgas/s as existing precompile benchmarks in the EVM, which ranges between 50-200 mgas/s.

In addition to the benchmarks, the following assumptions and goals were taken into account:

- BLS Public Key Aggregation is extremely fast, resulting in charging more for the base cost of a single BLS Multi-Signature Verification than for adding an additional public key
- The cost per byte included in the transaction should be strictly higher for including Avalanche Warp Messages than via transaction calldata, so that the Warp Precompile does not change the worst case maximum block size

#### Execution Gas Costs

The execution gas costs were determined by summing the cost of the EVM operations that are performed throughout the execution of the precompile with special consideration for added functionality that does not have an existing corollary within the EVM.

##### sendWarpMessage

`sendWarpMessage` charges a base cost of 41,500 gas + 8 gas / payload byte

This is comprised of charging for the following components:

- 375 gas / log operation
- 3 topics * 375 gas / topic
- 20k gas to produce and serve a BLS Signature
- 20k gas to store the Unsigned Warp Message
- 8 gas / payload byte

This charges 20k gas for storing an Unsigned Warp Message although the message is stored in an independent key-value database instead of the active state. This makes it less expensive to store, so 20k gas is a conservative estimate.

Additionally, the cost of serving valid signatures is significantly cheaper than serving state sync and bootstrapping requests, so the cost to validators of serving signatures over time is not considered a significant concern.

`sendWarpMessage` also charges for the log operation it includes commensurate with the gas cost of a standard log operation in the EVM.

A single `SendWarpMessage` log is charged:

- 375 gas base cost
- 375 gas per topic (`eventID`, `sender`, `messageID`)
- 8 byte per / payload byte encoded in the `message` field

Topics are indexed fields encoded as 32 byte values to support querying based on given specified topic values.

##### getBlockchainID

`getBlockchainID` charges 2 gas to serve an already in-memory 32 byte valu commensurate with existing in-memory operations.

##### getVerifiedWarpBlockHash / getVerifiedWarpMessage

`GetVerifiedWarpMessageBaseCost` charges 2 gas for serving a Warp Message (either payload type). Warp message are already in-memory, so it charges 2 gas for access.

`GasCostPerWarpMessageBytes` charges 100 gas per byte of the Avalanche Warp Message that is unpacked into a Solidity struct.

## Backwards Compatibility

Existing EVM opcodes and precompiles are not modified by activating Avalanche Warp Messaging in the EVM. This is an additive change to activate a Warp Precompile on the Avalanche C-Chain and can be scheduled for activation in any VM running on Avalanche Subnets that are capable of sending / verifying the specified payload types.

## Reference Implementation

A full reference implementation can be found in Subnet-EVM v0.5.9 [here](https://github.com/ava-labs/subnet-evm/tree/v0.5.9/x/warp).

## Security Considerations

Verifying an Avalanche Warp Message requires reading the source subnet's validator set at the P-Chain height specified in the [Snowman++ Block Extension](https://github.com/ava-labs/avalanchego/blob/v1.10.15/vms/proposervm/README.md#snowman-block-extension). The Avalanche PlatformVM provides the current state of the Avalanche P-Chain and maintains reverse diff-layers in order to compute Subnets' validator sets at historical points in time.

As a result, verifying a historical Avalanche Warp Message that references an old P-Chain height requires applying diff-layers from the current state back to the referenced P-Chain height. As Subnets and the P-Chain continue to produce and accept new blocks, verifying the Warp Messages in historical blocks becomes increasingly expensive.

To efficiently handle historical blocks containing Avalanche Warp Messages, the EVM uses the result bitset encoded in the block to determine the validity of Avalanche Warp Messages without requiring a historical P-Chain state lookup. This is considered secure because the network already verified the Avalanche Warp Messages when they were originally verified and accepted.

## Open Questions

_How should validator set lookups in Warp Message verification be effectively charged for gas?_

The verification cost of performing a validator set lookup on the P-Chain is currently excluded from the implementation. The cost of this lookup is variable depending on how old the referenced P-Chain height is from the perspective of each validator.

[Ongoing work](https://github.com/ava-labs/avalanchego/pull/1611) can parallelize P-Chain validator set lookups and message verification to reduce the impact on block verification latency to be negligible and reduce costs to reflect the additional bandwidth of encoding Avalanche Warp Messages in the transaction.

## Acknowledgements

Avalanche Warp Messaging and this effort to integrate it into the EVM has been a monumental effort. Thanks to all of the contributors who contributed their ideas, feedback, and development to this effort.

@stephenbuttolph
@patrick-ogrady
@michaelkaplan13
@minghinmatthewlam
@cam-schultz
@xanderdunn
@darioush
@ceyonur

## Copyright

Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

# ACP-31: Enable Subnet Ownership Transfer (/docs/acps/31-enable-subnet-ownership-transfer)

---
title: "ACP-31: Enable Subnet Ownership Transfer"
description: "Details for Avalanche Community Proposal 31: Enable Subnet Ownership Transfer"
edit_url: https://github.com/avalanche-foundation/ACPs/edit/main/ACPs/31-enable-subnet-ownership-transfer/README.md
---

| ACP | 31 |
| :--- | :--- |
| **Title** | Enable Subnet Ownership Transfer |
| **Author(s)** | Dhruba Basu ([@dhrubabasu](https://github.com/dhrubabasu)) |
| **Status** | Activated |
| **Track** | Standards |

## Abstract

Allow the current owner of a Subnet to transfer ownership to a new owner.

## Motivation

Once a Subnet is created on the P-chain through a [CreateSubnetTx](https://github.com/ava-labs/avalanchego/blob/v1.10.15/vms/platformvm/txs/create_subnet_tx.go#L14-L19), the `Owner` of the subnet is currently immutable. Subnet operators may want to transition ownership of the Subnet to a new owner for a number of reasons, not least of all being rotating their control key(s) periodically.

## Specification

Implement a new transaction type (`TransferSubnetOwnershipTx`) that:
1. Takes in a `Subnet`
2. Verifies that the `SubnetAuth` has the right to remove the node from the subnet by verifying it against the `Owner` field in the `CreateSubnetTx` that created the `Subnet`.
3. Takes in a new `Owner` and assigning it as the new owner of `Subnet`

This transaction type should have the following format (code below is presented in Golang):

```go
type TransferSubnetOwnershipTx struct {
	// Metadata, inputs and outputs
	BaseTx `serialize:"true"`
	// ID of the subnet this tx is modifying
	Subnet ids.ID `serialize:"true" json:"subnetID"`
	// Proves that the issuer has the right to remove the node from the subnet.
	SubnetAuth verify.Verifiable `serialize:"true" json:"subnetAuthorization"`
	// Who is now authorized to manage this subnet
	Owner fx.Owner `serialize:"true" json:"newOwner"`
}
```

This transaction type should have type ID `0x21` in codec version `0x00`.

This transaction type should have a fee of `0.001 AVAX`, equivalent to adding a subnet validator/delegator.

## Backwards Compatibility

Adding a new transaction type is an execution change and requires a mandatory upgrade for activation. Implementors must take care to reject this transaction prior to activation. This ACP only details the specification of the `TransferSubnetOwnershipTx` type.

## Reference Implementation

An implementation of `TransferSubnetOwnershipTx` was created [here](https://github.com/ava-labs/avalanchego/pull/2178) and subsequently merged into AvalancheGo. Since the "D" Upgrade is not activated, this transaction will be rejected by AvalancheGo.

If modifications are made to the specification of the transaction as part of the ACP process, the code must be updated prior to activation.

## Security Considerations

No security considerations.

## Open Questions

No open questions.

## Acknowledgements

Thank you [@friskyfoxdk](https://github.com/friskyfoxdk) for filing an [issue](https://github.com/ava-labs/avalanchego/issues/1946) requesting this feature. Thanks to [@StephenButtolph](https://github.com/StephenButtolph) and [@abi87](https://github.com/abi87) for their feedback on the reference implementation.

## Copyright

Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

# ACP-41: Remove Pending Stakers (/docs/acps/41-remove-pending-stakers)

---
title: "ACP-41: Remove Pending Stakers"
description: "Details for Avalanche Community Proposal 41: Remove Pending Stakers"
edit_url: https://github.com/avalanche-foundation/ACPs/edit/main/ACPs/41-remove-pending-stakers/README.md
---

| ACP | 41 |
| :--- | :--- |
| **Title** | Remove Pending Stakers |
| **Author(s)** | Dhruba Basu ([@dhrubabasu](https://github.com/dhrubabasu)) |
| **Status** | Activated |
| **Track** | Standards |

## Abstract

Remove user-specified `StartTime` for stakers. Start the staking period for a staker as soon as their staking transaction is accepted. This greatly reduces the computational load on the P-chain, increasing the efficiency of all Avalanche Network validators.

## Motivation

Stakers currently set a `StartTime` for their staking period. This means that Avalanche Network Clients, like AvalancheGo, need to maintain a pending set of all stakers that have not yet started. This places a nontrivial amount of work on the P-chain:

- When a new delegator transaction is verified, the pending set needs to be checked to ensure that the validator they are delegating to will not exceed `MaxValidatorStake` while they are active
- When a new staker transaction is accepted, it gets added to the pending set
- When time is advanced on the P-chain, any stakers in the pending set whose `StartTime &lt;= CurrentTime` need to be moved to the current set

By immediately starting every staker on acceptance, the validators do not have to do the above work when validating the P-chain. `MaxValidatorStake` will become an `O(1)` operation as only the current stake of the validator needs to be checked. The pending set can be fully removed.

## Specification

1. When adding a new staker, the current on-chain time should be used for the staker's start time.
2. When determining when to remove the staker from the staker set, the `EndTime` specified in the transaction should continue to be used. Staking transactions should now be rejected if it does not satisfy `MinStakeDuration &lt;= EndTime - CurrentTime &lt;= MaxStakeDuration`. `StartTime` will no longer be validated.

## Backwards Compatibility

Modifying the state transition of a transaction type is an execution change and requires a mandatory upgrade for activation. Implementors must take care to not alter the execution behavior prior to activation. This ACP only details the new state transition.

Current wallet implementations will continue to work as-is post-activation of this ACP since no transaction formats are modified or added. Wallet implementations may run into issues with their txs being rejected as a result of this ACP if `EndTime &gt;= CurrentChainTime + MaxStakeDuration`. `CurrentChainTime` is guaranteed to be &gt;= the latest block timestamp on the P-chain.

## Reference Implementation

A reference implementation has not been created for this ACP since it deals with state management. Each ANC will need to adjust their execution step to follow the Specification detailed above. For AvalancheGo, this work is tracked in this PR: https://github.com/ava-labs/avalanchego/pull/2175

If modifications are made to the specification of the new execution behavior as part of the ACP process, the code must be updated prior to activation.

## Security Considerations

No security considerations.

## Open Questions

_How will stakers stake for `MaxStakeDuration` if they cannot determine their `StartTime`?_

As mentioned above, the beginning of your staking period is the block acceptance timestamp. Unless you can accurately predict the block timestamp, you will *not* be able to fully stake for `MaxStakeDuration`. This is an explicit trade-off to guarantee that stakers will receive their original stake + any staking rewards at `EndTime`.

Delegators can maximize their staking period by setting the same `EndTime` as the Validator they are delegating to.

## Acknowledgements

Thanks to [@StephenButtolph](https://github.com/StephenButtolph) and [@abi87](https://github.com/abi87) for their feedback on these ideas.

## Copyright

Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

# ACP-62: Disable Addvalidatortx And Adddelegatortx (/docs/acps/62-disable-addvalidatortx-and-adddelegatortx)

---
title: "ACP-62: Disable Addvalidatortx And Adddelegatortx"
description: "Details for Avalanche Community Proposal 62: Disable Addvalidatortx And Adddelegatortx"
edit_url: https://github.com/avalanche-foundation/ACPs/edit/main/ACPs/62-disable-addvalidatortx-and-adddelegatortx/README.md
---

| ACP | 62 |
| :--- | :--- |
| **Title** | Disable `AddValidatorTx` and `AddDelegatorTx` |
| **Author(s)** | Jacob Everly ([@JacobEv3rly](https://twitter.com/JacobEv3rly)), Dhruba Basu ([@dhrubabasu](https://github.com/dhrubabasu)) |
| **Status** | Activated |
| **Track** | Standards |

## Abstract

Disable `AddValidatorTx` and `AddDelegatorTx` to push all new stakers to use `AddPermissionlessValidatorTx` and `AddPermissionlessDelegatorTx`. `AddPermissionlessValidatorTx` requires validators to register a BLS key. Wide adoption of registered BLS keys accelerates the timeline for future P-Chain upgrades. Additionally, this reduces the number of ways to participate in Primary Network validation from two to one.

## Motivation

`AddPermissionlessValidatorTx` and `AddPermissionlessDelegatorTx` were activated on the Avalanche Network in October 2022 with Banff (v1.9.0). This unlocked the ability for Subnet creators to activate Proof-of-Stake validation using their own token on their own Subnet. See more details about Banff [here](https://medium.com/avalancheavax/banff-elastic-subnets-44042f41e34c).

These new transaction types can also be used to register a Primary Network validator, leaving two redundant transactions: `AddValidatorTx` and `AddDelegatorTx`.

[`AddPermissionlessDelegatorTx`](https://github.com/ava-labs/avalanchego/blob/v1.10.18/vms/platformvm/txs/add_permissionless_delegator_tx.go#L25-L37) contains the same fields as [`AddDelegatorTx`](https://github.com/ava-labs/avalanchego/blob/v1.10.18/vms/platformvm/txs/add_delegator_tx.go#L29-L39) with an additional `Subnet` field.

[`AddPermissionlessValidatorTx`](https://github.com/ava-labs/avalanchego/blob/v1.10.18/vms/platformvm/txs/add_permissionless_validator_tx.go#L35-L59) contains the same fields as [`AddValidatorTx`](https://github.com/ava-labs/avalanchego/blob/v1.10.18/vms/platformvm/txs/add_validator_tx.go#L29-L42) with additional `Subnet` and `Signer` fields. `RewardsOwner` was also split into `ValidationRewardsOwner` and `DelegationRewardsOwner` letting validators divert rewards they receive from delegators into a separate rewards owner.

By disabling support of `AddValidatorTx`, all new validators on the Primary Network must use `AddPermissionlessValidatorTx` and register a BLS key with their NodeID. As more validators attach BLS keys to their nodes, future upgrades using these BLS keys can be activated through the ACP process. BLS keys can be used to efficiently sign a common message via [Public Key Aggregation](https://crypto.stanford.edu/~dabo/pubs/papers/BLSmultisig.html). Applications of this include, but are not limited to:

- **Arbitrary Subnet Rewards**: The P-Chain currently restricts Elastic Subnets to follow the reward curve defined in a `TransformSubnetTx`. With sufficient BLS key adoption, Elastic Subnets can define their own reward curve and reward conditions. The P-Chain can be modified to take in a message indicating if a Subnet validator should be rewarded with how many tokens signed with a BLS Multi-Signature.
- **Subnet Attestations**: Elastic Subnets can attest to the state of their Subnet with a BLS Multi-Signature. This can enable clients to fetch the current state of the Subnet without syncing the entire Subnet. `StateSync` enables clients to download chain state from peers up to a recent block near tip. However, it is up to the client to query these peers and resolve any potential conflicts in the responses. With Subnet Attestations, clients can query an API node to prove information about a Subnet without querying the Subnet's validators. This can especially be useful for [Subnet-Only Validators](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/62-disable-addvalidatortx-and-adddelegatortx/13-subnet-only-validators.md) to prove information about the C-Chain.

To accelerate future BLS-powered advancements in the Avalanche Network, this ACP aims to disable `AddValidatorTx` and `AddDelegatorTx` in Durango.

## Specification

`AddValidatorTx` and `AddDelegatorTx` should be marked as dropped when added to the mempool after activation. Any blocks including these transactions should be considered invalid.

## Backwards Compatibility

Disabling a transaction type is an execution change and requires a mandatory upgrade for activation. Implementers must take care to not alter the execution behavior prior to activation.

After this ACP is activated, any new issuance of `AddValidatorTx` or `AddDelegatorTx` will be considered invalid and dropped by the network. Any consumers of these transactions must transition to using `AddPermissionlessValidatorTx` and `AddPermissionlessDelegatorTx` to participate in Primary Network validation. The [Avalanche Ledger App](https://github.com/LedgerHQ/app-avalanche) supports both of these transaction types.

Note that `AddSubnetValidatorTx` and `RemoveSubnetValidatorTx` are unchanged by this ACP.

## Reference Implementation

An implementation disabling `AddValidatorTx` and `AddDelegatorTx` was created [here](https://github.com/ava-labs/avalanchego/pull/2662). Until activation, these transactions will continue to be accepted by AvalancheGo.

If modifications are made to the specification as part of the ACP process, the code must be updated prior to activation.

## Security Considerations

No security considerations.

## Open Questions

## Acknowledgements

Thanks to [@StephenButtolph](https://github.com/StephenButtolph) and [@patrick-ogrady](https://github.com/patrick-ogrady) for their feedback on these ideas.

## Copyright

Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

# ACP-75: Acceptance Proofs (/docs/acps/75-acceptance-proofs)

---
title: "ACP-75: Acceptance Proofs"
description: "Details for Avalanche Community Proposal 75: Acceptance Proofs"
edit_url: https://github.com/avalanche-foundation/ACPs/edit/main/ACPs/75-acceptance-proofs/README.md
---

| ACP | 75 |
| :--- | :--- |
| **Title** | Acceptance Proofs |
| **Author(s)** | Joshua Kim |
| **Status** | Proposed ([Discussion](https://github.com/avalanche-foundation/ACPs/discussions/82)) |
| **Track** | Standards |

## Abstract

Introduces support for a proof of a block’s acceptance in consensus.

## Motivation

Subnets are able to prove arbitrary events using warp messaging, but native support for proving block acceptance at the protocol layer enables more utility. Acceptance proofs are introduced to prove that a block has been accepted by a subnet. One example use case for acceptance proofs is to provide stronger fault isolation guarantees from the primary network to subnets.

Subnets use the [ProposerVM](https://github.com/ava-labs/avalanchego/blob/416fbdf1f783c40f21e7009a9f06d192e69ba9b5/vms/proposervm/README.md) to implement soft leader election for block proposal. The ProposerVM determines the block producer schedule from a randomly shuffled validator set at a specified P-Chain block height. Validators are therefore required to have the P-Chain block referenced in a block's header to verify the block producer against the expected block producer schedule. If a block's header specifies a P-Chain height that has not been accepted yet, the block is treated as invalid. If a block referencing an unknown P-Chain height was produced virtuously, it is expected that the validator will eventually discover the block as its P-Chain height advances and accept the block.

If many validators disagree about the current tip of the P-Chain, it can lead to a liveness concern on the subnet where block production entirely stalls. In practice, this almost never occurs because nodes produce blocks with a lagging P-Chain height because it’s likely that most nodes will have accepted a sufficiently stale block. This however, relies on an assumption that validators are constantly making progress in consensus on the P-Chain to prevent the subnet from stalling. This leaves an open concern where the P-Chain stalling on a node would prevent it from verifying any blocks, leading to a subnet unable to produce blocks if many validators stalled at different P-Chain heights.

---

Figure 1: A Validator that has synced P-Chain blocks `A` and `B` fails verification of a block proposed at block `C`.

<img alt="figure 1" src="https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/75-acceptance-proofs/1.jpg" />

---

We introduce "acceptance proofs", so that a peer can verify any block accepted by consensus. In the aforementioned use-case, if a P-Chain block is unknown by a peer, it can request the block and proof at the provided height from a peer. If a block's proof is valid, the block can be executed to advance the local P-Chain and verify the proposed subnet block. Peers can request blocks from any peer without requiring consensus locally or communication with a validator. This has the added benefit of reducing the number of required connections and p2p message load served by P-Chain validators.

---

Figure 2: A Validator is verifying a subnet’s block `Z` which references an unknown P-Chain block `C` in its block header

<img alt="figure 2" src="https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/75-acceptance-proofs/2.jpg" />

Figure 3: A Validator requests the blocks and proofs for `B` and `C` from a peer

<img alt="figure 3" src="https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/75-acceptance-proofs/3.jpg" />

Figure 4: The Validator accepts the P-Chain blocks and is now able to verify `Z`

<img alt="figure 4" src="https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/75-acceptance-proofs/4.jpg" />

---

## Specification

Note: The following is pseudocode.

### P2P

#### Aggregation

```diff
+ message GetAcceptanceSignatureRequest {
+   bytes chain_id = 1;
+   uint32 request_id = 2;
+   bytes block_id = 3;
+ }
```

The `GetAcceptanceSignatureRequest` message is sent to a peer to request their signature for a given block id.

```diff
+ message GetAcceptanceSignatureResponse {
+   bytes chain_id = 1;
+   uint32 request_id = 2;
+   bytes bls_signature = 3;
+ }
```

`GetAcceptanceSignatureResponse` is sent to a peer as a response for `GetAcceptanceSignatureRequest`. `bls_signature` is the peer’s signature using their registered primary network BLS staking key over the requested `block_id`. An empty `bls_signature` field indicates that the block was not accepted yet.

## Security Considerations

Nodes that bootstrap using state sync may not have the entire history of the
P-Chain and therefore will not be able to provide the entire history for a block
that is referenced in a block that they propose. This would be needed to unblock a node that is attempting to fast-forward their P-Chain, as they require the entire ancestry between their current accepted tip and the block they are attempting to forward to. It is assumed that nodes will have some minimum amount of recent state so that the requester can eventually be unblocked by retrying, as only one node with the requested ancestry is required to unblock the requester.

An alternative is to make a churn assumption and validate the proposed block's proof with a stale validator set to avoid complexity, but this introduces more security concerns.

## Copyright

Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

# ACP-77: Reinventing Subnets (/docs/acps/77-reinventing-subnets)

---
title: "ACP-77: Reinventing Subnets"
description: "Details for Avalanche Community Proposal 77: Reinventing Subnets"
edit_url: https://github.com/avalanche-foundation/ACPs/edit/main/ACPs/77-reinventing-subnets/README.md
---

| ACP           | 77                                                                                        |
| :------------ | :---------------------------------------------------------------------------------------- |
| **Title**     | Reinventing Subnets                                                                       |
| **Author(s)** | Dhruba Basu ([@dhrubabasu](https://github.com/dhrubabasu))                                |
| **Status**    | Activated ([Discussion](https://github.com/avalanche-foundation/ACPs/discussions/78)) |
| **Track**     | Standards                                                                                 |
| **Replaces**  | [ACP-13](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/13-subnet-only-validators/README.md)                                          |

## Abstract

Overhaul Subnet creation and management to unlock increased flexibility for Subnet creators by:

- Separating Subnet validators from Primary Network validators (Primary Network Partial Sync, Removal of 2000 $AVAX requirement)
- Moving ownership of Subnet validator set management from P-Chain to Subnets (ERC-20/ERC-721/Arbitrary Staking, Staking Reward Management)
- Introducing a continuous P-Chain fee mechanism for Subnet validators (Continuous Subnet Staking)

This ACP supersedes [ACP-13](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/13-subnet-only-validators/README.md) and borrows some of its language.

## Motivation

Each node operator must stake at least 2000 $AVAX ($70k at time of writing) to first become a Primary Network validator before they qualify to become a Subnet validator. Most Subnets aim to launch with at least 8 Subnet validators, which requires staking 16000 $AVAX ($560k at time of writing). All Subnet validators, to satisfy their role as Primary Network validators, must also [allocate 8 AWS vCPU, 16 GB RAM, and 1 TB storage](https://github.com/ava-labs/avalanchego/blob/master/README.md#installation) to sync the entire Primary Network (X-Chain, P-Chain, and C-Chain) and participate in its consensus, in addition to whatever resources are required for each Subnet they are validating.

Regulated entities that are prohibited from validating permissionless, smart contract-enabled blockchains (like the C-Chain) cannot launch a Subnet because they cannot opt-out of Primary Network Validation. This deployment blocker prevents a large cohort of Real World Asset (RWA) issuers from bringing unique, valuable tokens to the Avalanche Ecosystem (that could move between C-Chain &lt;-&gt; Subnets using Avalanche Warp Messaging/Teleporter).

A widely validated Subnet that is not properly metered could destabilize the Primary Network if usage spikes unexpectedly. Underprovisioned Primary Network validators running such a Subnet may exit with an OOM exception, see degraded disk performance, or find it difficult to allocate CPU time to P/X/C-Chain validation. The inverse also holds for Subnets with the Primary Network (where some undefined behavior could bring a Subnet offline).

Although the fee paid to the Primary Network to operate a Subnet does not go up with the amount of activity on the Subnet, the fixed, upfront cost of setting up a Subnet validator on the Primary Network deters new projects that prefer smaller, even variable, costs until demand is observed. _Unlike L2s that pay some increasing fee (usually denominated in units per transaction byte) to an external chain for data availability and security as activity scales, Subnets provide their own security/data availability and the only cost operators must pay from processing more activity is the hardware cost of supporting additional load._

Elastic Subnets, introduced in [Banff](https://medium.com/avalancheavax/banff-elastic-subnets-44042f41e34c), enabled Subnet creators to activate Proof-of-Stake validation and uptime-based rewards using their own token. However, this token is required to be an ANT (created on the X-Chain) and locked on the P-Chain. All staking rewards were distributed on the P-Chain with the reward curve being defined in the `TransformSubnetTx` and, once set, was unable to be modified.

With no Elastic Subnets live on Mainnet, it is clear that Permissionless Subnets as they stand today could be more desirable. There are many successful Permissioned Subnets in production but many Subnet creators have raised the above as points of concern. In summary, the Avalanche community could benefit from a more flexible and affordable mechanism to launch Permissionless Subnets.

### A Note on Nomenclature

Avalanche Subnets are subnetworks validated by a subset of the Primary Network validator set. The new network creation flow outlined in this ACP does not require any intersection between the new network's validator set and the Primary Network's validator set. Moreover, the new networks have greater functionality and sovereignty than Subnets. To distinguish between these two kinds of networks, the community has been referring to these new networks as _Avalanche Layer 1s_, or L1s for short.

All networks created through the old network creation flow will continue to be referred to as Avalanche Subnets.

## Specification

At a high-level, L1s can manage their validator sets externally to the P-Chain by setting the blockchain ID and address of their _validator manager_. The P-Chain will consume Warp messages that modify the L1's validator set. To confirm modification of the L1's validator set, the P-Chain will also produce Warp messages. L1 validators are not required to validate the Primary Network, and do not have the same 2000 $AVAX stake requirement that Subnet validators have. To maintain an active L1 validator, a continuous fee denominated in $AVAX is assessed. L1 validators are only required to sync the P-Chain (not X/C-Chain) in order to track validator set changes and support cross-L1 communication.

### P-Chain Warp Message Payloads

To enable management of an L1's validator set externally to the P-Chain, Warp message verification will be added to the [`PlatformVM`](https://github.com/ava-labs/avalanchego/tree/master/vms/platformvm). For a Warp message to be considered valid by the P-Chain, at least 67% of the `sourceChainID`'s weight must have participated in the aggregate BLS signature. This is equivalent to the threshold set for the C-Chain. A future ACP may be proposed to support modification of this threshold on a per-L1 basis.

The following Warp message payloads are introduced on the P-Chain:

- `SubnetToL1ConversionMessage`
- `RegisterL1ValidatorMessage`
- `L1ValidatorRegistrationMessage`
- `L1ValidatorWeightMessage`

The method of requesting signatures for these messages is left unspecified. A viable option for supporting this functionality is laid out in [ACP-118](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/118-warp-signature-request/README.md) with the `SignatureRequest` message.

All node IDs contained within the message specifications are represented as variable length arrays such that they can support new node IDs types should the P-Chain add support for them in the future.

The serialization of each of these messages is as follows.

#### `SubnetToL1ConversionMessage`

The P-Chain can produce a `SubnetToL1ConversionMessage` for consumers (i.e. validator managers) to be aware of the initial validator set.

The following serialization is defined as the `ValidatorData`:

|          Field |       Type |                     Size |
| -------------: | ---------: | -----------------------: |
|       `nodeID` |   `[]byte` |  4 + len(`nodeID`) bytes |
| `blsPublicKey` | `[48]byte` |                 48 bytes |
|       `weight` |   `uint64` |                  8 bytes |
|                |            | 60 + len(`nodeID`) bytes |

The following serialization is defined as the `ConversionData`:

|            Field |              Type |                                                       Size |
| ---------------: | ----------------: | ---------------------------------------------------------: |
|        `codecID` |          `uint16` |                                                    2 bytes |
|       `subnetID` |        `[32]byte` |                                                   32 bytes |
| `managerChainID` |        `[32]byte` |                                                   32 bytes |
| `managerAddress` |          `[]byte` |                            4 + len(`managerAddress`) bytes |
|     `validators` | `[]ValidatorData` |                          4 + sum(`validatorLengths`) bytes |
|                  |                   | 74 + len(`managerAddress`) + sum(`validatorLengths`) bytes |

- `codecID` is the codec version used to serialize the payload, and is hardcoded to `0x0000`
- `sum(validatorLengths)` is the sum of the lengths of `ValidatorData` serializations included in `validators`.
- `subnetID` identifies the Subnet that is being converted to an L1 (described further below).
- `managerChainID` and `managerAddress` identify the validator manager for the newly created L1. This is the (blockchain ID, address) tuple allowed to send Warp messages to modify the L1's validator set.
- `validators` are the initial continuous-fee-paying validators for the given L1.

The `SubnetToL1ConversionMessage` is specified as an `AddressedCall` with `sourceChainID` set to the P-Chain ID, the `sourceAddress` set to an empty byte array, and a payload of:

|          Field |       Type |     Size |
| -------------: | ---------: | -------: |
|      `codecID` |   `uint16` |  2 bytes |
|       `typeID` |   `uint32` |  4 bytes |
| `conversionID` | `[32]byte` | 32 bytes |
|                |            | 38 bytes |

- `codecID` is the codec version used to serialize the payload, and is hardcoded to `0x0000`
- `typeID` is the payload type identifier and is `0x00000000` for this message
- `conversionID` is the SHA256 hash of the `ConversionData` from a given `ConvertSubnetToL1Tx`

#### `RegisterL1ValidatorMessage`

The P-Chain can consume a `RegisterL1ValidatorMessage` from validator managers through a `RegisterL1ValidatorTx` to register an addition to the L1's validator set.

The following is the serialization of a `PChainOwner`:

|       Field |         Type |                             Size |
| ----------: | -----------: | -------------------------------: |
| `threshold` |     `uint32` |                          4 bytes |
| `addresses` | `[][20]byte` | 4 + len(`addresses`) \\* 20 bytes |
|             |              | 8 + len(`addresses`) \\* 20 bytes |

- `threshold` is the number of `addresses` that must provide a signature for the `PChainOwner` to authorize an action.
- Validation criteria:
  - If `threshold` is `0`, `addresses` must be empty
  - `threshold` &lt;= len(`addresses`)
  - Entries of `addresses` must be unique and sorted in ascending order

The `RegisterL1ValidatorMessage` is specified as an `AddressedCall` with a payload of:

|                   Field |          Type |                                                                      Size |
| ----------------------: | ------------: | ------------------------------------------------------------------------: |
|               `codecID` |      `uint16` |                                                                   2 bytes |
|                `typeID` |      `uint32` |                                                                   4 bytes |
|              `subnetID` |    `[32]byte` |                                                                  32 bytes |
|                `nodeID` |      `[]byte` |                                                   4 + len(`nodeID`) bytes |
|          `blsPublicKey` |    `[48]byte` |                                                                  48 bytes |
|                `expiry` |      `uint64` |                                                                   8 bytes |
| `remainingBalanceOwner` | `PChainOwner` |                                          8 + len(`addresses`) \\* 20 bytes |
|          `disableOwner` | `PChainOwner` |                                          8 + len(`addresses`) \\* 20 bytes |
|                `weight` |      `uint64` |                                                                   8 bytes |
|                         |               | 122 + len(`nodeID`) + (len(`addresses1`) + len(`addresses2`)) \\* 20 bytes |

- `codecID` is the codec version used to serialize the payload, and is hardcoded to `0x0000`
- `typeID` is the payload type identifier and is `0x00000001` for this payload
- `subnetID`, `nodeID`, `weight`, and `blsPublicKey` are for the validator being added
- `expiry` is the time at which this message becomes invalid. As of a P-Chain timestamp `&gt;= expiry`, this Avalanche Warp Message can no longer be used to add the `nodeID` to the validator set of `subnetID`
- `remainingBalanceOwner` is the P-Chain owner where leftover $AVAX from the validator's Balance will be issued to when this validator it is removed from the validator set.
- `disableOwner` is the only P-Chain owner allowed to disable the validator using `DisableL1ValidatorTx`, specified below.

#### `L1ValidatorRegistrationMessage`

The P-Chain can produce an `L1ValidatorRegistrationMessage` for consumers to verify that a validation period has either begun or has been invalidated.

The `L1ValidatorRegistrationMessage` is specified as an `AddressedCall` with `sourceChainID` set to the P-Chain ID, the `sourceAddress` set to an empty byte array, and a payload of:

|          Field |       Type |     Size |
| -------------: | ---------: | -------: |
|      `codecID` |   `uint16` |  2 bytes |
|       `typeID` |   `uint32` |  4 bytes |
| `validationID` | `[32]byte` | 32 bytes |
|   `registered` |     `bool` |   1 byte |
|                |            | 39 bytes |

- `codecID` is the codec version used to serialize the payload, and is hardcoded to `0x0000`
- `typeID` is the payload type identifier and is `0x00000002` for this message
- `validationID` identifies the validator for the message
- `registered` is a boolean representing the status of the `validationID`. If true, the `validationID` corresponds to a validator in the current validator set. If false, the `validationID` does not correspond to a validator in the current validator set, and never will in the future.

#### `L1ValidatorWeightMessage`

The P-Chain can consume an `L1ValidatorWeightMessage` through a `SetL1ValidatorWeightTx` to update the weight of an existing validator. The P-Chain can also produce an `L1ValidatorWeightMessage` for consumers to verify that the validator weight update has been effectuated.

The `L1ValidatorWeightMessage` is specified as an `AddressedCall` with the following payload. When sent from the P-Chain, the `sourceChainID` is set to the P-Chain ID, and the `sourceAddress` is set to an empty byte array.

|          Field |       Type |     Size |
| -------------: | ---------: | -------: |
|      `codecID` |   `uint16` |  2 bytes |
|       `typeID` |   `uint32` |  4 bytes |
| `validationID` | `[32]byte` | 32 bytes |
|        `nonce` |   `uint64` |  8 bytes |
|       `weight` |   `uint64` |  8 bytes |
|                |            | 54 bytes |

- `codecID` is the codec version used to serialize the payload, and is hardcoded to `0x0000`
- `typeID` is the payload type identifier and is `0x00000003` for this message
- `validationID` identifies the validator for the message
- `nonce` is a strictly increasing number that denotes the latest validator weight update and provides replay protection for this transaction
- `weight` is the new `weight` of the validator

### New P-Chain Transaction Types

Both before and after this ACP, to create a Subnet, a `CreateSubnetTx` must be issued on the P-Chain. This transaction includes an `Owner` field which defines the key that today can be used to authorize any validator set additions (`AddSubnetValidatorTx`) or removals (`RemoveSubnetValidatorTx`).

To be considered a permissionless network, or Avalanche Layer 1:

- This `Owner` key must no longer have the ability to modify the validator set.
- New transaction types must support modification of the validator set via Warp messages.

The following new transaction types are introduced on the P-Chain to support this functionality:

- `ConvertSubnetToL1Tx`
- `RegisterL1ValidatorTx`
- `SetL1ValidatorWeightTx`
- `DisableL1ValidatorTx`
- `IncreaseL1ValidatorBalanceTx`

#### `ConvertSubnetToL1Tx`

To convert a Subnet into an L1, a `ConvertSubnetToL1Tx` must be issued to set the `(chainID, address)` pair that will manage the L1's validator set. The `Owner` key defined in `CreateSubnetTx` must provide a signature to authorize this conversion.

The `ConvertSubnetToL1Tx` specification is:

```go
type PChainOwner struct {
    // The threshold number of `Addresses` that must provide a signature in order for
    // the `PChainOwner` to be considered valid.
    Threshold uint32 `json:"threshold"`
    // The 20-byte addresses that are allowed to sign to authenticate a `PChainOwner`.
    // Note: It is required for:
    //       - len(Addresses) == 0 if `Threshold` is 0.
    //       - len(Addresses) &gt;= `Threshold`
    //       - The values in Addresses to be sorted in ascending order.
    Addresses []ids.ShortID `json:"addresses"`
}

type L1Validator struct {
    // NodeID of this validator
    NodeID []byte `json:"nodeID"`
    // Weight of this validator used when sampling
    Weight uint64 `json:"weight"`
    // Initial balance for this validator
    Balance uint64 `json:"balance"`
    // [Signer] is the BLS public key and proof-of-possession for this validator.
    // Note: We do not enforce that the BLS key is unique across all validators.
    //       This means that validators can share a key if they so choose.
    //       However, a NodeID + L1 does uniquely map to a BLS key
    Signer signer.ProofOfPossession `json:"signer"`
    // Leftover $AVAX from the [Balance] will be issued to this
    // owner once it is removed from the validator set.
    RemainingBalanceOwner PChainOwner `json:"remainingBalanceOwner"`
    // The only owner allowed to disable this validator on the P-Chain.
    DisableOwner PChainOwner `json:"disableOwner"`
}

type ConvertSubnetToL1Tx struct {
    // Metadata, inputs and outputs
    BaseTx
    // ID of the Subnet to transform
    // Restrictions:
    // - Must not be the Primary Network ID
    Subnet ids.ID `json:"subnetID"`
    // BlockchainID where the validator manager lives
    ChainID ids.ID `json:"chainID"`
    // Address of the validator manager
    Address []byte `json:"address"`
    // Initial continuous-fee-paying validators for the L1
    Validators []L1Validator `json:"validators"`
    // Authorizes this conversion
    SubnetAuth verify.Verifiable `json:"subnetAuthorization"`
}
```

After this transaction is accepted, `CreateChainTx` and `AddSubnetValidatorTx` are disabled on the Subnet. The only action that the `Owner` key is able to take is removing Subnet validators with `RemoveSubnetValidatorTx` that had been added using `AddSubnetValidatorTx`. Unless removed by the `Owner` key, any Subnet validators added previously with an `AddSubnetValidatorTx` will continue to validate the Subnet until their [`End`](https://github.com/ava-labs/avalanchego/blob/a1721541754f8ee23502b456af86fea8c766352a/vms/platformvm/txs/validator.go#L27) time is reached. Once all Subnet validators added with `AddSubnetValidatorTx` are no longer in the validator set, the `Owner` key is powerless. `RegisterL1ValidatorTx` and `SetL1ValidatorWeightTx` must be used to manage the L1's validator set.

The `validationID` for validators added through `ConvertSubnetToL1Tx` is defined as the SHA256 hash of the 36 bytes resulting from concatenating the 32 byte `subnetID` with the 4 byte `validatorIndex` (index in the `Validators` array within the transaction).

Once this transaction is accepted, the P-Chain must be willing sign a `SubnetToL1ConversionMessage` with a `conversionID` corresponding to `ConversionData` populated with the values from this transaction.

#### `RegisterL1ValidatorTx`

After a `ConvertSubnetToL1Tx` has been accepted, new validators can only be added by using a `RegisterL1ValidatorTx`. The specification of this transaction is:

```go
type RegisterL1ValidatorTx struct {
    // Metadata, inputs and outputs
    BaseTx
    // Balance &lt;= sum($AVAX inputs) - sum($AVAX outputs) - TxFee.
    Balance uint64 `json:"balance"`
    // [Signer] is a BLS signature proving ownership of the BLS public key specified
    // below in `Message` for this validator.
    // Note: We do not enforce that the BLS key is unique across all validators.
    //       This means that validators can share a key if they so choose.
    //       However, a NodeID + L1 does uniquely map to a BLS key
    Signer [96]byte `json:"signer"`
    // A RegisterL1ValidatorMessage payload
    Message warp.Message `json:"message"`
}
```

The `validationID` of validators added via `RegisterL1ValidatorTx` is defined as the SHA256 hash of the `Payload` of the `AddressedCall` in `Message`.

When a `RegisterL1ValidatorTx` is accepted on the P-Chain, the validator is added to the L1's validator set. A `minNonce` field corresponding to the `validationID` will be stored on addition to the validator set (initially set to `0`). This field will be used when validating the `SetL1ValidatorWeightTx` defined below.

This `validationID` will be used for replay protection. Used `validationID`s will be stored on the P-Chain. If a `RegisterL1ValidatorTx`'s `validationID` has already been used, the transaction will be considered invalid. To prevent storing an unbounded number of `validationID`s, the `expiry` of the `RegisterL1ValidatorMessage` is required to be no more than 24 hours in the future of the time the transaction is issued on the P-Chain. Any `validationIDs` corresponding to an expired timestamp can be flushed from the P-Chain's state.

L1s are responsible for defining the procedure on how to retrieve the above information from prospective validators.

An EVM-compatible L1 may choose to implement this step like so:

- Use the number of tokens the user has staked into a smart contract on the L1 to determine the weight of their validator
- Require the user to submit an on-chain transaction with their validator information
- Generate the Warp message

For a `RegisterL1ValidatorTx` to be valid, `Signer` must be a valid proof-of-possession of the `blsPublicKey` defined in the `RegisterL1ValidatorMessage` contained in the transaction.

After a `RegisterL1ValidatorTx` is accepted, the P-Chain must be willing to sign an `L1ValidatorRegistrationMessage` for the given `validationID` with `registered` set to `true`. This remains the case until the time at which the validator is removed from the validator set using a `SetL1ValidatorWeightTx`, as described below.

When it is known that a given `validationID` _is not and never will be_ registered, the P-Chain must be willing to sign an `L1ValidatorRegistrationMessage` for the `validationID` with `registered` set to `false`. This could be the case if the `expiry` time of the message has passed prior to the message being delivered in a `RegisterL1ValidatorTx`, or if the validator was successfully registered and then later removed. This enables the P-Chain to prove to validator managers that a validator has been removed or never added. The P-Chain must refuse to sign any `L1ValidatorRegistrationMessage` where the `validationID` does not correspond to an active validator and the `expiry` is in the future.

#### `SetL1ValidatorWeightTx`

`SetL1ValidatorWeightTx` is used to modify the voting weight of a validator. The specification of this transaction is:

```go
type SetL1ValidatorWeightTx struct {
    // Metadata, inputs and outputs
    BaseTx
    // An L1ValidatorWeightMessage payload
    Message warp.Message `json:"message"`
}
```

Applications of this transaction could include:

- Increase the voting weight of a validator if a delegation is made on the L1
- Increase the voting weight of a validator if the stake amount is increased (by staking rewards for example)
- Decrease the voting weight of a misbehaving validator
- Remove an inactive validator

The validation criteria for `L1ValidatorWeightMessage` is:

- `nonce &gt;= minNonce`. Note that `nonce` is not required to be incremented by `1` with each successive validator weight update.
- When `minNonce == MaxUint64`, `nonce` must be `MaxUint64` and `weight` must be `0`. This prevents L1s from being unable to remove `nodeID` in a subsequent transaction.
- If `weight == 0`, the validator being removed must not be the last one in the set. If all validators are removed, there are no valid Warp messages that can be produced to register new validators through `RegisterL1ValidatorMessage`. With no validators, block production will halt and the L1 is unrecoverable. This validation criteria serves as a guardrail against this situation. A future ACP can remove this guardrail as users get more familiar with the new L1 mechanics and tooling matures to fork an L1.

When `weight != 0`, the weight of the validator is updated to `weight` and `minNonce` is updated to `nonce + 1`.

When `weight == 0`, the validator is removed from the validator set. All state related to the validator, including the `minNonce` and `validationID`, are reaped from the P-Chain state. Tracking these post-removal is not required since `validationID` can never be re-initialized due to the replay protection provided by `expiry` in `RegisterL1ValidatorTx`. Any unspent $AVAX in the validator's `Balance` will be issued in a single UTXO to the `RemainingBalanceOwner` for this validator. Recall that `RemainingBalanceOwner` is specified when the validator is first added to the L1's validator set (in either `ConvertSubnetToL1Tx` or `RegisterL1ValidatorTx`).

Note: There is no explicit `EndTime` for L1 validators added in a `ConvertSubnetToL1Tx` or `RegisterL1ValidatorTx`. The only time when L1 validators are removed from the L1's validator set is through this transaction when `weight == 0`.

#### `DisableL1ValidatorTx`

L1 validators can use `DisableL1ValidatorTx` to mark their validator as inactive. The specification of this transaction is:

```go
type DisableL1ValidatorTx struct {
    // Metadata, inputs and outputs
    BaseTx
    // ID corresponding to the validator
    ValidationID ids.ID `json:"validationID"`
    // Authorizes this validator to be disabled
    DisableAuth verify.Verifiable `json:"disableAuthorization"`
}
```

The `DisableOwner` specified for this validator must sign the transaction. Any unspent $AVAX in the validator's `Balance` will be issued in a single UTXO to the `RemainingBalanceOwner` for this validator. Recall that both `DisableOwner` and `RemainingBalanceOwner` are specified when the validator is first added to the L1's validator set (in either `ConvertSubnetToL1Tx` or `RegisterL1ValidatorTx`).

For full removal from an L1's validator set, a `SetL1ValidatorWeightTx` must be issued with weight `0`. To do so, a Warp message is required from the L1's validator manager. However, to support the ability to claim the unspent `Balance` for a validator without authorization is critical for failed L1s.

Note that this does not modify an L1's total staking weight. This transaction marks the validator as inactive, but does not remove it from the L1's validator set. Inactive validators can re-activate at any time by increasing their balance with an `IncreaseL1ValidatorBalanceTx`.

L1 creators should be aware that there is no notion of `MinStakeDuration` that is enforced by the P-Chain. It is expected that L1s who choose to enforce a `MinStakeDuration` will lock the validator's Stake for the L1's desired `MinStakeDuration`.

#### `IncreaseL1ValidatorBalanceTx`

L1 validators are required to maintain a non-zero balance used to pay the continuous fee on the P-Chain in order to be considered active. The `IncreaseL1ValidatorBalanceTx` can be used by anybody to add additional $AVAX to the `Balance` to a validator. The specification of this transaction is:

```go
type IncreaseL1ValidatorBalanceTx struct {
    // Metadata, inputs and outputs
    BaseTx
    // ID corresponding to the validator
    ValidationID ids.ID `json:"validationID"`
    // Balance &lt;= sum($AVAX inputs) - sum($AVAX outputs) - TxFee
    Balance uint64 `json:"balance"`
}
```

If the validator corresponding to `ValidationID` is currently inactive (`Balance` was exhausted or `DisableL1ValidatorTx` was issued), this transaction will move them back to the active validator set.

Note: The $AVAX added to `Balance` can be claimed at any time by the validator using `DisableL1ValidatorTx`.

### Bootstrapping L1 Nodes

Bootstrapping a node/validator is the process of securely recreating the latest state of the blockchain locally. At the end of this process, the local state of a node/validator must be in sync with the local state of other virtuous nodes/validators. The node/validator can then verify new incoming transactions and reach consensus with other nodes/validators.

To bootstrap a node/validator, a few critical questions must be answered: How does one discover peers in the network? How does one determine that a discovered peer is honestly participating in the network?

For standalone networks like the Avalanche Primary Network, this is done by connecting to a hardcoded [set](https://github.com/ava-labs/avalanchego/blob/master/genesis/bootstrappers.json) of trusted bootstrappers to then discover new peers. Ethereum calls their set [bootnodes](https://ethereum.org/developers/docs/nodes-and-clients/bootnodes).

Since L1 validators are not required to be Primary Network validators, a list of validator IPs to connect to (the functional bootstrappers of the L1) cannot be provided by simply connecting to the Primary Network validators. However, the Primary Network can enable nodes tracking an L1 to seamlessly connect to the validators by tracking and gossiping L1 validator IPs. L1s will not need to operate and maintain a set of bootstrappers and can rely on the Primary Network for peer discovery.

### Sidebar: L1 Sovereignty

After this ACP is activated, the P-Chain will no longer support staking of any assets other than $AVAX for the Primary Network. The P-Chain will not support the distribution of staking rewards for L1s. All staking-related operations for L1 validation must be managed by the L1's validator manager. The P-Chain simply requires a continuous fee per validator. If an L1 would like to manage their validator's balances on the P-Chain, it can cover the cost for all L1 validators by posting the $AVAX balance on the P-Chain. L1s can implement any mechanism they want to pay the continuous fee charged by the P-Chain for its participants.

The L1 has full ownership over its validator set, not the P-Chain. There are no restrictions on what requirements an L1 can have for validators to join. Any stake that is required to join the L1's validator set is not locked on the P-Chain. If a validator is removed from the L1's validator set via a `SetL1ValidatorWeightTx` with weight `0`, the stake will continue to be locked outside of the P-Chain. How each L1 handles stake associated with the validator is entirely left up to the L1 and can be treated independently to what happens on the P-Chain.

The relationship between the P-Chain and L1s provides a dynamic where L1s can use the P-Chain as an impartial judge to modify parameters (in addition to its existing role of helping to validate incoming Avalanche Warp Messages). If a validator is misbehaving, the L1 validators can collectively generate a BLS multisig to reduce the voting weight of a misbehaving validator. This operation is fully secured by the Avalanche Primary Network (225M $AVAX or $8.325B at the time of writing).

Follow-up ACPs could extend the P-Chain &lt;-&gt; L1 relationship to include parametrization of the 67% threshold to enable L1s to choose a different threshold based on their security model (e.g. a simple majority of 51%).

### Continuous Fee Mechanism

Every additional validator on the P-Chain adds persistent load to the Avalanche Network. When a validator transaction is issued on the P-Chain, it is charged for the computational cost of the transaction itself but is not charged for the cost of an active validator over the time they are validating on the network (which may be indefinitely). This is a common problem in blockchains, spawning many state rent proposals in the broader blockchain space to address it. The following fee mechanism takes advantage of the fact that each L1 validator uses the same amount of computation and charges each L1 validator the dynamic base fee for every discrete unit of time it is active.

To charge each L1 validator, the notion of a `Balance` is introduced. The `Balance` of a validator will be continuously charged during the time they are active to cover the cost of storing the associated validator properties (BLS key, weight, nonce) in memory and to track IPs (in addition to other services provided by the Primary Network). This `Balance` is initialized with the `RegisterL1ValidatorTx` that added them to the active validator set. `Balance` can be increased at any time using the `IncreaseL1ValidatorBalanceTx`. When this `Balance` reaches `0`, the validator will be considered "inactive" and will no longer participate in validating the L1. Inactive validators can be moved back to the active validator set at any time using the same `IncreaseL1ValidatorBalanceTx`. Once a validator is considered inactive, the P-Chain will remove these properties from memory and only retain them on disk. All messages from that validator will be considered invalid until it is revived using the `IncreaseL1ValidatorBalanceTx`. L1s can reduce the amount of inactive weight by removing inactive validators with the `SetL1ValidatorWeightTx` (`Weight` = 0).

Since each L1 validator is charged the same amount at each point in time, tracking the fees for the entire validator set is straight-forward. The accumulated dynamic base fee for the entire network is tracked in a single uint. This accumulated value should be equal to the fee charged if a validator was active from the time the accumulator was instantiated. The validator set is maintained in a priority queue. A pseudocode implementation of the continuous fee mechanism is provided below.

```python
# Pseudocode
class ValidatorQueue:
    def __init__(self, fee_getter):
        self.acc = 0
        self.queue = PriorityQueue()
        self.fee_getter = fee_getter

    # At each time period, increment the accumulator and
    # pop all validators from the top of the queue that
    # ran out of funds.

    # Note: The amount of work done in a single block
    # should be bounded to prevent a large number of
    # validator operations from happening at the same
    # time.
    def time_elapse(self, t):
        self.acc = self.acc + self.fee_getter(t)
        while True:
            vdr = self.queue.peek()
            if vdr.balance < self.acc:
                self.queue.pop()
                continue
            return

    # Validator was added
    def validator_enter(self, vdr):
        vdr.balance = vdr.balance + self.acc
        self.queue.add(vdr)

    # Validator was removed
    def validator_remove(self, vdrNodeID):
        vdr = find_and_remove(self.queue, vdrNodeID)
        vdr.balance = vdr.balance - self.acc
        vdr.refund() # Refund [vdr.balance] to [RemainingBalanceOwner]
        self.queue.remove()

    # Validator's balance was topped up
    def validator_increase(self, vdrNodeID, balance):
        vdr = find_and_remove(self.queue, vdrNodeID)
        vdr.balance = vdr.balance + balance
        self.queue.add(vdr)
```

#### Fee Algorithm

[ACP-103](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/103-dynamic-fees/README.md) proposes a dynamic fee mechanism for transactions on the P-Chain. This mechanism is repurposed with minor modifications for the active L1 validator continuous fee.

At activation, the number of excess active L1 validators $x$ is set to `0`.

The fee rate per second for an active L1 validator is:

$$M \cdot \exp\left(\frac{x}{K}\right)$$

Where:

- $M$ is the minimum price for an active L1 validator
- $\exp\left(x\right)$ is an approximation of $e^x$ following the EIP-4844 specification

  ```python
  # Approximates factor * e ** (numerator / denominator) using Taylor expansion
  def fake_exponential(factor: int, numerator: int, denominator: int) -> int:
    i = 1
    output = 0
    numerator_accum = factor * denominator
    while numerator_accum > 0:
        output += numerator_accum
        numerator_accum = (numerator_accum * numerator) // (denominator * i)
        i += 1
    return output // denominator
  ```

- $K$ is a constant to control the rate of change for the L1 validator price

After every second, $x$ will be updated:

$$x = \max(x + (V - T), 0)$$

Where:

- $V$ is the number of active L1 validators
- $T$ is the target number of active L1 validators

Whenever $x$ increases by $K$, the price per active L1 validator increases by a factor of `~2.7`. If the price per active L1 validator gets too expensive, some active L1 validators will exit the active validator set, decreasing $x$, dropping the price. The price per active L1 validator constantly adjusts to make sure that, on average, the P-Chain has no more than $T$ active L1 validators.

#### Block Processing

Before processing the transactions inside a block, all validators that no longer have a sufficient (non-zero) balance are deactivated.

After processing the transactions inside a block, all validators that do not have a sufficient balance for the next second are deactivated.

##### Block Timestamp Validity Change

To ensure that validators are charged accurately, blocks are only considered valid if advancing the chain times would not cause a validator to have a negative balance.

This upholds the expectation that the number of L1 validators remains constant between blocks.

The block building protocol is modified to account for this change by first checking if the wall clock time removes any validator due to a lack of funds. If the wall clock time does not remove any L1 validators, the wall clock time is used to build the block. If it does, the time at which the first validator gets removed is used.

##### Fee Calculation

The total validator fee assessed in $\Delta t$ is:

```python
# Calculate the fee to charge over Δt
def cost_over_time(V:int, T:int, x:int, Δt: int) -> int:
    cost = 0
    for _ in range(Δt):
        x = max(x + V - T, 0)
        cost += fake_exponential(M, x, K)
    return cost
```

#### Parameters

The parameters at activation are:

| Parameter | Definition                                  | Value         |
| --------- | ------------------------------------------- | ------------- |
| $T$       | target number of validators                 | 10_000        |
| $C$       | capacity number of validators               | 20_000        |
| $M$       | minimum fee rate                            | 512 nAVAX/s   |
| $K$       | constant to control the rate of fee changes | 1_246_488_515 |

An $M$ of 512 nAVAX/s equates to ~1.33 AVAX/month to run an L1 validator, so long as the total number of continuous-fee-paying L1 validators stays at or below $T$.

$K$ was chosen to set the maximum fee doubling rate to ~24 hours. This is in the extreme case that the network has $C$ validators for prolonged periods of time; if the network has $T$+1 validators for example, the fee rate would double every ~27 years.

A future ACP can adjust the parameters to increase $T$, reduce $M$, and/or modify $K$.

#### User Experience

L1 validators are continuously charged a fee, albeit a small one. This poses a challenge for L1 validators: How do they maintain the balance over time?

Node clients should expose an API to track how much balance is remaining in the validator's account. This will provide a way for L1 validators to track how quickly it is going down and top-up when needed. A nice byproduct of the above design is the balance in the validator's account is claimable. This means users can top-up as much $AVAX as they want and rest-assured knowing they can always retrieve it if there is an excessive amount.

The expectation is that most users will not interact with node clients or track when or how much they need to top-up their validator account. Wallet providers will abstract away most of this process. For users who desire more convenience, L1-as-a-Service providers will abstract away all of this process.

## Backwards Compatibility

This new design for Subnets proposes a large rework to all L1-related mechanics. Rollout should be done on a going-forward basis to not cause any service disruption for live Subnets. All current Subnet validators will be able to continue validating both the Primary Network and whatever Subnets they are validating.

Any state execution changes must be coordinated through a mandatory upgrade. Implementors must take care to continue to verify the existing ruleset until the upgrade is activated. After activation, nodes should verify the new ruleset. Implementors must take care to only verify the presence of 2000 $AVAX prior to activation.

### Deactivated Transactions

- P-Chain

  - `TransformSubnetTx`

    After this ACP is activated, Elastic Subnets will be disabled. `TransformSubnetTx` will not be accepted post-activation. As there are no Mainnet Elastic Subnets, there should be no production impact with this deactivation.

### New Transactions

- P-Chain
  - `ConvertSubnetToL1Tx`
  - `RegisterL1ValidatorTx`
  - `SetL1ValidatorWeightTx`
  - `DisableL1ValidatorTx`
  - `IncreaseL1ValidatorBalanceTx`

## Reference Implementation

ACP-77 was implemented and will be merged into AvalancheGo behind the `Etna` upgrade flag. The full body of work can be found tagged with the `acp77` label [here](https://github.com/ava-labs/avalanchego/issues?q=sort%3Aupdated-desc+label%3Aacp77).

Since Etna is not yet activated, all new transactions introduced in ACP-77 will be rejected by AvalancheGo. If any modifications are made to ACP-77 as part of the ACP process, the implementation must be updated prior to activation.

## Security Considerations

This ACP introduces Avalanche Layer 1s, a new network type that costs significantly less than Avalanche Subnets. This can lead to a large increase in the number of networks and, by extension, the number of validators. Each additional validator adds consistent RAM usage to the P-Chain. However, this should be appropriately metered by the continuous fee mechanism outlined above.

With the sovereignty L1s have from the P-Chain, L1 staking tokens are not locked on the P-Chain. This poses a security consideration for L1 validators: Malicious chains can choose to remove validators at will and take any funds that the validator has locked on the L1. The P-Chain only provides the guarantee that L1 validators can retrieve the remaining $AVAX Balance for their validator via a `DisableL1ValidatorTx`. Any assets on the L1 is entirely under the purview of the L1. The onus is on L1 validators to vet the L1's security for any assets transferred onto the L1.

With a long window of expiry (24 hours) for the Warp message in `RegisterL1ValidatorTx`, spam of validator registration could lead to high memory pressure on the P-Chain. A future ACP can reduce the window of expiry if 24 hours proves to be a problem.

NodeIDs can be added to an L1's validator set involuntarily. However, it is important to note that any stake/rewards are _not_ at risk. For a node operator who was added to a validator set involuntarily, they would only need to generate a new NodeID via key rotation as there is no lock-up of any stake to create a NodeID. This is an explicit tradeoff for easier on-boarding of NodeIDs. This mirrors the Primary Network validators guarantee of no stake/rewards at risk.

The continuous fee mechanism outlined above does not apply to inactive L1 validators since they are not stored in memory. However, inactive L1 validators are persisted on disk which can lead to persistent P-Chain state growth. A future ACP can introduce a mechanism to decrease the rate of P-Chain state growth or provide a state expiry path to reduce the amount of P-Chain state.

## Acknowledgements

Special thanks to [@StephenButtolph](https://github.com/StephenButtolph), [@aaronbuchwald](https://github.com/aaronbuchwald), and [@patrick-ogrady](https://github.com/patrick-ogrady) for their feedback on these ideas. Thank you to the broader Ava Labs Platform Engineering Group for their feedback on this ACP prior to publication.

## Copyright

Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

# ACP-83: Dynamic Multidimensional Fees (/docs/acps/83-dynamic-multidimensional-fees)

---
title: "ACP-83: Dynamic Multidimensional Fees"
description: "Details for Avalanche Community Proposal 83: Dynamic Multidimensional Fees"
edit_url: https://github.com/avalanche-foundation/ACPs/edit/main/ACPs/83-dynamic-multidimensional-fees/README.md
---

| ACP | 83 |
| :--- | :--- |
| **Title** | Dynamic multidimensional fees for P-chain and X-chain |
| **Author(s)** | Alberto Benegiamo ([@abi87](https://github.com/abi87)) |
| **Status** | Stale |
| **Track** | Standards |
| **Superseded-By** | [ACP-103](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/103-dynamic-fees/README.md) |

## Abstract

Introduce a dynamic and multidimensional fees scheme for the P-chain and X-chain.

Dynamic fees helps to preserve the stability of the chain as it provides a feedback mechanism that increases the cost of resources when the network operates above its target utilization.

Multidimensional fees ensures that high demand for orthogonal resources does not drive up the price of underutilized resources. For example, networks provide and consume orthogonal resources including, but not limited to, bandwidth, chain state, read/write throughput, and CPU. By independently metering each resource, they can be granularly priced and stay closer to optimal resource utilization.

## Motivation

The P-Chain and X-Chain currently have fixed fees and in some cases those fees are fixed to zero.

This makes transaction issuance predictable, but does not provide feedback mechanism to preserve chain stability under high load. In contrast, the C-Chain, which has the highest and most regular load among the chains on the Primary Network, already supports dynamic fees. This ACP proposes to introduce a similar dynamic fee mechanism for the P-Chain and X-Chain to further improve the Primary Network's stability and resilience under load.

However, unlike the C-Chain, we propose a multidimensional fee scheme with an exponential update rule for each fee dimension. The [HyperSDK](https://github.com/ava-labs/hypersdk) already utilizes a multidimensional fee scheme with optional priority fees and its efficiency is backed by [academic research](https://arxiv.org/abs/2208.07919).

Finally, we split the fee into two parts: a `base fee` and a `priority fee`. The `base fee` is calculated by the network each block to accurately price each resource at a given point in time. Whatever amount greater than the base fee is burnt is treated as the `priority fee` to prioritize faster transaction inclusion.

## Specification

We introduce the multidimensional scheme first and then how to apply the dynamic fee update rule for each fee dimension. Finally we list the new block verification rules, valid once the new fee scheme activates.

### Multidimensional scheme components

We define four fee dimensions, `Bandwidth`, `Reads`, `Writes`, `Compute`, to describe transactions complexity. In more details:

- `Bandwidth` measures the transaction size in bytes, as encoded by the AvalancheGo codec. Byte length is a proxy for the network resources needed to disseminate the transaction.
- `Reads` measures the number of DB reads needed to verify the transactions. DB reads include UTXOs reads and any other state quantity relevant for the specific transaction.
- `Writes` measures the number of DB writes following the transaction verification. DB writes include UTXOs generated as outputs of the transactions and any other state quantity relevant for the specific transaction.
- `Compute` measures the number of signatures to be verified, including UTXOs ones and those related to authorization of specific operations.

For each fee dimension $i$, we define:

- *fee rate* $r_i$ as the price, denominated in AVAX, to be paid for a transaction with complexity $u_i$ along the fee dimension $i$.
- *base fee* as the minimal fee needed to accept a transaction. Base fee is given be the formula
$$base \  fee = \sum_{i=0}^3 r_i \times u_i$$
- *priority fee* as an optional fee paid on top of the base fee to speed up the transaction inclusion in a block.

### Dynamic scheme components

Fee rates are updated in time, to allow a fee increase when network is getting congested. Each new block is a potential source of congestion, as its transactions carry complexity that each validator must process to verify and eventually accept the block. The more complexity carries a block, and the more rapidly blocks are produced, the higher the congestion.  

We seek a scheme that rapidly increases the fees when blocks complexity goes above a defined threshold and that equally rapidly decreases the fees once complexity goes down (because blocks carry less/simpler transactions, or because they are produced more slowly). We define the desired threshold as a *target complexity rate* $T$: we would want to process every second a block whose complexity is $T$. Any complexity more than that causes some congestion that we want to penalize via fees.

In order to update fees rates we track, per each block and each fee dimension, a parameter called cumulative excess complexity. Fee rates applied to a block will be defined in terms of cumulative excess complexity as we show in the following.

Suppose that a block $B_t$ is the current chain tip. $B_t$ has the following features:

- $t$ is its timestamp.
- $\Delta C_t$ is the cumulative excess complexity along fee dimension $i$.

Say a new block $B_{t + \Delta T}$ is built on top of $B$, with the following features:

- $t + \Delta T$ is its timestamp
- $C_{t + \Delta T}$ is its complexity along fee dimension $i$.

Then the fee rate $r_{t + \Delta T}$ applied for the block $B_{t + \Delta T}$ along dimension $i$ will be:

$$ r_{t + \Delta T} = r^{min} \times e^{\frac{max(0, \Delta C_t - T \times \Delta T)}{Denom}} $$

where

- $r^{min}$ is the minimal fee rate along fee dimension $i$
- $T$ is the target complexity rate along fee dimension $i$
- $Denom$ is a normalization constant for the fee dimension $i$

Moreover, once the block $B_{t + \Delta T}$ is accepted, the cumulative excess complexity is updated as follows:

$$\Delta C_{t + \Delta T} = max\large(0, \Delta C_{t} - T \times \Delta T\large) + C_{t + \Delta T}$$

The fee rate update formula guarantees that fee rates increase if incoming blocks are complex (large $C_{t + \Delta T}$) and if blocks are emitted rapidly (small $\Delta T$). Symmetrically, fee rates decrease to the minimum if incoming blocks are less complex and if blocks are produced less frequently.  
The update formula has a few paramenters to be tuned, independently, for each fee dimension. We defer discussion about tuning to the [implementation section](#tuning-the-update-formula).

## Block verification rules

Upon activation of the dynamic multidimensional fees scheme we modify block processing as follows:

- **Bound block complexity**. For each fee dimension $i$, we define a *maximal block complexity* $Max$. A block is only valid if the block complexity $C$ is less than the maximum block complexity: $C \leq Max$.
- **Verify transaction fee**. When verifying each transaction in a block, we confirm that it can cover its own base fee. Note that both base fee and optional priority fees are burned.

## User Experience

### How will the wallets estimate the fees?

AvalancheGo nodes will provide new APIs exposing the current and expected fee rates, as they are likely to change block by block. Wallets can then use the fees rates to select UTXOs to pay the transaction fees. Moreover, the AvalancheGo implementation proposed above offers a `fees.Calculator` struct that can be reused by wallets and downstream projects to evaluate calculate fees.

### How will wallets be able to re-issue Txs at a higher fee?

Wallets should be able to simply re-issue the transaction since current AvalancheGo implementation drops mempool transactions whose fee rate is lower than current one. More specifically, a transaction may be valid the moment it enters the mempool and it won’t be re-verified as long as it stays in there. However, as soon as the transaction is selected to be included in the next block, it is re-verified against the latest preferred tip. If fees are not enough by this time, the transaction is dropped and the wallet can simply re-issue it at a higher fee, or wait for the fee rate to go down. Note that priority fees offer some buffer space against an increase in the fee rate. A transaction paying just the base fee will be evicted from the mempool in the face of a fee rate increase, while a transaction paying some extra priority fee may have enough buffer room to stay valid after some amount of fee increase.

### How does priority fees guarantee a faster block inclusion?

AvalancheGo mempool will be restructured to order transactions by priority fees. Transactions paying priority fees will be selected for block inclusion first, without violating any spend dependency.

## Backwards Compatibility

Modifying the fee scheme for P-Chain and X-Chain requires a mandatory upgrade for activation. Moreover, wallets must be modified to properly handle the new fee scheme once activated.

## Reference Implementation

The implementation is split across multiple PRs:

- P-Chain work is tracked in this issue: [https://github.com/ava-labs/avalanchego/issues/2707](https://github.com/ava-labs/avalanchego/issues/2707)
- X-Chain work is tracked in this issue: [https://github.com/ava-labs/avalanchego/issues/2708](https://github.com/ava-labs/avalanchego/issues/2708)

A very important implementation step is tuning the update formula parameters for each chain and each fee dimension. We show here the principles we followed for tuning and a simulation based on historical data.

### Tuning the update formula

The basic idea is to measure the complexity of blocks already accepted and derive the parameters from it. You can find the historical data in [this repo](https://github.com/abi87/complexities).  
To simplify the exposition I am purposefully ignoring chain specifics (like P-chain proposal blocks). We can account for chain specifics while processing the historical data. Here are the principles:

- **Target block complexity rate $T$**: calculate the distribution of block complexity and pick a high enough quantile.
- **Max block complexity $Max$**: this is probably the trickiest parameter to set.
Historically we had [pretty big transactions](https://subnets.avax.network/p-chain/tx/27pjHPRCvd3zaoQUYMesqtkVfZ188uP93zetNSqk3kSH1WjED1) (more than $1.000$ referenced utxos). Setting a max block complexity so high that these big transactions are allowed is akin to setting no complexity cap.
On the other side, we still want to allow, even encourage, UTXO consolidation, so we may want to allow transactions [like this](https://subnets.avax.network/p-chain/tx/2LxyHzbi2AGJ4GAcHXth6pj5DwVLWeVmog2SAfh4WrqSBdENhV).
A principled way to set max block complexity may be the following:
  - calculate the target block complexity rate (see previous point)
  - calculate the median time elapsed among consecutive blocks
  - The product of these two quantities should gives us something like a target block complexity.
  - Set the max block complexity to say $\times 50$ the target value.
- **Normalization coefficient $Denom$**: I suggest we size it as follows:
  - Find the largest historical peak, i.e. the sequence of consecutive blocks which contained the most complexity in the shortest period of time
  - Tune  $Denom$ so that it would cause a $\times 10000$ increase in the fee rate for such a peak. This increase would push fees from the milliAVAX we normally pay under stable network condition up to tens of AVAX.
- **Minimal fee rates $r^{min}$**: we could size them so that transactions fees do not change very much with respect to the currently fixed values.

We simulate below how the update formula would behave on an peak period from Avalanche mainnet.

<p align="center">
  <img src="https://raw.githubusercontent.com/avalanche-foundation/ACPs/main/ACPs/83-dynamic-multidimensional-fees/complexities.png" /> />
  <img src="https://raw.githubusercontent.com/avalanche-foundation/ACPs/main/ACPs/83-dynamic-multidimensional-fees/fee.png" /> />
</p>

Figure 1 shows a peak period, starting with block [wqKJcvEv86TBpmJY2pAY7X65hzqJr3VnHriGh4oiAktWx5qT1](https://subnets.avax.network/p-chain/block/wqKJcvEv86TBpmJY2pAY7X65hzqJr3VnHriGh4oiAktWx5qT1) and going for roughly 30 blocks. We only show `Bandwidth` for clarity, but other fees dimensions have similar behaviour.
The network load is much larger than target and sustained.  
Figure 2 show the fee dynamic in response to the peak: fees scale up from a few milliAVAX up to around 25 AVAX. Moreover as soon as the peak is over, and complexity goes back to the target value, fees are reduced very rapidly.

## Security Considerations

The new fee scheme is expected to help network stability as it offers economic incentives to users to hold transactions issuance in times of high load. While fees are expected to remain generally low when the system is not loaded, a sudden load increase, with fuller blocks, would push the dynamic fees algo to increase fee rates. The increase is expected to continue until the load is reduced. Load reduction happens by both dropping unconfirmed transactions whose fee-rate is not sufficient anymore and by pushing users that optimize their transactions costs to delay transaction issuance until the fee rate goes down to an acceptable level.  
Note finally that the exponential fee update mechanism detailed above is [proven](https://ethresear.ch/t/multidimensional-eip-1559/11651) to be robust against strategic behaviors of users delaying transactions issuance and then suddenly push a bulk of transactions once the fee rate is low enough.

## Acknowledgements

Thanks to @StephenButtolph @patrick-ogrady and @dhrubabasu for their feedback on these ideas.

## Copyright

Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

# ACP-84: Table Preamble (/docs/acps/84-table-preamble)

---
title: "ACP-84: Table Preamble"
description: "Details for Avalanche Community Proposal 84: Table Preamble"
edit_url: https://github.com/avalanche-foundation/ACPs/edit/main/ACPs/84-table-preamble/README.md
---

| ACP | 84 |
| :--- | :--- |
| **Title** | Table Preamble for ACPs |
| **Author(s)** | Gauthier Leonard ([@Nuttymoon](https://github.com/Nuttymoon)) |
| **Status** | Activated |
| **Track** | Meta |

## Abstract

The current ACP template features a plain-text code block containing "RFC 822 style headers" as `Preamble` (see [What belongs in a successful ACP?](https://github.com/avalanche-foundation/ACPs?tab=readme-ov-file#what-belongs-in-a-successful-acp)). This header includes multiple links to discussions, authors, and other ACPs.

This ACP proposes to replace the `Preamble` code block with a Markdown table format (similar to what is used in [Ethereum EIPs](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-1.md)).

## Motivation

The current ACPs `Preamble` is (i) not very readable and (ii) not user-friendly as links are not clickable. The proposed table format aims to fix these issues.

## Specification

The following Markdown table format is proposed:

| ACP                            | PR Number                                                                                                                                           |
| :----------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Title**                      | ACP title                                                                                                                                           |
| **Author(s)**                  | A list of the author's name(s) and optionally contact info: FirstName LastName ([@GitHubUsername](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/84-table-preamble/README.md) or [email@address.com](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/84-table-preamble/README.md)) |
| **Status**                     | Proposed, Implementable, Activated, Stale ([Discussion](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/84-table-preamble/README.md))                                                                               |
| **Track**                      | Standards, Best Practices, Meta, Subnet                                                                                                             |
| **Replaces (\\*optional)**      | [ACP-XX](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/84-table-preamble/README.md)                                                                                                                               |
| **Superseded-By (\\*optional)** | [ACP-XX](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/84-table-preamble/README.md)                                                                                                                               |

It features all the existing fields of the current ACP template, and would replace the current `Preamble` code block in [ACPs/TEMPLATE.md](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/TEMPLATE.md).

## Backwards Compatibility

Existing ACPs could be updated to use the new table format, but it is not mandatory.

## Reference Implementation

For this ACP, the table would look like this:

| ACP           | 84                                                                                   |
| :------------ | :----------------------------------------------------------------------------------- |
| **Title**     | Table Preamble for ACPs                                                              |
| **Author(s)** | Gauthier Leonard ([@Nuttymoon](https://github.com/Nuttymoon))                        |
| **Status**    | Proposed ([Discussion](https://github.com/avalanche-foundation/ACPs/discussions/86)) |
| **Track**     | Meta                                                                                 |

## Security Considerations

NA

## Open Questions

NA

## Copyright

Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

# ACP-99: Validatorsetmanager Contract (/docs/acps/99-validatorsetmanager-contract)

---
title: "ACP-99: Validatorsetmanager Contract"
description: "Details for Avalanche Community Proposal 99: Validatorsetmanager Contract"
edit_url: https://github.com/avalanche-foundation/ACPs/edit/main/ACPs/99-validatorsetmanager-contract/README.md
---

| ACP          | 99                                                                                                                          |
| :----------- | :-------------------------------------------------------------------------------------------------------------------------- |
| Title        | Validator Manager Solidity Standard                                                                                         |
| Author(s)    | Gauthier Leonard ([@Nuttymoon](https://github.com/Nuttymoon)), Cam Schultz ([@cam-schultz](https://github.com/cam-schultz)) |
| Status       | Proposed ([Discussion](https://github.com/avalanche-foundation/ACPs/discussions/165))                                       |
| Track        | Best Practices                                                                                                              |
| Dependencies | [ACP-77](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/77-reinventing-subnets/README.md)                                                                               |

## Abstract

Define a standard Validator Manager Solidity smart contract to be deployed on any Avalanche EVM chain.

This ACP relies on concepts introduced in [ACP-77 (Reinventing Subnets)](https://github.com/avalanche-foundation/ACPs/tree/main/ACPs/77-reinventing-subnets). It depends on it to be marked as `Implementable`.

## Motivation

[ACP-77 (Reinventing Subnets)](https://github.com/avalanche-foundation/ACPs/tree/main/ACPs/77-reinventing-subnets) opens the door to managing an L1 validator set (stored on the P-Chain) from any chain on the Avalanche Network. The P-Chain allows a Subnet to specify a "validator manager" if it is converted to an L1 using `ConvertSubnetToL1Tx`. This `(blockchainID, address)` pair is responsible for sending ICM messages contained within `RegisterL1ValidatorTx` and `SetL1ValidatorWeightTx` on the P-Chain. This enables an on-chain program to add, modify the weight of, and remove validators.

On each validator set change, the P-Chain is willing to sign an `AddressedCall` to notify any on-chain program tracking the validator set. On-chain programs must be able to interpret this message, so they can trigger the appropriate action. The 2 kinds of `AddressedCall`s [defined in ACP-77](https://github.com/avalanche-foundation/ACPs/tree/main/ACPs/77-reinventing-subnets#p-chain-warp-message-payloads) are `L1ValidatorRegistrationMessage` and `L1ValidatorWeightMessage`.

Given these assumptions and the fact that most of the active blockchains on Avalanche Mainnet are EVM-based, we propose `ACP99Manager` as the standard Solidity contract specification that can:

1. Hold relevant information about the current L1 validator set
2. Send validator set updates to the P-Chain by generating `AdressedCall`s defined in ACP-77
3. Correctly update the validator set by interpreting notification messages received from the P-Chain
4. Be easily integrated into validator manager implementations that utilize various security models (e.g. Proof-of-Stake).

Having an audited and open-source reference implementation freely available will contribute to lowering the cost of launching L1s on Avalanche.

Once deployed, the `ACP99Manager` implementation contract can be used as the `Address` in the [`ConvertSubnetToL1Tx`](https://github.com/avalanche-foundation/ACPs/tree/main/ACPs/77-reinventing-subnets#convertsubnettol1tx).

## Specification

> **Note:**: The naming convention followed for the interfaces and contracts are inspired from the way [OpenZeppelin Contracts](https://docs.openzeppelin.com/contracts/5.x/) are named after ERC standards, using `ACP` instead of `ERC`.

### Type Definitions

The following type definitions are used in the function signatures described in [Contract Specification](#contract-specification)

```solidity
/**
 * @notice Description of the conversion data used to convert
 * a subnet to an L1 on the P-Chain.
 * This data is the pre-image of a hash that is authenticated by the P-Chain
 * and verified by the Validator Manager.
 */
struct ConversionData {
    bytes32 subnetID;
    bytes32 validatorManagerBlockchainID;
    address validatorManagerAddress;
    InitialValidator[] initialValidators;
}

/// @notice Specifies an initial validator, used in the conversion data.
struct InitialValidator {
    bytes nodeID;
    bytes blsPublicKey;
    uint64 weight;
}

/// @notice L1 validator status.
enum ValidatorStatus {
    Unknown,
    PendingAdded,
    Active,
    PendingRemoved,
    Completed,
    Invalidated
}

/**
 * @notice Specifies the owner of a validator's remaining balance or disable owner on the P-Chain.
 * P-Chain addresses are also 20-bytes, so we use the address type to represent them.
 */
struct PChainOwner {
    uint32 threshold;
    address[] addresses;
}

/**
 * @notice Contains the active state of a Validator.
 * @param status The validator status.
 * @param nodeID The NodeID of the validator.
 * @param startingWeight The weight of the validator at the time of registration.
 * @param sentNonce The current weight update nonce sent by the manager.
 * @param receivedNonce The highest nonce received from the P-Chain.
 * @param weight The current weight of the validator.
 * @param startTime The start time of the validator.
 * @param endTime The end time of the validator.
 */
struct Validator {
    ValidatorStatus status;
    bytes nodeID;
    uint64 startingWeight;
    uint64 sentNonce;
    uint64 receivedNonce;
    uint64 weight;
    uint64 startTime;
    uint64 endTime;
}
```

#### About `Validator`s

A `Validator` represents the continuous time frame during which a node is part of the validator set.

Each `Validator` is identified by its `validationID`. If a validator was added as part of the initial set of continuous dynamic fee paying validators, its `validationID` is the SHA256 hash of the 36 bytes resulting from concatenating the 32 byte `ConvertSubnetToL1Tx` transaction ID and the 4 byte index of the initial validator within the transaction. If a validator was added to the L1's validator set post-conversion, its `validationID` is the SHA256 of the payload of the `AddressedCall` in the `RegisterL1ValidatorTx` used to add it, as defined in ACP-77.

### Contract Specification

The standard `ACP99Manager` functionality is defined by a set of events, public methods, and private methods that must be included by a compliant implementation.

For a full implementation, please see the [Reference Implementation](#reference-implementation)

#### Events

```solidity
/**
 * @notice Emitted when an initial validator is registered.
 * @notice The field index is the index of the initial validator in the conversion data.
 * This is used along with the subnetID as the ACP-118 justification in
 * signature requests to P-Chain validators over a L1ValidatorRegistrationMessage
 * when removing the validator
 */
event RegisteredInitialValidator(
    bytes32 indexed validationID,
    bytes20 indexed nodeID,
    bytes32 indexed subnetID,
    uint64 weight,
    uint32 index
);
/// @notice Emitted when a validator registration to the L1 is initiated.
event InitiatedValidatorRegistration(
    bytes32 indexed validationID,
    bytes20 indexed nodeID,
    bytes32 registrationMessageID,
    uint64 registrationExpiry,
    uint64 weight
);
/// @notice Emitted when a validator registration to the L1 is completed.
event CompletedValidatorRegistration(bytes32 indexed validationID, uint64 weight);
/// @notice Emitted when removal of an L1 validator is initiated.
event InitiatedValidatorRemoval(
    bytes32 indexed validationID,
    bytes32 validatorWeightMessageID,
    uint64 weight,
    uint64 endTime
);
/// @notice Emitted when removal of an L1 validator is completed.
event CompletedValidatorRemoval(bytes32 indexed validationID);
/// @notice Emitted when a validator weight update is initiated.
event InitiatedValidatorWeightUpdate(
    bytes32 indexed validationID, uint64 nonce, bytes32 weightUpdateMessageID, uint64 weight
);
/// @notice Emitted when a validator weight update is completed.
event CompletedValidatorWeightUpdate(bytes32 indexed validationID, uint64 nonce, uint64 weight);
```

#### Public Methods

```solidity
/// @notice Returns the SubnetID of the L1 tied to this manager
    function subnetID() public view returns (bytes32 id);

/// @notice Returns the validator details for a given validation ID.
function getValidator(bytes32 validationID)
    public
    view
    returns (Validator memory validator);

/// @notice Returns the total weight of the current L1 validator set.
function l1TotalWeight() public view returns (uint64 weight);

/**
 * @notice Verifies and sets the initial validator set for the chain by consuming a
 * SubnetToL1ConversionMessage from the P-Chain.
 *
 * Emits a {RegisteredInitialValidator} event for each initial validator in {conversionData}.
 *
 * @param conversionData The Subnet conversion message data used to recompute and verify against the ConversionID.
 * @param messsageIndex The index that contains the SubnetToL1ConversionMessage ICM message containing the
 * ConversionID to be verified against the provided {conversionData}.
 */
function initializeValidatorSet(
    ConversionData calldata conversionData,
    uint32 messsageIndex
) public;

/**
 * @notice Completes the validator registration process by returning an acknowledgement of the registration of a
 * validationID from the P-Chain. The validator should not be considered active until this method is successfully called.
 *
 * Emits a {CompletedValidatorRegistration} event on success.
 *
 * @param messageIndex The index of the L1ValidatorRegistrationMessage to be received providing the acknowledgement.
 * @return validationID The ID of the registered validator.
 */
function completeValidatorRegistration(uint32 messageIndex)
    public
    returns (bytes32 validationID);

/**
 * @notice Completes validator removal by consuming an RegisterL1ValidatorMessage from the P-Chain acknowledging
 * that the validator has been removed.
 *
 * Emits a {CompletedValidatorRemoval} on success.
 *
 * @param messageIndex The index of the RegisterL1ValidatorMessage.
 */
function completeValidatorRemoval(uint32 messageIndex)
    public
    returns (bytes32 validationID);

/**
 * @notice Completes the validator weight update process by consuming an L1ValidatorWeightMessage from the P-Chain
 * acknowledging the weight update. The validator weight change should not have any effect until this method is successfully called.
 *
 * Emits a {CompletedValidatorWeightUpdate} event on success.
 *
 * @param messageIndex The index of the L1ValidatorWeightMessage message to be received providing the acknowledgement.
 * @return validationID The ID of the validator, retreived from the L1ValidatorWeightMessage.
 * @return nonce The nonce of the validator, retreived from the L1ValidatorWeightMessage.
 */
function completeValidatorWeightUpdate(uint32 messageIndex)
    public
    returns (bytes32 validationID, uint64 nonce);
```

>Note: While `getValidator` provides a way to fetch a `Validator` based on its `validationID`, no method that returns all active validators is specified. This is because a `mapping` is a reasonable way to store active validators internally, and Solidity `mapping`s are not iterable. This can be worked around by storing additional indexing metadata in the contract, but not all applications may wish to incur that added complexity.

#### Private Methods

The following methods are specified as `internal` to account for different semantics of initiating validator set changes, such as checking uptime attested to via ICM message, or transferring funds to be locked as stake. Rather than broaden the definitions of these functions to cover all use cases, we leave it to the implementer to define a suitable external interface and call the appropriate `ACP99Manager` function internally.

```solidity
/**
 * @notice Initiates validator registration by issuing a RegisterL1ValidatorMessage. The validator should
 * not be considered active until completeValidatorRegistration is called.
 *
 * Emits an {InitiatedValidatorRegistration} event on success.
 *
 * @param nodeID The ID of the node to add to the L1.
 * @param blsPublicKey The BLS public key of the validator.
 * @param remainingBalanceOwner The remaining balance owner of the validator.
 * @param disableOwner The disable owner of the validator.
 * @param weight The weight of the node on the L1.
 * @return validationID The ID of the registered validator.
 */
function _initiateValidatorRegistration(
    bytes memory nodeID,
    bytes memory blsPublicKey,
    PChainOwner memory remainingBalanceOwner,
    PChainOwner memory disableOwner,
    uint64 weight
) internal returns (bytes32 validationID);

/**
 * @notice Initiates validator removal by issuing a L1ValidatorWeightMessage with the weight set to zero.
 * The validator should be considered inactive as soon as this function is called.
 *
 * Emits an {InitiatedValidatorRemoval} on success.
 *
 * @param validationID The ID of the validator to remove.
 */
function _initiateValidatorRemoval(bytes32 validationID) internal;

/**
 * @notice Initiates a validator weight update by issuing an L1ValidatorWeightMessage with a nonzero weight.
 * The validator weight change should not have any effect until completeValidatorWeightUpdate is successfully called.
 *
 * Emits an {InitiatedValidatorWeightUpdate} event on success.
 *
 * @param validationID The ID of the validator to modify.
 * @param weight The new weight of the validator.
 * @return nonce The validator nonce associated with the weight change.
 * @return messageID The ID of the L1ValidatorWeightMessage used to update the validator's weight.
 */
function _initiateValidatorWeightUpdate(
    bytes32 validationID,
    uint64 weight
) internal returns (uint64 nonce, bytes32 messageID);
```

##### About `DisableL1ValidatorTx`

In addition to calling `_initiateValidatorRemoval`, a validator may be disabled by issuing a `DisableL1ValidatorTx` on the P-Chain. This transaction allows the `DisableOwner` of a validator to disable it directly from the P-Chain to claim the unspent `Balance` linked to the validator of a failed L1. Therefore it is not meant to be called in the `Manager` contract.

## Backwards Compatibility

`ACP99Manager` is a reference specification. As such, it doesn't have any impact on the current behavior of the Avalanche protocol.

## Reference Implementation

A reference implementation will be provided in Ava Labs' [ICM Contracts](https://github.com/ava-labs/icm-contracts/tree/main/contracts/validator-manager) repository. This reference implementation will need to be updated to conform to `ACP99Manager` before this ACP may be marked `Implementable`.

### Example Integrations

`ACP99Manager` is designed to be easily incorporated into any architecture. Two example integrations are included in this ACP, each of which uses a different architecture.

#### Multi-contract Design

The multi-contract design consists of a contract that implements `ACP99Manager`, and separate "security module" contracts that implement security models, such as PoS or PoA. Each `ACP99Manager` implementation contract is associated with one or more "security modules" that are the only contracts allowed to call the `ACP99Manager` functions that initiate validator set changes (`initiateValidatorRegistration`, and `initiateValidatorWeightUpdate`). Every time a validator is added/removed or a weight change is initiated, the `ACP99Manager` implementation will, in turn, call the corresponding function of the "security module" (`handleValidatorRegistration` or `handleValidatorWeightChange`). We recommend that the "security modules" reference an immutable `ACP99Manager` contract address for security reasons.

It is up to the "security module" to decide what action to take when a validator is added/removed or a weight change is confirmed by the P-Chain. Such actions could be starting the withdrawal period and allocating rewards in a PoS L1.

<Mermaid chart={`---
title: ACP-99 Multi-contract Architecture with a PoA Security Module
---
graph LR
  Safe(Safe multisig)
  SecurityModule(ACP99PoAModule)
  Manager(ACP99Manager)
  P(P-Chain)

  subgraph "Manager chain"
    Safe
    SecurityModule
    Manager
  end
  Safe -.->|Own| SecurityModule
  Safe -.->|Own| Manager
  SecurityModule <-.->|Reference| Manager
  Safe -->|addValidator| SecurityModule
  SecurityModule -->|initiateValidatorRegistration| Manager
  Manager -->|sendWarpMessage| P
  P -->|completeValidatorRegistration| Manager
  Manager -->|handleValidatorRegistration| SecurityModule`} />

"Security modules" could implement PoS, Liquid PoS, etc. The specification of such smart contracts is out of the scope of this ACP.

A work in progress implementation is available in the [Suzaku Contracts Library](https://github.com/suzaku-network/suzaku-contracts-library/blob/main/README.md#acp99-contracts-library) repository. It will be updated until this ACP is considered `Implementable` based on the outcome of the discussion.

Ava Labs' V2 Validator Manager also implements this architecture for a Proof-of-Stake security module, and is available in their [ICM Contracts Repository](https://github.com/ava-labs/icm-contracts/tree/validator-manager-v2.0.0/contracts/validator-manager/StakingManager.sol).

#### Single-contract Design

The single-contract design consists of a class hierarchy with the base class implementing `ACP99Manager`. The `PoAValidatorManager` child class in the below diagram may be swapped out for another class implementing a different security model, such as PoS.

<Mermaid chart={`---
title: ACP-99 Single-Contract Architecture implementing PoA
---
  classDiagram
  class ACP99Manager {
    initializeValidatorSet
    initiateValidatorRegistration
    completeValidatorRegistration
    initiateValidatorWeightUpdate
    completeValidatorWeightUpdate
  }
  <<abstract>> ACP99Manager

  class ValidatorManager {
    completeValidatorRegistration
  }
  <<abstract>> ValidatorManager
  class PoAValidatorManager {
    initiateValidatorRegistration
    initiateEndValidation
    completeEndValidation
  }

  ACP99Manager <|--ValidatorManager
  ValidatorManager <|-- PoAValidatorManager`} />

No reference implementation is provided for this architecture in particular, but Ava Labs' V1 [Validator Manager](https://github.com/ava-labs/icm-contracts/tree/validator-manager-v1.0.0/contracts/validator-manager) implements much of the functional behavior described by the specification. It predates the specification, however, so there are some deviations. It should at most be treated as a model of an approximate implementation of this standard.

## Security Considerations

The audit process of `ACP99Manager` and reference implementations is of the utmost importance for the future of the Avalanche ecosystem as most L1s would rely upon it to secure their L1.

## Open Questions

### Is there an interest to keep historical information about the validator set on the manager chain?

It is left to the implementor to decide if `getValidator` should return information about historical validators. Information about past validator performance may not be relevant for all applications (e.g. PoA has no need to know about past validator's uptimes). This information will still be available in archive nodes and offchain tools (e.g. explorers), but it is not enforced at the contract level.

### Should `ACP99Manager` include a churn control mechanism?

The Ava Labs [implementation](https://github.com/ava-labs/icm-contracts/blob/main/contracts/validator-manager/ValidatorManager.sol) of the `ValidatorManager` contract includes a churn control mechanism that prevents too much weight from being added or removed from the validator set in a short amount of time. Excessive churn can cause consensus failures, so it may be appropriate to require that churn tracking is implemented in some capacity.

## Acknowledgments

Special thanks to [@leopaul36](https://github.com/leopaul36), [@aaronbuchwald](https://github.com/aaronbuchwald), [@dhrubabasu](https://github.com/dhrubabasu), [@minghinmatthewlam](https://github.com/minghinmatthewlam) and [@michaelkaplan13](https://github.com/michaelkaplan13) for their reviews of previous versions of this ACP!

## Copyright

Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).

# Avalanche Community Proposals (ACPs) (/docs/acps)

---
title: "Avalanche Community Proposals (ACPs)"
description: "Official framework for proposing improvements and gathering consensus around changes to the Avalanche Network"
edit_url: https://github.com/avalanche-foundation/ACPs/edit/main/README.md
---

<div align="center">
  <img width="80%" src="https://raw.githubusercontent.com/avalanche-foundation/ACPs/main/LOGO.png" />>
</div>

## What is an Avalanche Community Proposal (ACP)?

An Avalanche Community Proposal is a concise document that introduces a change or best practice for adoption on the [Avalanche Network](https://www.avax.com). ACPs should provide clear technical specifications of any proposals and a compelling rationale for their adoption.

ACPs are an open framework for proposing improvements and gathering consensus around changes to the Avalanche Network. ACPs can be proposed by anyone and will be merged into this repository as long as they are well-formatted and coherent. Once an overwhelming majority of the Avalanche Network/Community have [signaled their support for an ACP](https://docs.avax.network/nodes/configure/avalanchego-config-flags#avalanche-community-proposals), it may be scheduled for activation on the Avalanche Network by Avalanche Network Clients (ANCs). It is ultimately up to members of the Avalanche Network/Community to adopt ACPs they support by running a compatible ANC, such as [AvalancheGo](https://github.com/ava-labs/avalanchego). 

## ACP Tracks

There are three kinds of ACP:

* A `Standards Track` ACP describes a change to the design or function of the Avalanche Network, such as a change to the P2P networking protocol, P-Chain design, Subnet architecture, or any change/addition that affects the interoperability of Avalanche Network Clients (ANCs).
* A `Best Practices Track` ACP describes a design pattern or common interface that should be used across the Avalanche Network to make it easier to integrate with Avalanche or for Subnets to interoperate with each other. This would include things like proposing a smart contract interface, not proposing a change to how smart contracts are executed.
* A `Meta Track` ACP describes a change to the ACP process or suggests a new way for the Avalanche Community to collaborate.
* A `Subnet Track` ACP describes a change to a particular Subnet. This would include things like configuration changes or coordinated Subnet upgrades.

## ACP Statuses

There are four statuses of an ACP:

* A `Proposed` ACP has been merged into the main branch of the ACP repository. It is actively being discussed by the Avalanche Community and may be modified based on feedback.
* An `Implementable` ACP is considered "ready for implementation" by the author(s) and will no longer change meaningfully from its current form (which would require a new ACP).
* An `Activated` ACP has been activated on the Avalanche Network via a coordinated upgrade by the Avalanche Community. Once an ACP is `Activated`, it is locked.
* A `Stale` ACP has been abandoned by its author(s) because it is not supported by the Avalanche Community or has been replaced with another ACP.

## ACP Workflow

### Step 0: Think of a Novel Improvement to Avalanche

The ACP process begins with a new idea for Avalanche. Each potential ACP must have an author(s): someone who writes the ACP using the style and format described below, shepherds the associated GitHub Discussion, and attempts to build consensus around the idea. Note that ideas and any resulting ACP is public. Authors should not post any ideas or anything in an ACP that the Author wants to keep confidential or to keep ownership rights in (such as intellectual property rights).

### Step 1: Post Your Idea to [GitHub Discussions](https://github.com/avalanche-foundation/ACPs/discussions/categories/ideas)

The author(s) should first attempt to ascertain whether there is support for their idea by posting in the "Ideas" category of GitHub Discussions. Vetting an idea publicly before going as far as writing an ACP is meant to save both the potential author(s) and the wider Avalanche Community time. Asking the Avalanche Community first if an idea is original helps prevent too much time being spent on something that is guaranteed to be rejected based on prior discussions (searching the Internet does not always do the trick). It also helps to make sure the idea is applicable to the entire community and not just the author(s). Small enhancements or patches often don't need standardization between multiple projects; these don't need an ACP and should be injected into the relevant development workflow with a patch submission to the applicable ANC issue tracker.

### Step 2: Propose an ACP via [Pull Request](https://github.com/avalanche-foundation/ACPs/pulls)

Once the author(s) feels confident that an idea has a decent chance of acceptance, an ACP should be drafted and submitted as a pull request (PR). This draft must be written in ACP style as described below. It is highly recommended that a single ACP contain a single key proposal or new idea. The more focused the ACP, the more successful it tends to be. If in doubt, split your ACP into several well-focused ones. The PR number of the ACP will become its assigned number.

### Step 3: Build Consensus on [GitHub Discussions](https://github.com/avalanche-foundation/ACPs/discussions/categories/discussion) and Provide an Implementation (if Applicable)

ACPs will be merged by ACP maintainers if the proposal is generally well-formatted and coherent. ACP editors will attempt to merge anything worthy of discussion, regardless of feasibility or complexity, that is not a duplicate or incomplete. After an ACP is merged, an official GitHub Discussion will be opened for the ACP and linked to the proposal for community discussion. It is recommended for author(s) or supportive Avalanche Community members to post an accompanying non-technical overview of their ACP for general consumption in this GitHub Discussion. The ACP should be reviewed and broadly supported before a reference implementation is started, again to avoid wasting the author(s) and the Avalanche Community's time, unless a reference implementation will aid people in studying the ACP.

### Step 4: Mark ACP as `Implementable` via [Pull Request](https://github.com/avalanche-foundation/ACPs/pulls)

Once an ACP is considered complete by the author(s), it should be marked as `Implementable`. At this point, all open questions should be addressed and an associated reference implementation should be provided (if applicable). As mentioned earlier, the Avalanche Foundation meets periodically to recommend the ratification of specific ACPs but it is ultimately up to members of the Avalanche Network/Community to adopt ACPs they support by running a compatible Avalanche Network Client (ANC), such as [AvalancheGo](https://github.com/ava-labs/avalanchego).

### [Optional] Step 5: Mark ACP as `Stale` via [Pull Request](https://github.com/avalanche-foundation/ACPs/pulls)

An ACP can be superseded by a different ACP, rendering the original obsolete. If this occurs, the original ACP will be marked as `Stale`. ACPs may also be marked as `Stale` if the author(s) abandon work on it for a prolonged period of time (12+ months). ACPs may be reopened and moved back to `Proposed` if the author(s) restart work.

### Maintenance

ACP maintainers will only merge PRs updating an ACP if it is created or approved by at least one of the author(s). ACP maintainers are not responsible for ensuring ACP author(s) approve the PR. ACP author(s) are expected to review PRs that target their unlocked ACP (`Proposed` or `Implementable`). Any PRs opened against a locked ACP (`Activated` or `Stale`) will not be merged by ACP maintainers.

## What belongs in a successful ACP?

Each ACP must have the following parts:

* `Preamble`: Markdown table containing metadata about the ACP, including the ACP number, a short descriptive title, the author(s), and optionally the contact info for each author, etc.
* `Abstract`: Concise (~200 word) description of the ACP
* `Motivation`: Rationale for adopting the ACP and the specific issue/challenge/opportunity it addresses
* `Specification`: Complete description of the semantics of any change should allow any ANC/Avalanche Community member to implement the ACP
* `Security Considerations`: Security implications of the proposed ACP

Each ACP can have the following parts:

* `Open Questions`: Questions that should be resolved before implementation

Each `Standards Track` ACP must have the following parts:

* `Backwards Compatibility`: List of backwards incompatible changes required to implement the ACP and their impact on the Avalanche Community
* `Reference Implementation`: Code, documentation, and telemetry (from a local network) of the ACP change

Each `Best Practices Track` ACP can have the following parts:

* `Backwards Compatibility`: List of backwards incompatible changes required to implement the ACP and their impact on the Avalanche Community
* `Reference Implementation`: Code, documentation, and telemetry (from a local network) of the ACP change

### ACP Formats and Templates

Each ACP is allocated a unique subdirectory in the `ACPs` directory. The name of this subdirectory must be of the form `N-T` where `N` is the ACP number and `T` is the ACP title with any spaces replaced by hyphens. ACPs must be written in [markdown](https://daringfireball.net/projects/markdown/syntax) format and stored at `ACPs/N-T/README.md`. Please see the [ACP template](https://raw.githubusercontent.com/avalanche-foundation/ACPs/main/ACPs/TEMPLATE.md) for an example of the correct layout.

### Auxiliary Files

ACPs may include auxiliary files such as diagrams or code snippets. Such files should be stored in the ACP's subdirectory (`ACPs/N-T/*`). There is no required naming convention for auxiliary files.

### Waived Copyright

ACP authors must waive any copyright claims before an ACP will be merged into the repository. This can be done by including the following text in an ACP:

```text
## Copyright

Copyright and related rights waived via [CC0](https://creativecommons.org/publicdomain/zero/1.0/).
```

## Proposals

_You can view the status of each ACP on the [ACP Tracker](https://github.com/orgs/avalanche-foundation/projects/1/views/1)._

| Number | Title |  Author(s) | Type |
|:-------|:------|:-------|:-----|
|[13](https://raw.githubusercontent.com/avalanche-foundation/ACPs/main/ACPs/13-subnet-only-validators/README.md)|Subnet-Only Validators (SOVs)|Patrick O'Grady (contact@patrickogrady.xyz)|Standards|
|[20](https://raw.githubusercontent.com/avalanche-foundation/ACPs/main/ACPs/20-ed25519-p2p/README.md)|Ed25519 p2p|Dhruba Basu ([@dhrubabasu](https://github.com/dhrubabasu))|Standards|
|[23](https://raw.githubusercontent.com/avalanche-foundation/ACPs/main/ACPs/23-p-chain-native-transfers/README.md)|P-Chain Native Transfers|Dhruba Basu ([@dhrubabasu](https://github.com/dhrubabasu))|Standards|
|[24](https://raw.githubusercontent.com/avalanche-foundation/ACPs/main/ACPs/24-shanghai-eips/README.md)|Activate Shanghai EIPs on C-Chain|Darioush Jalali ([@darioush](https://github.com/darioush))|Standards|
|[25](https://raw.githubusercontent.com/avalanche-foundation/ACPs/main/ACPs/25-vm-application-errors/README.md)|Virtual Machine Application Errors|Joshua Kim ([@joshua-kim](https://github.com/joshua-kim))|Standards|
|[30](https://raw.githubusercontent.com/avalanche-foundation/ACPs/main/ACPs/30-avalanche-warp-x-evm/README.md)|Integrate Avalanche Warp Messaging into the EVM|Aaron Buchwald (aaron.buchwald56@gmail.com)|Standards|
|[31](https://raw.githubusercontent.com/avalanche-foundation/ACPs/main/ACPs/31-enable-subnet-ownership-transfer/README.md)|Enable Subnet Ownership Transfer|Dhruba Basu ([@dhrubabasu](https://github.com/dhrubabasu))|Standards|
|[41](https://raw.githubusercontent.com/avalanche-foundation/ACPs/main/ACPs/41-remove-pending-stakers/README.md)|Remove Pending Stakers|Dhruba Basu ([@dhrubabasu](https://github.com/dhrubabasu))|Standards|
|[62](https://raw.githubusercontent.com/avalanche-foundation/ACPs/main/ACPs/62-disable-addvalidatortx-and-adddelegatortx/README.md)|Disable `AddValidatorTx` and `AddDelegatorTx`|Jacob Everly (https://twitter.com/JacobEv3rly), Dhruba Basu ([@dhrubabasu](https://github.com/dhrubabasu))|Standards|
|[75](https://raw.githubusercontent.com/avalanche-foundation/ACPs/main/ACPs/75-acceptance-proofs/README.md)|Acceptance Proofs|Joshua Kim ([@joshua-kim](https://github.com/joshua-kim))|Standards|
|[77](https://raw.githubusercontent.com/avalanche-foundation/ACPs/main/ACPs/77-reinventing-subnets/README.md)|Reinventing Subnets|Dhruba Basu ([@dhrubabasu](https://github.com/dhrubabasu))|Standards|
|[83](https://raw.githubusercontent.com/avalanche-foundation/ACPs/main/ACPs/83-dynamic-multidimensional-fees/README.md)|Dynamic Multidimensional Fees for P-Chain and X-Chain|Alberto Benegiamo ([@abi87](https://github.com/abi87))|Standards|
|[84](https://raw.githubusercontent.com/avalanche-foundation/ACPs/main/ACPs/84-table-preamble/README.md)|Table Preamble for ACPs|Gauthier Leonard ([@Nuttymoon](https://github.com/Nuttymoon))|Meta|
|[99](https://raw.githubusercontent.com/avalanche-foundation/ACPs/main/ACPs/99-validatorsetmanager-contract/README.md)|Validator Manager Solidity Standard|Gauthier Leonard ([@Nuttymoon](https://github.com/Nuttymoon)), Cam Schultz ([@cam-schultz](https://github.com/cam-schultz))|Best Practices|
|[103](https://raw.githubusercontent.com/avalanche-foundation/ACPs/main/ACPs/103-dynamic-fees/README.md)|Add Dynamic Fees to the X-Chain and P-Chain|Dhruba Basu ([@dhrubabasu](https://github.com/dhrubabasu)), Alberto Benegiamo ([@abi87](https://github.com/abi87)), Stephen Buttolph ([@StephenButtolph](https://github.com/StephenButtolph))|Standards|
|[108](https://raw.githubusercontent.com/avalanche-foundation/ACPs/main/ACPs/108-evm-event-importing/README.md)|EVM Event Importing|Michael Kaplan ([@michaelkaplan13](https://github.com/michaelkaplan13))|Best Practices|
|[113](https://raw.githubusercontent.com/avalanche-foundation/ACPs/main/ACPs/113-provable-randomness/README.md)|Provable Virtual Machine Randomness|Tsachi Herman ([@tsachiherman](https://github.com/tsachiherman))|Standards|
|[118](https://raw.githubusercontent.com/avalanche-foundation/ACPs/main/ACPs/118-warp-signature-request/README.md)|Standardized P2P Warp Signature Request Interface|Cam Schultz ([@cam-schultz](https://github.com/cam-schultz))|Best Practices|
|[125](https://raw.githubusercontent.com/avalanche-foundation/ACPs/main/ACPs/125-basefee-reduction/README.md)|Reduce C-Chain minimum base fee from 25 nAVAX to 1 nAVAX|Stephen Buttolph ([@StephenButtolph](https://github.com/StephenButtolph)), Darioush Jalali ([@darioush](https://github.com/darioush))|Standards|
|[131](https://raw.githubusercontent.com/avalanche-foundation/ACPs/main/ACPs/131-cancun-eips/README.md)|Activate Cancun EIPs on C-Chain and Subnet-EVM chains|Darioush Jalali ([@darioush](https://github.com/darioush)), Ceyhun Onur ([@ceyonur](https://github.com/ceyonur))|Standards|
|[151](https://raw.githubusercontent.com/avalanche-foundation/ACPs/main/ACPs/151-use-current-block-pchain-height-as-context/README.md)|Use current block P-Chain height as context for state verification|Ian Suvak ([@iansuvak](https://github.com/iansuvak))|Standards|
|[176](https://raw.githubusercontent.com/avalanche-foundation/ACPs/main/ACPs/176-dynamic-evm-gas-limit-and-price-discovery-updates/README.md)|Dynamic EVM Gas Limits and Price Discovery Updates|Stephen Buttolph ([@StephenButtolph](https://github.com/StephenButtolph)), Michael Kaplan ([@michaelkaplan13](https://github.com/michaelkaplan13))|Standards|
|[181](https://raw.githubusercontent.com/avalanche-foundation/ACPs/main/ACPs/181-p-chain-epoched-views/README.md)|P-Chain Epoched Views|Cam Schultz ([@cam-schultz](https://github.com/cam-schultz))|Standards|
|[191](https://raw.githubusercontent.com/avalanche-foundation/ACPs/main/ACPs/191-seamless-l1-creation/README.md)|Seamless L1 Creations (CreateL1Tx)|Martin Eckardt ([@martineckardt](https://github.com/martineckardt)), Aaron Buchwald ([aaronbuchwald](https://github.com/aaronbuchwald)), Michael Kaplan ([@michaelkaplan13](https://github.com/michaelkaplan13)), Meag FitzGerald ([@meaghanfitzgerald](https://github.com/meaghanfitzgerald))|Standards|
|[194](https://raw.githubusercontent.com/avalanche-foundation/ACPs/main/ACPs/194-streaming-asynchronous-execution/README.md)|Streaming Asynchronous Execution|Arran Schlosberg ([@ARR4N](https://github.com/ARR4N)), Stephen Buttolph ([@StephenButtolph](https://github.com/StephenButtolph))|Standards|
|[204](https://raw.githubusercontent.com/avalanche-foundation/ACPs/main/ACPs/204-precompile-secp256r1/README.md)|Precompile for secp256r1 Curve Support|Santiago Cammi ([@scammi](https://github.com/scammi)), Arran Schlosberg ([@ARR4N](https://github.com/ARR4N))|Standards|
|[209](https://raw.githubusercontent.com/avalanche-foundation/ACPs/main/ACPs/209-eip7702-style-account-abstraction/README.md)|EIP-7702-style Set Code for EOAs|Stephen Buttolph ([@StephenButtolph](https://github.com/StephenButtolph)), Arran Schlosberg ([@ARR4N](https://github.com/ARR4N)), Aaron Buchwald ([aaronbuchwald](https://github.com/aaronbuchwald)), Michael Kaplan ([@michaelkaplan13](https://github.com/michaelkaplan13))|Standards|
|[224](https://raw.githubusercontent.com/avalanche-foundation/ACPs/main/ACPs/224-dynamic-gas-limit-in-subnet-evm/README.md)|Introduce ACP-176-Based Dynamic Gas Limits and Fee Manager Precompile in Subnet-EVM|Ceyhun Onur ([@ceyonur](https://github.com/ceyonur), Michael Kaplan ([@michaelkaplan13](https://github.com/michaelkaplan13))|Standards|
|[226](https://raw.githubusercontent.com/avalanche-foundation/ACPs/main/ACPs/226-dynamic-minimum-block-times/README.md)|Dynamic Minimum Block Times|Stephen Buttolph ([@StephenButtolph](https://github.com/StephenButtolph)), Michael Kaplan ([@michaelkaplan13](https://github.com/michaelkaplan13))|Standards|

## Contributing

Before contributing to ACPs, please read the [ACP Terms of Contribution](https://raw.githubusercontent.com/avalanche-foundation/ACPs/main/CONTRIBUTING.md).

# CLI Commands (/docs/tooling/cli-commands)

---
title: "CLI Commands"
description: "Complete list of Avalanche CLI commands and their usage."
edit_url: https://github.com/ava-labs/avalanche-cli/edit/main/cmd/commands.md
---

<a id="avalanche-blockchain"></a>
## avalanche blockchain

The blockchain command suite provides a collection of tools for developing
and deploying Blockchains.

To get started, use the blockchain create command wizard to walk through the
configuration of your very first Blockchain. Then, go ahead and deploy it
with the blockchain deploy command. You can use the rest of the commands to
manage your Blockchain configurations and live deployments.

**Usage:**
```bash
avalanche blockchain [subcommand] [flags]
```

**Subcommands:**

- [`addValidator`](#avalanche-blockchain-addvalidator): The blockchain addValidator command adds a node as a validator to
an L1 of the user provided deployed network. If the network is proof of 
authority, the owner of the validator manager contract must sign the 
transaction. If the network is proof of stake, the node must stake the L1's
staking token. Both processes will issue a RegisterL1ValidatorTx on the P-Chain.

This command currently only works on Blockchains deployed to either the Fuji
Testnet or Mainnet.
- [`changeOwner`](#avalanche-blockchain-changeowner): The blockchain changeOwner changes the owner of the deployed Blockchain.
- [`changeWeight`](#avalanche-blockchain-changeweight): The blockchain changeWeight command changes the weight of a L1 Validator.

The L1 has to be a Proof of Authority L1.
- [`configure`](#avalanche-blockchain-configure): AvalancheGo nodes support several different configuration files.
Each network (a Subnet or an L1) has their own config which applies to all blockchains/VMs in the network (see https://build.avax.network/docs/nodes/configure/avalanche-l1-configs)
Each blockchain within the network can have its own chain config (see https://build.avax.network/docs/nodes/chain-configs/c-chain https://github.com/ava-labs/subnet-evm/blob/master/plugin/evm/config/config.go for subnet-evm options).
A chain can also have special requirements for the AvalancheGo node configuration itself (see https://build.avax.network/docs/nodes/configure/configs-flags).
This command allows you to set all those files.
- [`create`](#avalanche-blockchain-create): The blockchain create command builds a new genesis file to configure your Blockchain.
By default, the command runs an interactive wizard. It walks you through
all the steps you need to create your first Blockchain.

The tool supports deploying Subnet-EVM, and custom VMs. You
can create a custom, user-generated genesis with a custom VM by providing
the path to your genesis and VM binaries with the --genesis and --vm flags.

By default, running the command with a blockchainName that already exists
causes the command to fail. If you'd like to overwrite an existing
configuration, pass the -f flag.
- [`delete`](#avalanche-blockchain-delete): The blockchain delete command deletes an existing blockchain configuration.
- [`deploy`](#avalanche-blockchain-deploy): The blockchain deploy command deploys your Blockchain configuration locally, to Fuji Testnet, or to Mainnet.

At the end of the call, the command prints the RPC URL you can use to interact with the Subnet.

Avalanche-CLI only supports deploying an individual Blockchain once per network. Subsequent
attempts to deploy the same Blockchain to the same network (local, Fuji, Mainnet) aren't
allowed. If you'd like to redeploy a Blockchain locally for testing, you must first call
avalanche network clean to reset all deployed chain state. Subsequent local deploys
redeploy the chain with fresh state. You can deploy the same Blockchain to multiple networks,
so you can take your locally tested Blockchain and deploy it on Fuji or Mainnet.
- [`describe`](#avalanche-blockchain-describe): The blockchain describe command prints the details of a Blockchain configuration to the console.
By default, the command prints a summary of the configuration. By providing the --genesis
flag, the command instead prints out the raw genesis file.
- [`export`](#avalanche-blockchain-export): The blockchain export command write the details of an existing Blockchain deploy to a file.

The command prompts for an output path. You can also provide one with
the --output flag.
- [`import`](#avalanche-blockchain-import): Import blockchain configurations into avalanche-cli.

This command suite supports importing from a file created on another computer,
or importing from blockchains running public networks
(e.g. created manually or with the deprecated subnet-cli)
- [`join`](#avalanche-blockchain-join): The blockchain join command configures your validator node to begin validating a new Blockchain.

To complete this process, you must have access to the machine running your validator. If the
CLI is running on the same machine as your validator, it can generate or update your node's
config file automatically. Alternatively, the command can print the necessary instructions
to update your node manually. To complete the validation process, the Blockchain's admins must add
the NodeID of your validator to the Blockchain's allow list by calling addValidator with your
NodeID.

After you update your validator's config, you need to restart your validator manually. If
you provide the --avalanchego-config flag, this command attempts to edit the config file
at that path.

This command currently only supports Blockchains deployed on the Fuji Testnet and Mainnet.
- [`list`](#avalanche-blockchain-list): The blockchain list command prints the names of all created Blockchain configurations. Without any flags,
it prints some general, static information about the Blockchain. With the --deployed flag, the command
shows additional information including the VMID, BlockchainID and SubnetID.
- [`publish`](#avalanche-blockchain-publish): The blockchain publish command publishes the Blockchain's VM to a repository.
- [`removeValidator`](#avalanche-blockchain-removevalidator): The blockchain removeValidator command stops a whitelisted blockchain network validator from
validating your deployed Blockchain.

To remove the validator from the Subnet's allow list, provide the validator's unique NodeID. You can bypass
these prompts by providing the values with flags.
- [`stats`](#avalanche-blockchain-stats): The blockchain stats command prints validator statistics for the given Blockchain.
- [`upgrade`](#avalanche-blockchain-upgrade): The blockchain upgrade command suite provides a collection of tools for
updating your developmental and deployed Blockchains.
- [`validators`](#avalanche-blockchain-validators): The blockchain validators command lists the validators of a blockchain and provides
several statistics about them.
- [`vmid`](#avalanche-blockchain-vmid): The blockchain vmid command prints the virtual machine ID (VMID) for the given Blockchain.

**Flags:**

```bash
-h, --help             help for blockchain
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-blockchain-addvalidator"></a>
### addValidator

The blockchain addValidator command adds a node as a validator to
an L1 of the user provided deployed network. If the network is proof of 
authority, the owner of the validator manager contract must sign the 
transaction. If the network is proof of stake, the node must stake the L1's
staking token. Both processes will issue a RegisterL1ValidatorTx on the P-Chain.

This command currently only works on Blockchains deployed to either the Fuji
Testnet or Mainnet.

**Usage:**
```bash
avalanche blockchain addValidator [subcommand] [flags]
```

**Flags:**

```bash
--aggregator-allow-private-peers        allow the signature aggregator to connect to peers with private IP (default true)
--aggregator-extra-endpoints strings    endpoints for extra nodes that are needed in signature aggregation
--aggregator-log-level string           log level to use with signature aggregator (default "Debug")
--aggregator-log-to-stdout              use stdout for signature aggregator logs
--balance float                         set the AVAX balance of the validator that will be used for continuous fee on P-Chain
--blockchain-genesis-key                use genesis allocated key to pay fees for completing the validator's registration (blockchain gas token)
--blockchain-key string                 CLI stored key to use to pay fees for completing the validator's registration (blockchain gas token)
--blockchain-private-key string         private key to use to pay fees for completing the validator's registration (blockchain gas token)
--bls-proof-of-possession string        set the BLS proof of possession of the validator to add
--bls-public-key string                 set the BLS public key of the validator to add
--cluster string                        operate on the given cluster
--create-local-validator                create additional local validator and add it to existing running local node
--default-duration                      (for Subnets, not L1s) set duration so as to validate until primary validator ends its period
--default-start-time                    (for Subnets, not L1s) use default start time for subnet validator (5 minutes later for fuji & mainnet, 30 seconds later for devnet)
--default-validator-params              (for Subnets, not L1s) use default weight/start/duration params for subnet validator
--delegation-fee uint16                 (PoS only) delegation fee (in bips) (default 100)
--devnet                                operate on a devnet network
--disable-owner string                  P-Chain address that will able to disable the validator with a P-Chain transaction
--endpoint string                       use the given endpoint for network operations
-e, --ewoq                              use ewoq key [fuji/devnet only]
-f, --fuji                              testnet                         operate on fuji (alias to testnet
-h, --help                              help for addValidator
-k, --key string                        select the key to use [fuji/devnet only]
-g, --ledger                            use ledger instead of key (always true on mainnet, defaults to false on fuji/devnet)
--ledger-addrs strings                  use the given ledger addresses
-l, --local                             operate on a local network
-m, --mainnet                           operate on mainnet
--node-endpoint string                  gather node id/bls from publicly available avalanchego apis on the given endpoint
--node-id string                        node-id of the validator to add
--output-tx-path string                 (for Subnets, not L1s) file path of the add validator tx
--partial-sync                          set primary network partial sync for new validators (default true)
--remaining-balance-owner string        P-Chain address that will receive any leftover AVAX from the validator when it is removed from Subnet
--rpc string                            connect to validator manager at the given rpc endpoint
--stake-amount uint                     (PoS only) amount of tokens to stake
--staking-period duration               how long this validator will be staking
--start-time string                     (for Subnets, not L1s) UTC start time when this validator starts validating, in 'YYYY-MM-DD HH:MM:SS' format
--subnet-auth-keys strings              (for Subnets, not L1s) control keys that will be used to authenticate add validator tx
-t, --testnet                           fuji                         operate on testnet (alias to fuji)
--wait-for-tx-acceptance                (for Subnets, not L1s) just issue the add validator tx, without waiting for its acceptance (default true)
--weight uint                           set the staking weight of the validator to add (default 20)
--config string                         config file (default is $HOME/.avalanche-cli/config.json)
--log-level string                      log level for the application (default "ERROR")
--skip-update-check                     skip check for new versions
```

<a id="avalanche-blockchain-changeowner"></a>
### changeOwner

The blockchain changeOwner changes the owner of the deployed Blockchain.

**Usage:**
```bash
avalanche blockchain changeOwner [subcommand] [flags]
```

**Flags:**

```bash
--auth-keys strings        control keys that will be used to authenticate transfer blockchain ownership tx
--cluster string           operate on the given cluster
--control-keys strings     addresses that may make blockchain changes
--devnet                   operate on a devnet network
--endpoint string          use the given endpoint for network operations
-e, --ewoq                 use ewoq key [fuji/devnet]
-f, --fuji                 testnet            operate on fuji (alias to testnet
-h, --help                 help for changeOwner
-k, --key string           select the key to use [fuji/devnet]
-g, --ledger               use ledger instead of key (always true on mainnet, defaults to false on fuji/devnet)
--ledger-addrs strings     use the given ledger addresses
-l, --local                operate on a local network
-m, --mainnet              operate on mainnet
--output-tx-path string    file path of the transfer blockchain ownership tx
-s, --same-control-key     use the fee-paying key as control key
-t, --testnet              fuji            operate on testnet (alias to fuji)
--threshold uint32         required number of control key signatures to make blockchain changes
--config string            config file (default is $HOME/.avalanche-cli/config.json)
--log-level string         log level for the application (default "ERROR")
--skip-update-check        skip check for new versions
```

<a id="avalanche-blockchain-changeweight"></a>
### changeWeight

The blockchain changeWeight command changes the weight of a L1 Validator.

The L1 has to be a Proof of Authority L1.

**Usage:**
```bash
avalanche blockchain changeWeight [subcommand] [flags]
```

**Flags:**

```bash
--cluster string          operate on the given cluster
--devnet                  operate on a devnet network
--endpoint string         use the given endpoint for network operations
-e, --ewoq                use ewoq key [fuji/devnet only]
-f, --fuji                testnet           operate on fuji (alias to testnet
-h, --help                help for changeWeight
-k, --key string          select the key to use [fuji/devnet only]
-g, --ledger              use ledger instead of key (always true on mainnet, defaults to false on fuji/devnet)
--ledger-addrs strings    use the given ledger addresses
-l, --local               operate on a local network
-m, --mainnet             operate on mainnet
--node-endpoint string    gather node id/bls from publicly available avalanchego apis on the given endpoint
--node-id string          node-id of the validator
-t, --testnet             fuji           operate on testnet (alias to fuji)
--weight uint             set the new staking weight of the validator
--config string           config file (default is $HOME/.avalanche-cli/config.json)
--log-level string        log level for the application (default "ERROR")
--skip-update-check       skip check for new versions
```

<a id="avalanche-blockchain-configure"></a>
### configure

AvalancheGo nodes support several different configuration files.
Each network (a Subnet or an L1) has their own config which applies to all blockchains/VMs in the network (see https://build.avax.network/docs/nodes/configure/avalanche-l1-configs)
Each blockchain within the network can have its own chain config (see https://build.avax.network/docs/nodes/chain-configs/c-chain https://github.com/ava-labs/subnet-evm/blob/master/plugin/evm/config/config.go for subnet-evm options).
A chain can also have special requirements for the AvalancheGo node configuration itself (see https://build.avax.network/docs/nodes/configure/configs-flags).
This command allows you to set all those files.

**Usage:**
```bash
avalanche blockchain configure [subcommand] [flags]
```

**Flags:**

```bash
--chain-config string             path to the chain configuration
-h, --help                        help for configure
--node-config string              path to avalanchego node configuration
--per-node-chain-config string    path to per node chain configuration for local network
--subnet-config string            path to the subnet configuration
--config string                   config file (default is $HOME/.avalanche-cli/config.json)
--log-level string                log level for the application (default "ERROR")
--skip-update-check               skip check for new versions
```

<a id="avalanche-blockchain-create"></a>
### create

The blockchain create command builds a new genesis file to configure your Blockchain.
By default, the command runs an interactive wizard. It walks you through
all the steps you need to create your first Blockchain.

The tool supports deploying Subnet-EVM, and custom VMs. You
can create a custom, user-generated genesis with a custom VM by providing
the path to your genesis and VM binaries with the --genesis and --vm flags.

By default, running the command with a blockchainName that already exists
causes the command to fail. If you'd like to overwrite an existing
configuration, pass the -f flag.

**Usage:**
```bash
avalanche blockchain create [subcommand] [flags]
```

**Flags:**

```bash
--custom                            use a custom VM template
--custom-vm-branch string           custom vm branch or commit
--custom-vm-build-script string     custom vm build-script
--custom-vm-path string             file path of custom vm to use
--custom-vm-repo-url string         custom vm repository url
--debug                             enable blockchain debugging (default true)
--evm                               use the Subnet-EVM as the base template
--evm-chain-id uint                 chain ID to use with Subnet-EVM
--evm-defaults                      deprecation notice: use '--production-defaults'
--evm-token string                  token symbol to use with Subnet-EVM
--external-gas-token                use a gas token from another blockchain
-f, --force                         overwrite the existing configuration if one exists
--from-github-repo                  generate custom VM binary from github repository
--genesis string                    file path of genesis to use
-h, --help                          help for create
--icm                               interoperate with other blockchains using ICM
--icm-registry-at-genesis           setup ICM registry smart contract on genesis [experimental]
--latest                            use latest Subnet-EVM released version, takes precedence over --vm-version
--pre-release                       use latest Subnet-EVM pre-released version, takes precedence over --vm-version
--production-defaults               use default production settings for your blockchain
--proof-of-authority                use proof of authority(PoA) for validator management
--proof-of-stake                    use proof of stake(PoS) for validator management
--proxy-contract-owner string       EVM address that controls ProxyAdmin for TransparentProxy of ValidatorManager contract
--reward-basis-points uint          (PoS only) reward basis points for PoS Reward Calculator (default 100)
--sovereign                         set to false if creating non-sovereign blockchain (default true)
--teleporter                        interoperate with other blockchains using ICM
--test-defaults                     use default test settings for your blockchain
--validator-manager-owner string    EVM address that controls Validator Manager Owner
--vm string                         file path of custom vm to use. alias to custom-vm-path
--vm-version string                 version of Subnet-EVM template to use
--warp                              generate a vm with warp support (needed for ICM) (default true)
--config string                     config file (default is $HOME/.avalanche-cli/config.json)
--log-level string                  log level for the application (default "ERROR")
--skip-update-check                 skip check for new versions
```

<a id="avalanche-blockchain-delete"></a>
### delete

The blockchain delete command deletes an existing blockchain configuration.

**Usage:**
```bash
avalanche blockchain delete [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for delete
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-blockchain-deploy"></a>
### deploy

The blockchain deploy command deploys your Blockchain configuration to Local Network, to Fuji Testnet, DevNet or to Mainnet.

At the end of the call, the command prints the RPC URL you can use to interact with the L1 / Subnet.

When deploying an L1, Avalanche-CLI lets you use your local machine as a bootstrap validator, so you don't need to run separate Avalanche nodes.
This is controlled by the --use-local-machine flag (enabled by default on Local Network).

If --use-local-machine is set to true:
- Avalanche-CLI will call CreateSubnetTx, CreateChainTx, ConvertSubnetToL1Tx, followed by syncing the local machine bootstrap validator to the L1 and initialize
  Validator Manager Contract on the L1

If using your own Avalanche Nodes as bootstrap validators:
- Avalanche-CLI will call CreateSubnetTx, CreateChainTx, ConvertSubnetToL1Tx
- You will have to sync your bootstrap validators to the L1
- Next, Initialize Validator Manager contract on the L1 using avalanche contract initValidatorManager [L1_Name]

Avalanche-CLI only supports deploying an individual Blockchain once per network. Subsequent
attempts to deploy the same Blockchain to the same network (Local Network, Fuji, Mainnet) aren't
allowed. If you'd like to redeploy a Blockchain locally for testing, you must first call
avalanche network clean to reset all deployed chain state. Subsequent local deploys
redeploy the chain with fresh state. You can deploy the same Blockchain to multiple networks,
so you can take your locally tested Blockchain and deploy it on Fuji or Mainnet.

**Usage:**
```bash
avalanche blockchain deploy [subcommand] [flags]
```

**Flags:**

```bash
 --convert-only              avoid node track, restart and poa manager setup
  -e, --ewoq                      use ewoq key [local/devnet deploy only]
  -h, --help                      help for deploy
  -k, --key string                select the key to use [fuji/devnet deploy only]
  -g, --ledger                    use ledger instead of key
      --ledger-addrs strings      use the given ledger addresses
      --mainnet-chain-id uint32   use different ChainID for mainnet deployment
      --output-tx-path string     file path of the blockchain creation tx (for multi-sig signing)
  -u, --subnet-id string          do not create a subnet, deploy the blockchain into the given subnet id
      --subnet-only               command stops after CreateSubnetTx and returns SubnetID

Network Flags (Select One):
  --cluster string   operate on the given cluster
  --devnet           operate on a devnet network
  --endpoint string  use the given endpoint for network operations
  --fuji             operate on fuji (alias to `testnet`)
  --local            operate on a local network
  --mainnet          operate on mainnet
  --testnet          operate on testnet (alias to `fuji`)

Bootstrap Validators Flags:
  --balance float64                  set the AVAX balance of each bootstrap validator that will be used for continuous fee on P-Chain (setting balance=1 equals to 1 AVAX for each bootstrap validator)
  --bootstrap-endpoints stringSlice  take validator node info from the given endpoints
  --bootstrap-filepath string        JSON file path that provides details about bootstrap validators
  --change-owner-address string      address that will receive change if node is no longer L1 validator
  --generate-node-id                 set to true to generate Node IDs for bootstrap validators when none are set up. Use these Node IDs to set up your Avalanche Nodes.
  --num-bootstrap-validators int     number of bootstrap validators to set up in sovereign L1 validator)

Local Machine Flags (Use Local Machine as Bootstrap Validator):
  --avalanchego-path string              use this avalanchego binary path
  --avalanchego-version string           use this version of avalanchego (ex: v1.17.12)
  --http-port uintSlice                  http port for node(s)
  --partial-sync                         set primary network partial sync for new validators
  --staking-cert-key-path stringSlice    path to provided staking cert key for node(s)
  --staking-port uintSlice               staking port for node(s)
  --staking-signer-key-path stringSlice  path to provided staking signer key for node(s)
  --staking-tls-key-path stringSlice     path to provided staking TLS key for node(s)
  --use-local-machine                    use local machine as a blockchain validator

Local Network Flags:
  --avalanchego-path string     use this avalanchego binary path
  --avalanchego-version string  use this version of avalanchego (ex: v1.17.12)
  --num-nodes uint32            number of nodes to be created on local network deploy

Non Subnet-Only-Validators (Non-SOV) Flags:
  --auth-keys stringSlice     control keys that will be used to authenticate chain creation
  --control-keys stringSlice  addresses that may make blockchain changes
  --same-control-key          use the fee-paying key as control key
  --threshold uint32          required number of control key signatures to make blockchain changes

ICM Flags:
  --cchain-funding-key string                          key to be used to fund relayer account on cchain
  --cchain-icm-key string                              key to be used to pay for ICM deploys on C-Chain
  --icm-key string                                     key to be used to pay for ICM deploys
  --icm-version string                                 ICM version to deploy
  --relay-cchain                                       relay C-Chain as source and destination
  --relayer-allow-private-ips                          allow relayer to connec to private ips
  --relayer-amount float64                             automatically fund relayer fee payments with the given amount
  --relayer-key string                                 key to be used by default both for rewards and to pay fees
  --relayer-log-level string                           log level to be used for relayer logs
  --relayer-path string                                relayer binary to use
  --relayer-version string                             relayer version to deploy
  --skip-icm-deploy                                    Skip automatic ICM deploy
  --skip-relayer                                       skip relayer deploy
  --teleporter-messenger-contract-address-path string  path to an ICM Messenger contract address file
  --teleporter-messenger-deployer-address-path string  path to an ICM Messenger deployer address file
  --teleporter-messenger-deployer-tx-path string       path to an ICM Messenger deployer tx file
  --teleporter-registry-bytecode-path string           path to an ICM Registry bytecode file

Proof Of Stake Flags:
  --pos-maximum-stake-amount uint64     maximum stake amount
  --pos-maximum-stake-multiplier uint8  maximum stake multiplier
  --pos-minimum-delegation-fee uint16   minimum delegation fee
  --pos-minimum-stake-amount uint64     minimum stake amount
  --pos-minimum-stake-duration uint64   minimum stake duration (in seconds)
  --pos-weight-to-value-factor uint64   weight to value factor

Signature Aggregator Flags:
  --aggregator-log-level string  log level to use with signature aggregator
  --aggregator-log-to-stdout     use stdout for signature aggregator logs
```

<a id="avalanche-blockchain-describe"></a>
### describe

The blockchain describe command prints the details of a Blockchain configuration to the console.
By default, the command prints a summary of the configuration. By providing the --genesis
flag, the command instead prints out the raw genesis file.

**Usage:**
```bash
avalanche blockchain describe [subcommand] [flags]
```

**Flags:**

```bash
-g, --genesis          Print the genesis to the console directly instead of the summary
-h, --help             help for describe
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-blockchain-export"></a>
### export

The blockchain export command write the details of an existing Blockchain deploy to a file.

The command prompts for an output path. You can also provide one with
the --output flag.

**Usage:**
```bash
avalanche blockchain export [subcommand] [flags]
```

**Flags:**

```bash
--custom-vm-branch string          custom vm branch
--custom-vm-build-script string    custom vm build-script
--custom-vm-repo-url string        custom vm repository url
-h, --help                         help for export
-o, --output string                write the export data to the provided file path
--config string                    config file (default is $HOME/.avalanche-cli/config.json)
--log-level string                 log level for the application (default "ERROR")
--skip-update-check                skip check for new versions
```

<a id="avalanche-blockchain-import"></a>
### import

Import blockchain configurations into avalanche-cli.

This command suite supports importing from a file created on another computer,
or importing from blockchains running public networks
(e.g. created manually or with the deprecated subnet-cli)

**Usage:**
```bash
avalanche blockchain import [subcommand] [flags]
```

**Subcommands:**

- [`file`](#avalanche-blockchain-import-file): The blockchain import command will import a blockchain configuration from a file or a git repository.

To import from a file, you can optionally provide the path as a command-line argument.
Alternatively, running the command without any arguments triggers an interactive wizard.
To import from a repository, go through the wizard. By default, an imported Blockchain doesn't 
overwrite an existing Blockchain with the same name. To allow overwrites, provide the --force
flag.
- [`public`](#avalanche-blockchain-import-public): The blockchain import public command imports a Blockchain configuration from a running network.

By default, an imported Blockchain
doesn't overwrite an existing Blockchain with the same name. To allow overwrites, provide the --force
flag.

**Flags:**

```bash
-h, --help             help for import
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-blockchain-import-file"></a>
#### import file

The blockchain import command will import a blockchain configuration from a file or a git repository.

To import from a file, you can optionally provide the path as a command-line argument.
Alternatively, running the command without any arguments triggers an interactive wizard.
To import from a repository, go through the wizard. By default, an imported Blockchain doesn't 
overwrite an existing Blockchain with the same name. To allow overwrites, provide the --force
flag.

**Usage:**
```bash
avalanche blockchain import file [subcommand] [flags]
```

**Flags:**

```bash
--blockchain string    the blockchain configuration to import from the provided repo
--branch string        the repo branch to use if downloading a new repo
-f, --force            overwrite the existing configuration if one exists
-h, --help             help for file
--repo string          the repo to import (ex: ava-labs/avalanche-plugins-core) or url to download the repo from
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-blockchain-import-public"></a>
#### import public

The blockchain import public command imports a Blockchain configuration from a running network.

By default, an imported Blockchain
doesn't overwrite an existing Blockchain with the same name. To allow overwrites, provide the --force
flag.

**Usage:**
```bash
avalanche blockchain import public [subcommand] [flags]
```

**Flags:**

```bash
--blockchain-id string    the blockchain ID
--cluster string          operate on the given cluster
--custom                  use a custom VM template
--devnet                  operate on a devnet network
--endpoint string         use the given endpoint for network operations
--evm                     import a subnet-evm
--force                   overwrite the existing configuration if one exists
-f, --fuji                testnet           operate on fuji (alias to testnet
-h, --help                help for public
-l, --local               operate on a local network
-m, --mainnet             operate on mainnet
--node-url string         [optional] URL of an already running validator
-t, --testnet             fuji           operate on testnet (alias to fuji)
--config string           config file (default is $HOME/.avalanche-cli/config.json)
--log-level string        log level for the application (default "ERROR")
--skip-update-check       skip check for new versions
```

<a id="avalanche-blockchain-join"></a>
### join

The blockchain join command configures your validator node to begin validating a new Blockchain.

To complete this process, you must have access to the machine running your validator. If the
CLI is running on the same machine as your validator, it can generate or update your node's
config file automatically. Alternatively, the command can print the necessary instructions
to update your node manually. To complete the validation process, the Blockchain's admins must add
the NodeID of your validator to the Blockchain's allow list by calling addValidator with your
NodeID.

After you update your validator's config, you need to restart your validator manually. If
you provide the --avalanchego-config flag, this command attempts to edit the config file
at that path.

This command currently only supports Blockchains deployed on the Fuji Testnet and Mainnet.

**Usage:**
```bash
avalanche blockchain join [subcommand] [flags]
```

**Flags:**

```bash
--avalanchego-config string    file path of the avalanchego config file
--cluster string               operate on the given cluster
--data-dir string              path of avalanchego's data dir directory
--devnet                       operate on a devnet network
--endpoint string              use the given endpoint for network operations
--force-write                  if true, skip to prompt to overwrite the config file
-f, --fuji                     testnet                operate on fuji (alias to testnet
-h, --help                     help for join
-k, --key string               select the key to use [fuji only]
-g, --ledger                   use ledger instead of key (always true on mainnet, defaults to false on fuji)
--ledger-addrs strings         use the given ledger addresses
-l, --local                    operate on a local network
-m, --mainnet                  operate on mainnet
--node-id string               set the NodeID of the validator to check
--plugin-dir string            file path of avalanchego's plugin directory
--print                        if true, print the manual config without prompting
--stake-amount uint            amount of tokens to stake on validator
--staking-period duration      how long validator validates for after start time
--start-time string            start time that validator starts validating
-t, --testnet                  fuji                operate on testnet (alias to fuji)
--config string                config file (default is $HOME/.avalanche-cli/config.json)
--log-level string             log level for the application (default "ERROR")
--skip-update-check            skip check for new versions
```

<a id="avalanche-blockchain-list"></a>
### list

The blockchain list command prints the names of all created Blockchain configurations. Without any flags,
it prints some general, static information about the Blockchain. With the --deployed flag, the command
shows additional information including the VMID, BlockchainID and SubnetID.

**Usage:**
```bash
avalanche blockchain list [subcommand] [flags]
```

**Flags:**

```bash
--deployed             show additional deploy information
-h, --help             help for list
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-blockchain-publish"></a>
### publish

The blockchain publish command publishes the Blockchain's VM to a repository.

**Usage:**
```bash
avalanche blockchain publish [subcommand] [flags]
```

**Flags:**

```bash
--alias string               We publish to a remote repo, but identify the repo locally under a user-provided alias (e.g. myrepo).
--force                      If true, ignores if the blockchain has been published in the past, and attempts a forced publish.
-h, --help                   help for publish
--no-repo-path string        Do not let the tool manage file publishing, but have it only generate the files and put them in the location given by this flag.
--repo-url string            The URL of the repo where we are publishing
--subnet-file-path string    Path to the Blockchain description file. If not given, a prompting sequence will be initiated.
--vm-file-path string        Path to the VM description file. If not given, a prompting sequence will be initiated.
--config string              config file (default is $HOME/.avalanche-cli/config.json)
--log-level string           log level for the application (default "ERROR")
--skip-update-check          skip check for new versions
```

<a id="avalanche-blockchain-removevalidator"></a>
### removeValidator

The blockchain removeValidator command stops a whitelisted blockchain network validator from
validating your deployed Blockchain.

To remove the validator from the Subnet's allow list, provide the validator's unique NodeID. You can bypass
these prompts by providing the values with flags.

**Usage:**
```bash
avalanche blockchain removeValidator [subcommand] [flags]
```

**Flags:**

```bash
--aggregator-allow-private-peers        allow the signature aggregator to connect to peers with private IP (default true)
--aggregator-extra-endpoints strings    endpoints for extra nodes that are needed in signature aggregation
--aggregator-log-level string           log level to use with signature aggregator (default "Debug")
--aggregator-log-to-stdout              use stdout for signature aggregator logs
--auth-keys strings                     (for non-SOV blockchain only) control keys that will be used to authenticate the removeValidator tx
--blockchain-genesis-key                use genesis allocated key to pay fees for completing the validator's removal (blockchain gas token)
--blockchain-key string                 CLI stored key to use to pay fees for completing the validator's removal (blockchain gas token)
--blockchain-private-key string         private key to use to pay fees for completing the validator's removal (blockchain gas token)
--cluster string                        operate on the given cluster
--devnet                                operate on a devnet network
--endpoint string                       use the given endpoint for network operations
--force                                 force validator removal even if it's not getting rewarded
-f, --fuji                              testnet                         operate on fuji (alias to testnet
-h, --help                              help for removeValidator
-k, --key string                        select the key to use [fuji deploy only]
-g, --ledger                            use ledger instead of key (always true on mainnet, defaults to false on fuji)
--ledger-addrs strings                  use the given ledger addresses
-l, --local                             operate on a local network
-m, --mainnet                           operate on mainnet
--node-endpoint string                  remove validator that responds to the given endpoint
--node-id string                        node-id of the validator
--output-tx-path string                 (for non-SOV blockchain only) file path of the removeValidator tx
--rpc string                            connect to validator manager at the given rpc endpoint
-t, --testnet                           fuji                         operate on testnet (alias to fuji)
--uptime uint                           validator's uptime in seconds. If not provided, it will be automatically calculated
--config string                         config file (default is $HOME/.avalanche-cli/config.json)
--log-level string                      log level for the application (default "ERROR")
--skip-update-check                     skip check for new versions
```

<a id="avalanche-blockchain-stats"></a>
### stats

The blockchain stats command prints validator statistics for the given Blockchain.

**Usage:**
```bash
avalanche blockchain stats [subcommand] [flags]
```

**Flags:**

```bash
--cluster string       operate on the given cluster
--devnet               operate on a devnet network
--endpoint string      use the given endpoint for network operations
-f, --fuji             testnet      operate on fuji (alias to testnet
-h, --help             help for stats
-l, --local            operate on a local network
-m, --mainnet          operate on mainnet
-t, --testnet          fuji      operate on testnet (alias to fuji)
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-blockchain-upgrade"></a>
### upgrade

The blockchain upgrade command suite provides a collection of tools for
updating your developmental and deployed Blockchains.

**Usage:**
```bash
avalanche blockchain upgrade [subcommand] [flags]
```

**Subcommands:**

- [`apply`](#avalanche-blockchain-upgrade-apply): Apply generated upgrade bytes to running Blockchain nodes to trigger a network upgrade.

For public networks (Fuji Testnet or Mainnet), to complete this process,
you must have access to the machine running your validator.
If the CLI is running on the same machine as your validator, it can manipulate your node's
configuration automatically. Alternatively, the command can print the necessary instructions
to upgrade your node manually.

After you update your validator's configuration, you need to restart your validator manually.
If you provide the --avalanchego-chain-config-dir flag, this command attempts to write the upgrade file at that path.
Refer to https://docs.avax.network/nodes/maintain/chain-config-flags#subnet-chain-configs for related documentation.
- [`export`](#avalanche-blockchain-upgrade-export): Export the upgrade bytes file to a location of choice on disk
- [`generate`](#avalanche-blockchain-upgrade-generate): The blockchain upgrade generate command builds a new upgrade.json file to customize your Blockchain. It
guides the user through the process using an interactive wizard.
- [`import`](#avalanche-blockchain-upgrade-import): Import the upgrade bytes file into the local environment
- [`print`](#avalanche-blockchain-upgrade-print): Print the upgrade.json file content
- [`vm`](#avalanche-blockchain-upgrade-vm): The blockchain upgrade vm command enables the user to upgrade their Blockchain's VM binary. The command
can upgrade both local Blockchains and publicly deployed Blockchains on Fuji and Mainnet.

The command walks the user through an interactive wizard. The user can skip the wizard by providing
command line flags.

**Flags:**

```bash
-h, --help             help for upgrade
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-blockchain-upgrade-apply"></a>
#### upgrade apply

Apply generated upgrade bytes to running Blockchain nodes to trigger a network upgrade.

For public networks (Fuji Testnet or Mainnet), to complete this process,
you must have access to the machine running your validator.
If the CLI is running on the same machine as your validator, it can manipulate your node's
configuration automatically. Alternatively, the command can print the necessary instructions
to upgrade your node manually.

After you update your validator's configuration, you need to restart your validator manually.
If you provide the --avalanchego-chain-config-dir flag, this command attempts to write the upgrade file at that path.
Refer to https://docs.avax.network/nodes/maintain/chain-config-flags#subnet-chain-configs for related documentation.

**Usage:**
```bash
avalanche blockchain upgrade apply [subcommand] [flags]
```

**Flags:**

```bash
--avalanchego-chain-config-dir string    avalanchego's chain config file directory (default "/home/runner/.avalanchego/chains")
--config                                 create upgrade config for future subnet deployments (same as generate)
--force                                  If true, don't prompt for confirmation of timestamps in the past
--fuji                                   fuji                             apply upgrade existing fuji deployment (alias for `testnet`)
-h, --help                               help for apply
--local                                  local                           apply upgrade existing local deployment
--mainnet                                mainnet                       apply upgrade existing mainnet deployment
--print                                  if true, print the manual config without prompting (for public networks only)
--testnet                                testnet                       apply upgrade existing testnet deployment (alias for `fuji`)
--log-level string                       log level for the application (default "ERROR")
--skip-update-check                      skip check for new versions
```

<a id="avalanche-blockchain-upgrade-export"></a>
#### upgrade export

Export the upgrade bytes file to a location of choice on disk

**Usage:**
```bash
avalanche blockchain upgrade export [subcommand] [flags]
```

**Flags:**

```bash
--force                      If true, overwrite a possibly existing file without prompting
-h, --help                   help for export
--upgrade-filepath string    Export upgrade bytes file to location of choice on disk
--config string              config file (default is $HOME/.avalanche-cli/config.json)
--log-level string           log level for the application (default "ERROR")
--skip-update-check          skip check for new versions
```

<a id="avalanche-blockchain-upgrade-generate"></a>
#### upgrade generate

The blockchain upgrade generate command builds a new upgrade.json file to customize your Blockchain. It
guides the user through the process using an interactive wizard.

**Usage:**
```bash
avalanche blockchain upgrade generate [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for generate
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-blockchain-upgrade-import"></a>
#### upgrade import

Import the upgrade bytes file into the local environment

**Usage:**
```bash
avalanche blockchain upgrade import [subcommand] [flags]
```

**Flags:**

```bash
-h, --help                   help for import
--upgrade-filepath string    Import upgrade bytes file into local environment
--config string              config file (default is $HOME/.avalanche-cli/config.json)
--log-level string           log level for the application (default "ERROR")
--skip-update-check          skip check for new versions
```

<a id="avalanche-blockchain-upgrade-print"></a>
#### upgrade print

Print the upgrade.json file content

**Usage:**
```bash
avalanche blockchain upgrade print [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for print
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-blockchain-upgrade-vm"></a>
#### upgrade vm

The blockchain upgrade vm command enables the user to upgrade their Blockchain's VM binary. The command
can upgrade both local Blockchains and publicly deployed Blockchains on Fuji and Mainnet.

The command walks the user through an interactive wizard. The user can skip the wizard by providing
command line flags.

**Usage:**
```bash
avalanche blockchain upgrade vm [subcommand] [flags]
```

**Flags:**

```bash
--binary string        Upgrade to custom binary
--config               upgrade config for future subnet deployments
--fuji                 fuji           upgrade existing fuji deployment (alias for `testnet`)
-h, --help             help for vm
--latest               upgrade to latest version
--local                local         upgrade existing local deployment
--mainnet              mainnet     upgrade existing mainnet deployment
--plugin-dir string    plugin directory to automatically upgrade VM
--print                print instructions for upgrading
--testnet              testnet     upgrade existing testnet deployment (alias for `fuji`)
--version string       Upgrade to custom version
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-blockchain-validators"></a>
### validators

The blockchain validators command lists the validators of a blockchain and provides
several statistics about them.

**Usage:**
```bash
avalanche blockchain validators [subcommand] [flags]
```

**Flags:**

```bash
--cluster string       operate on the given cluster
--devnet               operate on a devnet network
--endpoint string      use the given endpoint for network operations
-f, --fuji             testnet      operate on fuji (alias to testnet
-h, --help             help for validators
-l, --local            operate on a local network
-m, --mainnet          operate on mainnet
-t, --testnet          fuji      operate on testnet (alias to fuji)
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-blockchain-vmid"></a>
### vmid

The blockchain vmid command prints the virtual machine ID (VMID) for the given Blockchain.

**Usage:**
```bash
avalanche blockchain vmid [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for vmid
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-config"></a>
## avalanche config

Customize configuration for Avalanche-CLI

**Usage:**
```bash
avalanche config [subcommand] [flags]
```

**Subcommands:**

- [`authorize-cloud-access`](#avalanche-config-authorize-cloud-access): set preferences to authorize access to cloud resources
- [`metrics`](#avalanche-config-metrics): set user metrics collection preferences
- [`migrate`](#avalanche-config-migrate): migrate command migrates old ~/.avalanche-cli.json and ~/.avalanche-cli/config to /.avalanche-cli/config.json..
- [`snapshotsAutoSave`](#avalanche-config-snapshotsautosave): set user preference between auto saving local network snapshots or not
- [`update`](#avalanche-config-update): set user preference between update check or not

**Flags:**

```bash
-h, --help             help for config
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-config-authorize-cloud-access"></a>
### authorize-cloud-access

set preferences to authorize access to cloud resources

**Usage:**
```bash
avalanche config authorize-cloud-access [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for authorize-cloud-access
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-config-metrics"></a>
### metrics

set user metrics collection preferences

**Usage:**
```bash
avalanche config metrics [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for metrics
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-config-migrate"></a>
### migrate

migrate command migrates old ~/.avalanche-cli.json and ~/.avalanche-cli/config to /.avalanche-cli/config.json..

**Usage:**
```bash
avalanche config migrate [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for migrate
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-config-snapshotsautosave"></a>
### snapshotsAutoSave

set user preference between auto saving local network snapshots or not

**Usage:**
```bash
avalanche config snapshotsAutoSave [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for snapshotsAutoSave
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-config-update"></a>
### update

set user preference between update check or not

**Usage:**
```bash
avalanche config update [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for update
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-contract"></a>
## avalanche contract

The contract command suite provides a collection of tools for deploying
and interacting with smart contracts.

**Usage:**
```bash
avalanche contract [subcommand] [flags]
```

**Subcommands:**

- [`deploy`](#avalanche-contract-deploy): The contract command suite provides a collection of tools for deploying
smart contracts.
- [`initValidatorManager`](#avalanche-contract-initvalidatormanager): Initializes Proof of Authority(PoA) or Proof of Stake(PoS)Validator Manager contract on a Blockchain and sets up initial validator set on the Blockchain. For more info on Validator Manager, please head to https://github.com/ava-labs/icm-contracts/tree/main/contracts/validator-manager

**Flags:**

```bash
-h, --help             help for contract
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-contract-deploy"></a>
### deploy

The contract command suite provides a collection of tools for deploying
smart contracts.

**Usage:**
```bash
avalanche contract deploy [subcommand] [flags]
```

**Subcommands:**

- [`erc20`](#avalanche-contract-deploy-erc20): Deploy an ERC20 token into a given Network and Blockchain

**Flags:**

```bash
-h, --help             help for deploy
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-contract-deploy-erc20"></a>
#### deploy erc20

Deploy an ERC20 token into a given Network and Blockchain

**Usage:**
```bash
avalanche contract deploy erc20 [subcommand] [flags]
```

**Flags:**

```bash
--blockchain string       deploy the ERC20 contract into the given CLI blockchain
--blockchain-id string    deploy the ERC20 contract into the given blockchain ID/Alias
--c-chain                 deploy the ERC20 contract into C-Chain
--cluster string          operate on the given cluster
--devnet                  operate on a devnet network
--endpoint string         use the given endpoint for network operations
-f, --fuji                testnet           operate on fuji (alias to testnet
--funded string           set the funded address
--genesis-key             use genesis allocated key as contract deployer
-h, --help                help for erc20
--key string              CLI stored key to use as contract deployer
-l, --local               operate on a local network
-m, --mainnet             operate on mainnet
--private-key string      private key to use as contract deployer
--rpc string              deploy the contract into the given rpc endpoint
--supply uint             set the token supply
--symbol string           set the token symbol
-t, --testnet             fuji           operate on testnet (alias to fuji)
--config string           config file (default is $HOME/.avalanche-cli/config.json)
--log-level string        log level for the application (default "ERROR")
--skip-update-check       skip check for new versions
```

<a id="avalanche-contract-initvalidatormanager"></a>
### initValidatorManager

Initializes Proof of Authority(PoA) or Proof of Stake(PoS)Validator Manager contract on a Blockchain and sets up initial validator set on the Blockchain. For more info on Validator Manager, please head to https://github.com/ava-labs/icm-contracts/tree/main/contracts/validator-manager

**Usage:**
```bash
avalanche contract initValidatorManager [subcommand] [flags]
```

**Flags:**

```bash
--aggregator-allow-private-peers          allow the signature aggregator to connect to peers with private IP (default true)
--aggregator-extra-endpoints strings      endpoints for extra nodes that are needed in signature aggregation
--aggregator-log-level string             log level to use with signature aggregator (default "Debug")
--aggregator-log-to-stdout                dump signature aggregator logs to stdout
--cluster string                          operate on the given cluster
--devnet                                  operate on a devnet network
--endpoint string                         use the given endpoint for network operations
-f, --fuji                                testnet                           operate on fuji (alias to testnet
--genesis-key                             use genesis allocated key as contract deployer
-h, --help                                help for initValidatorManager
--key string                              CLI stored key to use as contract deployer
-l, --local                               operate on a local network
-m, --mainnet                             operate on mainnet
--pos-maximum-stake-amount uint           (PoS only) maximum stake amount (default 1000)
--pos-maximum-stake-multiplier            uint8     (PoS only )maximum stake multiplier (default 1)
--pos-minimum-delegation-fee uint16       (PoS only) minimum delegation fee (default 1)
--pos-minimum-stake-amount uint           (PoS only) minimum stake amount (default 1)
--pos-minimum-stake-duration uint         (PoS only) minimum stake duration (in seconds) (default 100)
--pos-reward-calculator-address string    (PoS only) initialize the ValidatorManager with reward calculator address
--pos-weight-to-value-factor uint         (PoS only) weight to value factor (default 1)
--private-key string                      private key to use as contract deployer
--rpc string                              deploy the contract into the given rpc endpoint
-t, --testnet                             fuji                           operate on testnet (alias to fuji)
--config string                           config file (default is $HOME/.avalanche-cli/config.json)
--log-level string                        log level for the application (default "ERROR")
--skip-update-check                       skip check for new versions
```

<a id="avalanche-help"></a>
## avalanche help

Help provides help for any command in the application.
Simply type avalanche help [path to command] for full details.

**Usage:**
```bash
avalanche help [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for help
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-icm"></a>
## avalanche icm

The messenger command suite provides a collection of tools for interacting
with ICM messenger contracts.

**Usage:**
```bash
avalanche icm [subcommand] [flags]
```

**Subcommands:**

- [`deploy`](#avalanche-icm-deploy): Deploys ICM Messenger and Registry into a given L1.
- [`sendMsg`](#avalanche-icm-sendmsg): Sends and wait reception for a ICM msg between two blockchains.

**Flags:**

```bash
-h, --help             help for icm
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-icm-deploy"></a>
### deploy

Deploys ICM Messenger and Registry into a given L1.

For Local Networks, it also deploys into C-Chain.

**Usage:**
```bash
avalanche icm deploy [subcommand] [flags]
```

**Flags:**

```bash
--blockchain string                         deploy ICM into the given CLI blockchain
--blockchain-id string                      deploy ICM into the given blockchain ID/Alias
--c-chain                                   deploy ICM into C-Chain
--cchain-key string                         key to be used to pay fees to deploy ICM to C-Chain
--cluster string                            operate on the given cluster
--deploy-messenger                          deploy ICM Messenger (default true)
--deploy-registry                           deploy ICM Registry (default true)
--devnet                                    operate on a devnet network
--endpoint string                           use the given endpoint for network operations
--force-registry-deploy                     deploy ICM Registry even if Messenger has already been deployed
-f, --fuji                                  testnet                             operate on fuji (alias to testnet
--genesis-key                               use genesis allocated key to fund ICM deploy
-h, --help                                  help for deploy
--include-cchain                            deploy ICM also to C-Chain
--key string                                CLI stored key to use to fund ICM deploy
-l, --local                                 operate on a local network
-m, --mainnet                               operate on mainnet
--messenger-contract-address-path string    path to a messenger contract address file
--messenger-deployer-address-path string    path to a messenger deployer address file
--messenger-deployer-tx-path string         path to a messenger deployer tx file
--private-key string                        private key to use to fund ICM deploy
--registry-bytecode-path string             path to a registry bytecode file
--rpc-url string                            use the given RPC URL to connect to the subnet
-t, --testnet                               fuji                             operate on testnet (alias to fuji)
--version string                            version to deploy (default "latest")
--config string                             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string                          log level for the application (default "ERROR")
--skip-update-check                         skip check for new versions
```

<a id="avalanche-icm-sendmsg"></a>
### sendMsg

Sends and wait reception for a ICM msg between two blockchains.

**Usage:**
```bash
avalanche icm sendMsg [subcommand] [flags]
```

**Flags:**

```bash
--cluster string                operate on the given cluster
--dest-rpc string               use the given destination blockchain rpc endpoint
--destination-address string    deliver the message to the given contract destination address
--devnet                        operate on a devnet network
--endpoint string               use the given endpoint for network operations
-f, --fuji                      testnet                 operate on fuji (alias to testnet
--genesis-key                   use genesis allocated key as message originator and to pay source blockchain fees
-h, --help                      help for sendMsg
--hex-encoded                   given message is hex encoded
--key string                    CLI stored key to use as message originator and to pay source blockchain fees
-l, --local                     operate on a local network
-m, --mainnet                   operate on mainnet
--private-key string            private key to use as message originator and to pay source blockchain fees
--source-rpc string             use the given source blockchain rpc endpoint
-t, --testnet                   fuji                 operate on testnet (alias to fuji)
--config string                 config file (default is $HOME/.avalanche-cli/config.json)
--log-level string              log level for the application (default "ERROR")
--skip-update-check             skip check for new versions
```

<a id="avalanche-ictt"></a>
## avalanche ictt

The ictt command suite provides tools to deploy and manage Interchain Token Transferrers.

**Usage:**
```bash
avalanche ictt [subcommand] [flags]
```

**Subcommands:**

- [`deploy`](#avalanche-ictt-deploy): Deploys a Token Transferrer into a given Network and Subnets

**Flags:**

```bash
-h, --help             help for ictt
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-ictt-deploy"></a>
### deploy

Deploys a Token Transferrer into a given Network and Subnets

**Usage:**
```bash
avalanche ictt deploy [subcommand] [flags]
```

**Flags:**

```bash
--c-chain-home                 set the Transferrer's Home Chain into C-Chain
--c-chain-remote               set the Transferrer's Remote Chain into C-Chain
--cluster string               operate on the given cluster
--deploy-erc20-home string     deploy a Transferrer Home for the given Chain's ERC20 Token
--deploy-native-home           deploy a Transferrer Home for the Chain's Native Token
--deploy-native-remote         deploy a Transferrer Remote for the Chain's Native Token
--devnet                       operate on a devnet network
--endpoint string              use the given endpoint for network operations
-f, --fuji                     testnet                  operate on fuji (alias to testnet
-h, --help                     help for deploy
--home-blockchain string       set the Transferrer's Home Chain into the given CLI blockchain
--home-genesis-key             use genesis allocated key to deploy Transferrer Home
--home-key string              CLI stored key to use to deploy Transferrer Home
--home-private-key string      private key to use to deploy Transferrer Home
--home-rpc string              use the given RPC URL to connect to the home blockchain
-l, --local                    operate on a local network
-m, --mainnet                  operate on mainnet
--remote-blockchain string     set the Transferrer's Remote Chain into the given CLI blockchain
--remote-genesis-key           use genesis allocated key to deploy Transferrer Remote
--remote-key string            CLI stored key to use to deploy Transferrer Remote
--remote-private-key string    private key to use to deploy Transferrer Remote
--remote-rpc string            use the given RPC URL to connect to the remote blockchain
--remote-token-decimals        uint8   use the given number of token decimals for the Transferrer Remote [defaults to token home's decimals (18 for a new wrapped native home token)]
--remove-minter-admin          remove the native minter precompile admin found on remote blockchain genesis
-t, --testnet                  fuji                  operate on testnet (alias to fuji)
--use-home string              use the given Transferrer's Home Address
--version string               tag/branch/commit of Avalanche Interchain Token Transfer (ICTT) to be used (defaults to main branch)
--config string                config file (default is $HOME/.avalanche-cli/config.json)
--log-level string             log level for the application (default "ERROR")
--skip-update-check            skip check for new versions
```

<a id="avalanche-interchain"></a>
## avalanche interchain

The interchain command suite provides a collection of tools to
set and manage interoperability between blockchains.

**Usage:**
```bash
avalanche interchain [subcommand] [flags]
```

**Subcommands:**

- [`messenger`](#avalanche-interchain-messenger): The messenger command suite provides a collection of tools for interacting
with ICM messenger contracts.
- [`relayer`](#avalanche-interchain-relayer): The relayer command suite provides a collection of tools for deploying
and configuring an ICM relayers.
- [`tokenTransferrer`](#avalanche-interchain-tokentransferrer): The tokenTransfer command suite provides tools to deploy and manage Token Transferrers.

**Flags:**

```bash
-h, --help             help for interchain
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-interchain-messenger"></a>
### messenger

The messenger command suite provides a collection of tools for interacting
with ICM messenger contracts.

**Usage:**
```bash
avalanche interchain messenger [subcommand] [flags]
```

**Subcommands:**

- [`deploy`](#avalanche-interchain-messenger-deploy): Deploys ICM Messenger and Registry into a given L1.
- [`sendMsg`](#avalanche-interchain-messenger-sendmsg): Sends and wait reception for a ICM msg between two blockchains.

**Flags:**

```bash
-h, --help             help for messenger
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-interchain-messenger-deploy"></a>
#### messenger deploy

Deploys ICM Messenger and Registry into a given L1.

For Local Networks, it also deploys into C-Chain.

**Usage:**
```bash
avalanche interchain messenger deploy [subcommand] [flags]
```

**Flags:**

```bash
--blockchain string                         deploy ICM into the given CLI blockchain
--blockchain-id string                      deploy ICM into the given blockchain ID/Alias
--c-chain                                   deploy ICM into C-Chain
--cchain-key string                         key to be used to pay fees to deploy ICM to C-Chain
--cluster string                            operate on the given cluster
--deploy-messenger                          deploy ICM Messenger (default true)
--deploy-registry                           deploy ICM Registry (default true)
--devnet                                    operate on a devnet network
--endpoint string                           use the given endpoint for network operations
--force-registry-deploy                     deploy ICM Registry even if Messenger has already been deployed
-f, --fuji                                  testnet                             operate on fuji (alias to testnet
--genesis-key                               use genesis allocated key to fund ICM deploy
-h, --help                                  help for deploy
--include-cchain                            deploy ICM also to C-Chain
--key string                                CLI stored key to use to fund ICM deploy
-l, --local                                 operate on a local network
-m, --mainnet                               operate on mainnet
--messenger-contract-address-path string    path to a messenger contract address file
--messenger-deployer-address-path string    path to a messenger deployer address file
--messenger-deployer-tx-path string         path to a messenger deployer tx file
--private-key string                        private key to use to fund ICM deploy
--registry-bytecode-path string             path to a registry bytecode file
--rpc-url string                            use the given RPC URL to connect to the subnet
-t, --testnet                               fuji                             operate on testnet (alias to fuji)
--version string                            version to deploy (default "latest")
--config string                             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string                          log level for the application (default "ERROR")
--skip-update-check                         skip check for new versions
```

<a id="avalanche-interchain-messenger-sendmsg"></a>
#### messenger sendMsg

Sends and wait reception for a ICM msg between two blockchains.

**Usage:**
```bash
avalanche interchain messenger sendMsg [subcommand] [flags]
```

**Flags:**

```bash
--cluster string                operate on the given cluster
--dest-rpc string               use the given destination blockchain rpc endpoint
--destination-address string    deliver the message to the given contract destination address
--devnet                        operate on a devnet network
--endpoint string               use the given endpoint for network operations
-f, --fuji                      testnet                 operate on fuji (alias to testnet
--genesis-key                   use genesis allocated key as message originator and to pay source blockchain fees
-h, --help                      help for sendMsg
--hex-encoded                   given message is hex encoded
--key string                    CLI stored key to use as message originator and to pay source blockchain fees
-l, --local                     operate on a local network
-m, --mainnet                   operate on mainnet
--private-key string            private key to use as message originator and to pay source blockchain fees
--source-rpc string             use the given source blockchain rpc endpoint
-t, --testnet                   fuji                 operate on testnet (alias to fuji)
--config string                 config file (default is $HOME/.avalanche-cli/config.json)
--log-level string              log level for the application (default "ERROR")
--skip-update-check             skip check for new versions
```

<a id="avalanche-interchain-relayer"></a>
### relayer

The relayer command suite provides a collection of tools for deploying
and configuring an ICM relayers.

**Usage:**
```bash
avalanche interchain relayer [subcommand] [flags]
```

**Subcommands:**

- [`deploy`](#avalanche-interchain-relayer-deploy): Deploys an ICM Relayer for the given Network.
- [`logs`](#avalanche-interchain-relayer-logs): Shows pretty formatted AWM relayer logs
- [`start`](#avalanche-interchain-relayer-start): Starts AWM relayer on the specified network (Currently only for local network).
- [`stop`](#avalanche-interchain-relayer-stop): Stops AWM relayer on the specified network (Currently only for local network, cluster).

**Flags:**

```bash
-h, --help             help for relayer
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-interchain-relayer-deploy"></a>
#### relayer deploy

Deploys an ICM Relayer for the given Network.

**Usage:**
```bash
avalanche interchain relayer deploy [subcommand] [flags]
```

**Flags:**

```bash
--allow-private-ips                allow relayer to connec to private ips (default true)
--amount float                     automatically fund l1s fee payments with the given amount
--bin-path string                  use the given relayer binary
--blockchain-funding-key string    key to be used to fund relayer account on all l1s
--blockchains strings              blockchains to relay as source and destination
--cchain                           relay C-Chain as source and destination
--cchain-amount float              automatically fund cchain fee payments with the given amount
--cchain-funding-key string        key to be used to fund relayer account on cchain
--cluster string                   operate on the given cluster
--devnet                           operate on a devnet network
--endpoint string                  use the given endpoint for network operations
-f, --fuji                         testnet                    operate on fuji (alias to testnet
-h, --help                         help for deploy
--key string                       key to be used by default both for rewards and to pay fees
-l, --local                        operate on a local network
--log-level string                 log level to use for relayer logs
-t, --testnet                      fuji                    operate on testnet (alias to fuji)
--version string                   version to deploy (default "latest-prerelease")
--config string                    config file (default is $HOME/.avalanche-cli/config.json)
--skip-update-check                skip check for new versions
```

<a id="avalanche-interchain-relayer-logs"></a>
#### relayer logs

Shows pretty formatted AWM relayer logs

**Usage:**
```bash
avalanche interchain relayer logs [subcommand] [flags]
```

**Flags:**

```bash
--endpoint string      use the given endpoint for network operations
--first uint           output first N log lines
-f, --fuji             testnet      operate on fuji (alias to testnet
-h, --help             help for logs
--last uint            output last N log lines
-l, --local            operate on a local network
--raw                  raw logs output
-t, --testnet          fuji      operate on testnet (alias to fuji)
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-interchain-relayer-start"></a>
#### relayer start

Starts AWM relayer on the specified network (Currently only for local network).

**Usage:**
```bash
avalanche interchain relayer start [subcommand] [flags]
```

**Flags:**

```bash
--bin-path string      use the given relayer binary
--cluster string       operate on the given cluster
--endpoint string      use the given endpoint for network operations
-f, --fuji             testnet      operate on fuji (alias to testnet
-h, --help             help for start
-l, --local            operate on a local network
-t, --testnet          fuji      operate on testnet (alias to fuji)
--version string       version to use (default "latest-prerelease")
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-interchain-relayer-stop"></a>
#### relayer stop

Stops AWM relayer on the specified network (Currently only for local network, cluster).

**Usage:**
```bash
avalanche interchain relayer stop [subcommand] [flags]
```

**Flags:**

```bash
--cluster string       operate on the given cluster
--endpoint string      use the given endpoint for network operations
-f, --fuji             testnet      operate on fuji (alias to testnet
-h, --help             help for stop
-l, --local            operate on a local network
-t, --testnet          fuji      operate on testnet (alias to fuji)
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-interchain-tokentransferrer"></a>
### tokenTransferrer

The tokenTransfer command suite provides tools to deploy and manage Token Transferrers.

**Usage:**
```bash
avalanche interchain tokenTransferrer [subcommand] [flags]
```

**Subcommands:**

- [`deploy`](#avalanche-interchain-tokentransferrer-deploy): Deploys a Token Transferrer into a given Network and Subnets

**Flags:**

```bash
-h, --help             help for tokenTransferrer
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-interchain-tokentransferrer-deploy"></a>
#### tokenTransferrer deploy

Deploys a Token Transferrer into a given Network and Subnets

**Usage:**
```bash
avalanche interchain tokenTransferrer deploy [subcommand] [flags]
```

**Flags:**

```bash
--c-chain-home                 set the Transferrer's Home Chain into C-Chain
--c-chain-remote               set the Transferrer's Remote Chain into C-Chain
--cluster string               operate on the given cluster
--deploy-erc20-home string     deploy a Transferrer Home for the given Chain's ERC20 Token
--deploy-native-home           deploy a Transferrer Home for the Chain's Native Token
--deploy-native-remote         deploy a Transferrer Remote for the Chain's Native Token
--devnet                       operate on a devnet network
--endpoint string              use the given endpoint for network operations
-f, --fuji                     testnet                  operate on fuji (alias to testnet
-h, --help                     help for deploy
--home-blockchain string       set the Transferrer's Home Chain into the given CLI blockchain
--home-genesis-key             use genesis allocated key to deploy Transferrer Home
--home-key string              CLI stored key to use to deploy Transferrer Home
--home-private-key string      private key to use to deploy Transferrer Home
--home-rpc string              use the given RPC URL to connect to the home blockchain
-l, --local                    operate on a local network
-m, --mainnet                  operate on mainnet
--remote-blockchain string     set the Transferrer's Remote Chain into the given CLI blockchain
--remote-genesis-key           use genesis allocated key to deploy Transferrer Remote
--remote-key string            CLI stored key to use to deploy Transferrer Remote
--remote-private-key string    private key to use to deploy Transferrer Remote
--remote-rpc string            use the given RPC URL to connect to the remote blockchain
--remote-token-decimals        uint8   use the given number of token decimals for the Transferrer Remote [defaults to token home's decimals (18 for a new wrapped native home token)]
--remove-minter-admin          remove the native minter precompile admin found on remote blockchain genesis
-t, --testnet                  fuji                  operate on testnet (alias to fuji)
--use-home string              use the given Transferrer's Home Address
--version string               tag/branch/commit of Avalanche Interchain Token Transfer (ICTT) to be used (defaults to main branch)
--config string                config file (default is $HOME/.avalanche-cli/config.json)
--log-level string             log level for the application (default "ERROR")
--skip-update-check            skip check for new versions
```

<a id="avalanche-key"></a>
## avalanche key

The key command suite provides a collection of tools for creating and managing
signing keys. You can use these keys to deploy Subnets to the Fuji Testnet,
but these keys are NOT suitable to use in production environments. DO NOT use
these keys on Mainnet.

To get started, use the key create command.

**Usage:**
```bash
avalanche key [subcommand] [flags]
```

**Subcommands:**

- [`create`](#avalanche-key-create): The key create command generates a new private key to use for creating and controlling
test Subnets. Keys generated by this command are NOT cryptographically secure enough to
use in production environments. DO NOT use these keys on Mainnet.

The command works by generating a secp256 key and storing it with the provided keyName. You
can use this key in other commands by providing this keyName.

If you'd like to import an existing key instead of generating one from scratch, provide the
--file flag.
- [`delete`](#avalanche-key-delete): The key delete command deletes an existing signing key.

To delete a key, provide the keyName. The command prompts for confirmation
before deleting the key. To skip the confirmation, provide the --force flag.
- [`export`](#avalanche-key-export): The key export command exports a created signing key. You can use an exported key in other
applications or import it into another instance of Avalanche-CLI.

By default, the tool writes the hex encoded key to stdout. If you provide the --output
flag, the command writes the key to a file of your choosing.
- [`list`](#avalanche-key-list): The key list command prints information for all stored signing
keys or for the ledger addresses associated to certain indices.
- [`transfer`](#avalanche-key-transfer): The key transfer command allows to transfer funds between stored keys or ledger addresses.

**Flags:**

```bash
-h, --help             help for key
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-key-create"></a>
### create

The key create command generates a new private key to use for creating and controlling
test Subnets. Keys generated by this command are NOT cryptographically secure enough to
use in production environments. DO NOT use these keys on Mainnet.

The command works by generating a secp256 key and storing it with the provided keyName. You
can use this key in other commands by providing this keyName.

If you'd like to import an existing key instead of generating one from scratch, provide the
--file flag.

**Usage:**
```bash
avalanche key create [subcommand] [flags]
```

**Flags:**

```bash
--file string          import the key from an existing key file
-f, --force            overwrite an existing key with the same name
-h, --help             help for create
--skip-balances        do not query public network balances for an imported key
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-key-delete"></a>
### delete

The key delete command deletes an existing signing key.

To delete a key, provide the keyName. The command prompts for confirmation
before deleting the key. To skip the confirmation, provide the --force flag.

**Usage:**
```bash
avalanche key delete [subcommand] [flags]
```

**Flags:**

```bash
-f, --force            delete the key without confirmation
-h, --help             help for delete
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-key-export"></a>
### export

The key export command exports a created signing key. You can use an exported key in other
applications or import it into another instance of Avalanche-CLI.

By default, the tool writes the hex encoded key to stdout. If you provide the --output
flag, the command writes the key to a file of your choosing.

**Usage:**
```bash
avalanche key export [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for export
-o, --output string    write the key to the provided file path
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-key-list"></a>
### list

The key list command prints information for all stored signing
keys or for the ledger addresses associated to certain indices.

**Usage:**
```bash
avalanche key list [subcommand] [flags]
```

**Flags:**

```bash
-a, --all-networks       list all network addresses
--blockchains strings    blockchains to show information about (p=p-chain, x=x-chain, c=c-chain, and blockchain names) (default p,x,c)
-c, --cchain             list C-Chain addresses (default true)
--cluster string         operate on the given cluster
--devnet                 operate on a devnet network
--endpoint string        use the given endpoint for network operations
-f, --fuji               testnet          operate on fuji (alias to testnet
-h, --help               help for list
--keys strings           list addresses for the given keys
-g, --ledger             uints          list ledger addresses for the given indices (default [])
-l, --local              operate on a local network
-m, --mainnet            operate on mainnet
--pchain                 list P-Chain addresses (default true)
--subnets strings        subnets to show information about (p=p-chain, x=x-chain, c=c-chain, and blockchain names) (default p,x,c)
-t, --testnet            fuji          operate on testnet (alias to fuji)
--tokens strings         provide balance information for the given token contract addresses (Evm only) (default [Native])
--use-gwei               use gwei for EVM balances
-n, --use-nano-avax      use nano Avax for balances
--xchain                 list X-Chain addresses (default true)
--config string          config file (default is $HOME/.avalanche-cli/config.json)
--log-level string       log level for the application (default "ERROR")
--skip-update-check      skip check for new versions
```

<a id="avalanche-key-transfer"></a>
### transfer

The key transfer command allows to transfer funds between stored keys or ledger addresses.

**Usage:**
```bash
avalanche key transfer [subcommand] [flags]
```

**Flags:**

```bash
-o, --amount float                          amount to send or receive (AVAX or TOKEN units)
--c-chain-receiver                          receive at C-Chain
--c-chain-sender                            send from C-Chain
--cluster string                            operate on the given cluster
-a, --destination-addr string               destination address
--destination-key string                    key associated to a destination address
--destination-subnet string                 subnet where the funds will be sent (token transferrer experimental)
--destination-transferrer-address string    token transferrer address at the destination subnet (token transferrer experimental)
--devnet                                    operate on a devnet network
--endpoint string                           use the given endpoint for network operations
-f, --fuji                                  testnet                             operate on fuji (alias to testnet
-h, --help                                  help for transfer
-k, --key string                            key associated to the sender or receiver address
-i, --ledger uint32                         ledger index associated to the sender or receiver address (default 32768)
-l, --local                                 operate on a local network
-m, --mainnet                               operate on mainnet
--origin-subnet string                      subnet where the funds belong (token transferrer experimental)
--origin-transferrer-address string         token transferrer address at the origin subnet (token transferrer experimental)
--p-chain-receiver                          receive at P-Chain
--p-chain-sender                            send from P-Chain
--receiver-blockchain string                receive at the given CLI blockchain
--receiver-blockchain-id string             receive at the given blockchain ID/Alias
--sender-blockchain string                  send from the given CLI blockchain
--sender-blockchain-id string               send from the given blockchain ID/Alias
-t, --testnet                               fuji                             operate on testnet (alias to fuji)
--x-chain-receiver                          receive at X-Chain
--x-chain-sender                            send from X-Chain
--config string                             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string                          log level for the application (default "ERROR")
--skip-update-check                         skip check for new versions
```

<a id="avalanche-network"></a>
## avalanche network

The network command suite provides a collection of tools for managing local Blockchain
deployments.

When you deploy a Blockchain locally, it runs on a local, multi-node Avalanche network. The
blockchain deploy command starts this network in the background. This command suite allows you
to shutdown, restart, and clear that network.

This network currently supports multiple, concurrently deployed Blockchains.

**Usage:**
```bash
avalanche network [subcommand] [flags]
```

**Subcommands:**

- [`clean`](#avalanche-network-clean): The network clean command shuts down your local, multi-node network. All deployed Subnets
shutdown and delete their state. You can restart the network by deploying a new Subnet
configuration.
- [`start`](#avalanche-network-start): The network start command starts a local, multi-node Avalanche network on your machine.

By default, the command loads the default snapshot. If you provide the --snapshot-name
flag, the network loads that snapshot instead. The command fails if the local network is
already running.
- [`status`](#avalanche-network-status): The network status command prints whether or not a local Avalanche
network is running and some basic stats about the network.
- [`stop`](#avalanche-network-stop): The network stop command shuts down your local, multi-node network.

All deployed Subnets shutdown gracefully and save their state. If you provide the
--snapshot-name flag, the network saves its state under this named snapshot. You can
reload this snapshot with network start --snapshot-name `snapshotName`. Otherwise, the
network saves to the default snapshot, overwriting any existing state. You can reload the
default snapshot with network start.

**Flags:**

```bash
-h, --help             help for network
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-network-clean"></a>
### clean

The network clean command shuts down your local, multi-node network. All deployed Subnets
shutdown and delete their state. You can restart the network by deploying a new Subnet
configuration.

**Usage:**
```bash
avalanche network clean [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for clean
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-network-start"></a>
### start

The network start command starts a local, multi-node Avalanche network on your machine.

By default, the command loads the default snapshot. If you provide the --snapshot-name
flag, the network loads that snapshot instead. The command fails if the local network is
already running.

**Usage:**
```bash
avalanche network start [subcommand] [flags]
```

**Flags:**

```bash
--avalanchego-path string       use this avalanchego binary path
--avalanchego-version string    use this version of avalanchego (ex: v1.17.12) (default "latest-prerelease")
-h, --help                      help for start
--num-nodes uint32              number of nodes to be created on local network (default 2)
--relayer-path string           use this relayer binary path
--relayer-version string        use this relayer version (default "latest-prerelease")
--snapshot-name string          name of snapshot to use to start the network from (default "default")
--config string                 config file (default is $HOME/.avalanche-cli/config.json)
--log-level string              log level for the application (default "ERROR")
--skip-update-check             skip check for new versions
```

<a id="avalanche-network-status"></a>
### status

The network status command prints whether or not a local Avalanche
network is running and some basic stats about the network.

**Usage:**
```bash
avalanche network status [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for status
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-network-stop"></a>
### stop

The network stop command shuts down your local, multi-node network.

All deployed Subnets shutdown gracefully and save their state. If you provide the
--snapshot-name flag, the network saves its state under this named snapshot. You can
reload this snapshot with network start --snapshot-name `snapshotName`. Otherwise, the
network saves to the default snapshot, overwriting any existing state. You can reload the
default snapshot with network start.

**Usage:**
```bash
avalanche network stop [subcommand] [flags]
```

**Flags:**

```bash
--dont-save               do not save snapshot, just stop the network
-h, --help                help for stop
--snapshot-name string    name of snapshot to use to save network state into (default "default")
--config string           config file (default is $HOME/.avalanche-cli/config.json)
--log-level string        log level for the application (default "ERROR")
--skip-update-check       skip check for new versions
```

<a id="avalanche-node"></a>
## avalanche node

The node command suite provides a collection of tools for creating and maintaining 
validators on Avalanche Network.

To get started, use the node create command wizard to walk through the
configuration to make your node a primary validator on Avalanche public network. You can use the 
rest of the commands to maintain your node and make your node a Subnet Validator.

**Usage:**
```bash
avalanche node [subcommand] [flags]
```

**Subcommands:**

- [`addDashboard`](#avalanche-node-adddashboard): (ALPHA Warning) This command is currently in experimental mode. 

The node addDashboard command adds custom dashboard to the Grafana monitoring dashboard for the 
cluster.
- [`create`](#avalanche-node-create): (ALPHA Warning) This command is currently in experimental mode. 

The node create command sets up a validator on a cloud server of your choice. 
The validator will be validating the Avalanche Primary Network and Subnet 
of your choice. By default, the command runs an interactive wizard. It 
walks you through all the steps you need to set up a validator.
Once this command is completed, you will have to wait for the validator
to finish bootstrapping on the primary network before running further
commands on it, e.g. validating a Subnet. You can check the bootstrapping
status by running avalanche node status 

The created node will be part of group of validators called `clusterName` 
and users can call node commands with `clusterName` so that the command
will apply to all nodes in the cluster
- [`destroy`](#avalanche-node-destroy): (ALPHA Warning) This command is currently in experimental mode.

The node destroy command terminates all running nodes in cloud server and deletes all storage disks.

If there is a static IP address attached, it will be released.
- [`devnet`](#avalanche-node-devnet): (ALPHA Warning) This command is currently in experimental mode.

The node devnet command suite provides a collection of commands related to devnets.
You can check the updated status by calling avalanche node status `clusterName`
- [`export`](#avalanche-node-export): (ALPHA Warning) This command is currently in experimental mode.

The node export command exports cluster configuration and its nodes config to a text file.

If no file is specified, the configuration is printed to the stdout.

Use --include-secrets to include keys in the export. In this case please keep the file secure as it contains sensitive information.

Exported cluster configuration without secrets can be imported by another user using node import command.
- [`import`](#avalanche-node-import): (ALPHA Warning) This command is currently in experimental mode.

The node import command imports cluster configuration and its nodes configuration from a text file
created from the node export command.

Prior to calling this command, call node whitelist command to have your SSH public key and IP whitelisted by
the cluster owner. This will enable you to use avalanche-cli commands to manage the imported cluster.

Please note, that this imported cluster will be considered as EXTERNAL by avalanche-cli, so some commands
affecting cloud nodes like node create or node destroy will be not applicable to it.
- [`list`](#avalanche-node-list): (ALPHA Warning) This command is currently in experimental mode.

The node list command lists all clusters together with their nodes.
- [`loadtest`](#avalanche-node-loadtest): (ALPHA Warning) This command is currently in experimental mode. 

The node loadtest command suite starts and stops a load test for an existing devnet cluster.
- [`local`](#avalanche-node-local): The node local command suite provides a collection of commands related to local nodes
- [`refresh-ips`](#avalanche-node-refresh-ips): (ALPHA Warning) This command is currently in experimental mode.

The node refresh-ips command obtains the current IP for all nodes with dynamic IPs in the cluster,
and updates the local node information used by CLI commands.
- [`resize`](#avalanche-node-resize): (ALPHA Warning) This command is currently in experimental mode.

The node resize command can change the amount of CPU, memory and disk space available for the cluster nodes.
- [`scp`](#avalanche-node-scp): (ALPHA Warning) This command is currently in experimental mode.

The node scp command securely copies files to and from nodes. Remote source or destionation can be specified using the following format:
[clusterName|nodeID|instanceID|IP]:/path/to/file. Regular expressions are supported for the source files like /tmp/*.txt.
File transfer to the nodes are parallelized. IF source or destination is cluster, the other should be a local file path. 
If both destinations are remote, they must be nodes for the same cluster and not clusters themselves.
For example:
$ avalanche node scp [cluster1|node1]:/tmp/file.txt /tmp/file.txt
$ avalanche node scp /tmp/file.txt [cluster1|NodeID-XXXX]:/tmp/file.txt
$ avalanche node scp node1:/tmp/file.txt NodeID-XXXX:/tmp/file.txt
- [`ssh`](#avalanche-node-ssh): (ALPHA Warning) This command is currently in experimental mode.

The node ssh command execute a given command [cmd] using ssh on all nodes in the cluster if ClusterName is given.
If no command is given, just prints the ssh command to be used to connect to each node in the cluster.
For provided NodeID or InstanceID or IP, the command [cmd] will be executed on that node.
If no [cmd] is provided for the node, it will open ssh shell there.
- [`status`](#avalanche-node-status): (ALPHA Warning) This command is currently in experimental mode.

The node status command gets the bootstrap status of all nodes in a cluster with the Primary Network. 
If no cluster is given, defaults to node list behaviour.

To get the bootstrap status of a node with a Blockchain, use --blockchain flag
- [`sync`](#avalanche-node-sync): (ALPHA Warning) This command is currently in experimental mode.

The node sync command enables all nodes in a cluster to be bootstrapped to a Blockchain.
You can check the blockchain bootstrap status by calling avalanche node status `clusterName` --blockchain `blockchainName`
- [`update`](#avalanche-node-update): (ALPHA Warning) This command is currently in experimental mode.

The node update command suite provides a collection of commands for nodes to update
their avalanchego or VM config.

You can check the status after update by calling avalanche node status
- [`upgrade`](#avalanche-node-upgrade): (ALPHA Warning) This command is currently in experimental mode.

The node update command suite provides a collection of commands for nodes to update
their avalanchego or VM version.

You can check the status after upgrade by calling avalanche node status
- [`validate`](#avalanche-node-validate): (ALPHA Warning) This command is currently in experimental mode.

The node validate command suite provides a collection of commands for nodes to join
the Primary Network and Subnets as validators.
If any of the commands is run before the nodes are bootstrapped on the Primary Network, the command 
will fail. You can check the bootstrap status by calling avalanche node status `clusterName`
- [`whitelist`](#avalanche-node-whitelist): (ALPHA Warning) The whitelist command suite provides a collection of tools for granting access to the cluster.

	Command adds IP if --ip params provided to cloud security access rules allowing it to access all nodes in the cluster via ssh or http.
	It also command adds SSH public key to all nodes in the cluster if --ssh params is there.
	If no params provided it detects current user IP automaticaly and whitelists it

**Flags:**

```bash
-h, --help             help for node
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-node-adddashboard"></a>
### addDashboard

(ALPHA Warning) This command is currently in experimental mode. 

The node addDashboard command adds custom dashboard to the Grafana monitoring dashboard for the 
cluster.

**Usage:**
```bash
avalanche node addDashboard [subcommand] [flags]
```

**Flags:**

```bash
--add-grafana-dashboard string    path to additional grafana dashboard json file
-h, --help                        help for addDashboard
--subnet string                   subnet that the dasbhoard is intended for (if any)
--config string                   config file (default is $HOME/.avalanche-cli/config.json)
--log-level string                log level for the application (default "ERROR")
--skip-update-check               skip check for new versions
```

<a id="avalanche-node-create"></a>
### create

(ALPHA Warning) This command is currently in experimental mode. 

The node create command sets up a validator on a cloud server of your choice. 
The validator will be validating the Avalanche Primary Network and Subnet 
of your choice. By default, the command runs an interactive wizard. It 
walks you through all the steps you need to set up a validator.
Once this command is completed, you will have to wait for the validator
to finish bootstrapping on the primary network before running further
commands on it, e.g. validating a Subnet. You can check the bootstrapping
status by running avalanche node status 

The created node will be part of group of validators called `clusterName` 
and users can call node commands with `clusterName` so that the command
will apply to all nodes in the cluster

**Usage:**
```bash
avalanche node create [subcommand] [flags]
```

**Flags:**

```bash
--add-grafana-dashboard string              path to additional grafana dashboard json file
--alternative-key-pair-name string          key pair name to use if default one generates conflicts
--authorize-access                          authorize CLI to create cloud resources
--auto-replace-keypair                      automatically replaces key pair to access node if previous key pair is not found
--avalanchego-version-from-subnet string    install latest avalanchego version, that is compatible with the given subnet, on node/s
--aws                                       create node/s in AWS cloud
--aws-profile string                        aws profile to use (default "default")
--aws-volume-iops int                       AWS iops (for gp3, io1, and io2 volume types only) (default 3000)
--aws-volume-size int                       AWS volume size in GB (default 1000)
--aws-volume-throughput int                 AWS throughput in MiB/s (for gp3 volume type only) (default 125)
--aws-volume-type string                    AWS volume type (default "gp3")
--bootstrap-ids                             stringArray                nodeIDs of bootstrap nodes
--bootstrap-ips                             stringArray                IP:port pairs of bootstrap nodes
--cluster string                            operate on the given cluster
--custom-avalanchego-version string         install given avalanchego version on node/s
--devnet                                    operate on a devnet network
--enable-monitoring                         set up Prometheus monitoring for created nodes. This option creates a separate monitoring cloud instance and incures additional cost
--endpoint string                           use the given endpoint for network operations
-f, --fuji                                  testnet                             operate on fuji (alias to testnet
--gcp                                       create node/s in GCP cloud
--gcp-credentials string                    use given GCP credentials
--gcp-project string                        use given GCP project
--genesis string                            path to genesis file
--grafana-pkg string                        use grafana pkg instead of apt repo(by default), for example https://dl.grafana.com/oss/release/grafana_10.4.1_amd64.deb
-h, --help                                  help for create
--latest-avalanchego-pre-release-version    install latest avalanchego pre-release version on node/s
--latest-avalanchego-version                install latest avalanchego release version on node/s
-m, --mainnet                               operate on mainnet
--node-type string                          cloud instance type. Use 'default' to use recommended default instance type
--num-apis                                  ints                            number of API nodes(nodes without stake) to create in the new Devnet
--num-validators                            ints                      number of nodes to create per region(s). Use comma to separate multiple numbers for each region in the same order as --region flag
--partial-sync                              primary network partial sync (default true)
--public-http-port                          allow public access to avalanchego HTTP port
--region strings                            create node(s) in given region(s). Use comma to separate multiple regions
--ssh-agent-identity string                 use given ssh identity(only for ssh agent). If not set, default will be used
-t, --testnet                               fuji                             operate on testnet (alias to fuji)
--upgrade string                            path to upgrade file
--use-ssh-agent                             use ssh agent(ex: Yubikey) for ssh auth
--use-static-ip                             attach static Public IP on cloud servers (default true)
--config string                             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string                          log level for the application (default "ERROR")
--skip-update-check                         skip check for new versions
```

<a id="avalanche-node-destroy"></a>
### destroy

(ALPHA Warning) This command is currently in experimental mode.

The node destroy command terminates all running nodes in cloud server and deletes all storage disks.

If there is a static IP address attached, it will be released.

**Usage:**
```bash
avalanche node destroy [subcommand] [flags]
```

**Flags:**

```bash
--all                   destroy all existing clusters created by Avalanche CLI
--authorize-access      authorize CLI to release cloud resources
-y, --authorize-all     authorize all CLI requests
--authorize-remove      authorize CLI to remove all local files related to cloud nodes
--aws-profile string    aws profile to use (default "default")
-h, --help              help for destroy
--config string         config file (default is $HOME/.avalanche-cli/config.json)
--log-level string      log level for the application (default "ERROR")
--skip-update-check     skip check for new versions
```

<a id="avalanche-node-devnet"></a>
### devnet

(ALPHA Warning) This command is currently in experimental mode.

The node devnet command suite provides a collection of commands related to devnets.
You can check the updated status by calling avalanche node status `clusterName`

**Usage:**
```bash
avalanche node devnet [subcommand] [flags]
```

**Subcommands:**

- [`deploy`](#avalanche-node-devnet-deploy): (ALPHA Warning) This command is currently in experimental mode.

The node devnet deploy command deploys a subnet into a devnet cluster, creating subnet and blockchain txs for it.
It saves the deploy info both locally and remotely.
- [`wiz`](#avalanche-node-devnet-wiz): (ALPHA Warning) This command is currently in experimental mode.

The node wiz command creates a devnet and deploys, sync and validate a subnet into it. It creates the subnet if so needed.

**Flags:**

```bash
-h, --help             help for devnet
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-node-devnet-deploy"></a>
#### devnet deploy

(ALPHA Warning) This command is currently in experimental mode.

The node devnet deploy command deploys a subnet into a devnet cluster, creating subnet and blockchain txs for it.
It saves the deploy info both locally and remotely.

**Usage:**
```bash
avalanche node devnet deploy [subcommand] [flags]
```

**Flags:**

```bash
-h, --help                  help for deploy
--no-checks                 do not check for healthy status or rpc compatibility of nodes against subnet
--subnet-aliases strings    additional subnet aliases to be used for RPC calls in addition to subnet blockchain name
--subnet-only               only create a subnet
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check         skip check for new versions
```

<a id="avalanche-node-devnet-wiz"></a>
#### devnet wiz

(ALPHA Warning) This command is currently in experimental mode.

The node wiz command creates a devnet and deploys, sync and validate a subnet into it. It creates the subnet if so needed.

**Usage:**
```bash
avalanche node devnet wiz [subcommand] [flags]
```

**Flags:**

```bash
--add-grafana-dashboard string                         path to additional grafana dashboard json file
--alternative-key-pair-name string                     key pair name to use if default one generates conflicts
--authorize-access                                     authorize CLI to create cloud resources
--auto-replace-keypair                                 automatically replaces key pair to access node if previous key pair is not found
--aws                                                  create node/s in AWS cloud
--aws-profile string                                   aws profile to use (default "default")
--aws-volume-iops int                                  AWS iops (for gp3, io1, and io2 volume types only) (default 3000)
--aws-volume-size int                                  AWS volume size in GB (default 1000)
--aws-volume-throughput int                            AWS throughput in MiB/s (for gp3 volume type only) (default 125)
--aws-volume-type string                               AWS volume type (default "gp3")
--chain-config string                                  path to the chain configuration for subnet
--custom-avalanchego-version string                    install given avalanchego version on node/s
--custom-subnet                                        use a custom VM as the subnet virtual machine
--custom-vm-branch string                              custom vm branch or commit
--custom-vm-build-script string                        custom vm build-script
--custom-vm-repo-url string                            custom vm repository url
--default-validator-params                             use default weight/start/duration params for subnet validator
--deploy-icm-messenger                                 deploy Interchain Messenger (default true)
--deploy-icm-registry                                  deploy Interchain Registry (default true)
--deploy-teleporter-messenger                          deploy Interchain Messenger (default true)
--deploy-teleporter-registry                           deploy Interchain Registry (default true)
--enable-monitoring                                    set up Prometheus monitoring for created nodes. Please note that this option creates a separate monitoring instance and incures additional cost
--evm-chain-id uint                                    chain ID to use with Subnet-EVM
--evm-defaults                                         use default production settings with Subnet-EVM
--evm-production-defaults                              use default production settings for your blockchain
--evm-subnet                                           use Subnet-EVM as the subnet virtual machine
--evm-test-defaults                                    use default test settings for your blockchain
--evm-token string                                     token name to use with Subnet-EVM
--evm-version string                                   version of Subnet-EVM to use
--force-subnet-create                                  overwrite the existing subnet configuration if one exists
--gcp                                                  create node/s in GCP cloud
--gcp-credentials string                               use given GCP credentials
--gcp-project string                                   use given GCP project
--grafana-pkg string                                   use grafana pkg instead of apt repo(by default), for example https://dl.grafana.com/oss/release/grafana_10.4.1_amd64.deb
-h, --help                                             help for wiz
--icm                                                  generate an icm-ready vm
--icm-messenger-contract-address-path string           path to an icm messenger contract address file
--icm-messenger-deployer-address-path string           path to an icm messenger deployer address file
--icm-messenger-deployer-tx-path string                path to an icm messenger deployer tx file
--icm-registry-bytecode-path string                    path to an icm registry bytecode file
--icm-version string                                   icm version to deploy (default "latest")
--latest-avalanchego-pre-release-version               install latest avalanchego pre-release version on node/s
--latest-avalanchego-version                           install latest avalanchego release version on node/s
--latest-evm-version                                   use latest Subnet-EVM released version
--latest-pre-released-evm-version                      use latest Subnet-EVM pre-released version
--node-config string                                   path to avalanchego node configuration for subnet
--node-type string                                     cloud instance type. Use 'default' to use recommended default instance type
--num-apis                                             ints                                       number of API nodes(nodes without stake) to create in the new Devnet
--num-validators                                       ints                                 number of nodes to create per region(s). Use comma to separate multiple numbers for each region in the same order as --region flag
--public-http-port                                     allow public access to avalanchego HTTP port
--region strings                                       create node/s in given region(s). Use comma to separate multiple regions
--relayer                                              run AWM relayer when deploying the vm
--ssh-agent-identity string                            use given ssh identity(only for ssh agent). If not set, default will be used.
--subnet-aliases strings                               additional subnet aliases to be used for RPC calls in addition to subnet blockchain name
--subnet-config string                                 path to the subnet configuration for subnet
--subnet-genesis string                                file path of the subnet genesis
--teleporter                                           generate an icm-ready vm
--teleporter-messenger-contract-address-path string    path to an icm messenger contract address file
--teleporter-messenger-deployer-address-path string    path to an icm messenger deployer address file
--teleporter-messenger-deployer-tx-path string         path to an icm messenger deployer tx file
--teleporter-registry-bytecode-path string             path to an icm registry bytecode file
--teleporter-version string                            icm version to deploy (default "latest")
--use-ssh-agent                                        use ssh agent for ssh
--use-static-ip                                        attach static Public IP on cloud servers (default true)
--validators strings                                   deploy subnet into given comma separated list of validators. defaults to all cluster nodes
--config string                                        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string                                     log level for the application (default "ERROR")
--skip-update-check                                    skip check for new versions
```

<a id="avalanche-node-export"></a>
### export

(ALPHA Warning) This command is currently in experimental mode.

The node export command exports cluster configuration and its nodes config to a text file.

If no file is specified, the configuration is printed to the stdout.

Use --include-secrets to include keys in the export. In this case please keep the file secure as it contains sensitive information.

Exported cluster configuration without secrets can be imported by another user using node import command.

**Usage:**
```bash
avalanche node export [subcommand] [flags]
```

**Flags:**

```bash
--file string          specify the file to export the cluster configuration to
--force                overwrite the file if it exists
-h, --help             help for export
--include-secrets      include keys in the export
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-node-import"></a>
### import

(ALPHA Warning) This command is currently in experimental mode.

The node import command imports cluster configuration and its nodes configuration from a text file
created from the node export command.

Prior to calling this command, call node whitelist command to have your SSH public key and IP whitelisted by
the cluster owner. This will enable you to use avalanche-cli commands to manage the imported cluster.

Please note, that this imported cluster will be considered as EXTERNAL by avalanche-cli, so some commands
affecting cloud nodes like node create or node destroy will be not applicable to it.

**Usage:**
```bash
avalanche node import [subcommand] [flags]
```

**Flags:**

```bash
--file string          specify the file to export the cluster configuration to
-h, --help             help for import
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-node-list"></a>
### list

(ALPHA Warning) This command is currently in experimental mode.

The node list command lists all clusters together with their nodes.

**Usage:**
```bash
avalanche node list [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for list
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-node-loadtest"></a>
### loadtest

(ALPHA Warning) This command is currently in experimental mode. 

The node loadtest command suite starts and stops a load test for an existing devnet cluster.

**Usage:**
```bash
avalanche node loadtest [subcommand] [flags]
```

**Subcommands:**

- [`start`](#avalanche-node-loadtest-start): (ALPHA Warning) This command is currently in experimental mode. 

The node loadtest command starts load testing for an existing devnet cluster. If the cluster does 
not have an existing load test host, the command creates a separate cloud server and builds the load 
test binary based on the provided load test Git Repo URL and load test binary build command. 

The command will then run the load test binary based on the provided load test run command.
- [`stop`](#avalanche-node-loadtest-stop): (ALPHA Warning) This command is currently in experimental mode. 

The node loadtest stop command stops load testing for an existing devnet cluster and terminates the 
separate cloud server created to host the load test.

**Flags:**

```bash
-h, --help             help for loadtest
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-node-loadtest-start"></a>
#### loadtest start

(ALPHA Warning) This command is currently in experimental mode. 

The node loadtest command starts load testing for an existing devnet cluster. If the cluster does 
not have an existing load test host, the command creates a separate cloud server and builds the load 
test binary based on the provided load test Git Repo URL and load test binary build command. 

The command will then run the load test binary based on the provided load test run command.

**Usage:**
```bash
avalanche node loadtest start [subcommand] [flags]
```

**Flags:**

```bash
--authorize-access              authorize CLI to create cloud resources
--aws                           create loadtest node in AWS cloud
--aws-profile string            aws profile to use (default "default")
--gcp                           create loadtest in GCP cloud
-h, --help                      help for start
--load-test-branch string       load test branch or commit
--load-test-build-cmd string    command to build load test binary
--load-test-cmd string          command to run load test
--load-test-repo string         load test repo url to use
--node-type string              cloud instance type for loadtest script
--region string                 create load test node in a given region
--ssh-agent-identity string     use given ssh identity(only for ssh agent). If not set, default will be used
--use-ssh-agent                 use ssh agent(ex: Yubikey) for ssh auth
--config string                 config file (default is $HOME/.avalanche-cli/config.json)
--log-level string              log level for the application (default "ERROR")
--skip-update-check             skip check for new versions
```

<a id="avalanche-node-loadtest-stop"></a>
#### loadtest stop

(ALPHA Warning) This command is currently in experimental mode. 

The node loadtest stop command stops load testing for an existing devnet cluster and terminates the 
separate cloud server created to host the load test.

**Usage:**
```bash
avalanche node loadtest stop [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for stop
--load-test strings    stop specified load test node(s). Use comma to separate multiple load test instance names
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-node-local"></a>
### local

The node local command suite provides a collection of commands related to local nodes

**Usage:**
```bash
avalanche node local [subcommand] [flags]
```

**Subcommands:**

- [`destroy`](#avalanche-node-local-destroy): Cleanup local node.
- [`start`](#avalanche-node-local-start): The node local start command creates Avalanche nodes on the local machine.
Once this command is completed, you will have to wait for the Avalanche node
to finish bootstrapping on the primary network before running further
commands on it, e.g. validating a Subnet. 

You can check the bootstrapping status by running avalanche node status local.
- [`status`](#avalanche-node-local-status): Get status of local node.
- [`stop`](#avalanche-node-local-stop): Stop local node.
- [`track`](#avalanche-node-local-track): Track specified blockchain with local node
- [`validate`](#avalanche-node-local-validate): Use Avalanche Node set up on local machine to set up specified L1 by providing the
RPC URL of the L1. 

This command can only be used to validate Proof of Stake L1.

**Flags:**

```bash
-h, --help             help for local
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-node-local-destroy"></a>
#### local destroy

Cleanup local node.

**Usage:**
```bash
avalanche node local destroy [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for destroy
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-node-local-start"></a>
#### local start

The node local start command creates Avalanche nodes on the local machine.
Once this command is completed, you will have to wait for the Avalanche node
to finish bootstrapping on the primary network before running further
commands on it, e.g. validating a Subnet. 

You can check the bootstrapping status by running avalanche node status local.

**Usage:**
```bash
avalanche node local start [subcommand] [flags]
```

**Flags:**

```bash
--avalanchego-path string                   use this avalanchego binary path
--bootstrap-id                              stringArray                 nodeIDs of bootstrap nodes
--bootstrap-ip                              stringArray                 IP:port pairs of bootstrap nodes
--cluster string                            operate on the given cluster
--custom-avalanchego-version string         install given avalanchego version on node/s
--devnet                                    operate on a devnet network
--endpoint string                           use the given endpoint for network operations
-f, --fuji                                  testnet                             operate on fuji (alias to testnet
--genesis string                            path to genesis file
-h, --help                                  help for start
--latest-avalanchego-pre-release-version    install latest avalanchego pre-release version on node/s (default true)
--latest-avalanchego-version                install latest avalanchego release version on node/s
-l, --local                                 operate on a local network
-m, --mainnet                               operate on mainnet
--node-config string                        path to common avalanchego config settings for all nodes
--num-nodes uint32                          number of Avalanche nodes to create on local machine (default 1)
--partial-sync                              primary network partial sync (default true)
--staking-cert-key-path string              path to provided staking cert key for node
--staking-signer-key-path string            path to provided staking signer key for node
--staking-tls-key-path string               path to provided staking tls key for node
-t, --testnet                               fuji                             operate on testnet (alias to fuji)
--upgrade string                            path to upgrade file
--config string                             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string                          log level for the application (default "ERROR")
--skip-update-check                         skip check for new versions
```

<a id="avalanche-node-local-status"></a>
#### local status

Get status of local node.

**Usage:**
```bash
avalanche node local status [subcommand] [flags]
```

**Flags:**

```bash
--blockchain string    specify the blockchain the node is syncing with
-h, --help             help for status
--l1 string            specify the blockchain the node is syncing with
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-node-local-stop"></a>
#### local stop

Stop local node.

**Usage:**
```bash
avalanche node local stop [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for stop
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-node-local-track"></a>
#### local track

Track specified blockchain with local node

**Usage:**
```bash
avalanche node local track [subcommand] [flags]
```

**Flags:**

```bash
--avalanchego-path string                   use this avalanchego binary path
--custom-avalanchego-version string         install given avalanchego version on node/s
-h, --help                                  help for track
--latest-avalanchego-pre-release-version    install latest avalanchego pre-release version on node/s (default true)
--latest-avalanchego-version                install latest avalanchego release version on node/s
--config string                             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string                          log level for the application (default "ERROR")
--skip-update-check                         skip check for new versions
```

<a id="avalanche-node-local-validate"></a>
#### local validate

Use Avalanche Node set up on local machine to set up specified L1 by providing the
RPC URL of the L1. 

This command can only be used to validate Proof of Stake L1.

**Usage:**
```bash
avalanche node local validate [subcommand] [flags]
```

**Flags:**

```bash
--aggregator-log-level string       log level to use with signature aggregator (default "Debug")
--aggregator-log-to-stdout          use stdout for signature aggregator logs
--balance float                     amount of AVAX to increase validator's balance by
--blockchain string                 specify the blockchain the node is syncing with
--delegation-fee uint16             delegation fee (in bips) (default 100)
--disable-owner string              P-Chain address that will able to disable the validator with a P-Chain transaction
-h, --help                          help for validate
--l1 string                         specify the blockchain the node is syncing with
--minimum-stake-duration uint       minimum stake duration (in seconds) (default 100)
--remaining-balance-owner string    P-Chain address that will receive any leftover AVAX from the validator when it is removed from Subnet
--rpc string                        connect to validator manager at the given rpc endpoint
--stake-amount uint                 amount of tokens to stake
--config string                     config file (default is $HOME/.avalanche-cli/config.json)
--log-level string                  log level for the application (default "ERROR")
--skip-update-check                 skip check for new versions
```

<a id="avalanche-node-refresh-ips"></a>
### refresh-ips

(ALPHA Warning) This command is currently in experimental mode.

The node refresh-ips command obtains the current IP for all nodes with dynamic IPs in the cluster,
and updates the local node information used by CLI commands.

**Usage:**
```bash
avalanche node refresh-ips [subcommand] [flags]
```

**Flags:**

```bash
--aws-profile string    aws profile to use (default "default")
-h, --help              help for refresh-ips
--config string         config file (default is $HOME/.avalanche-cli/config.json)
--log-level string      log level for the application (default "ERROR")
--skip-update-check     skip check for new versions
```

<a id="avalanche-node-resize"></a>
### resize

(ALPHA Warning) This command is currently in experimental mode.

The node resize command can change the amount of CPU, memory and disk space available for the cluster nodes.

**Usage:**
```bash
avalanche node resize [subcommand] [flags]
```

**Flags:**

```bash
--aws-profile string    aws profile to use (default "default")
--disk-size string      Disk size to resize in Gb (e.g. 1000Gb)
-h, --help              help for resize
--node-type string      Node type to resize (e.g. t3.2xlarge)
--config string         config file (default is $HOME/.avalanche-cli/config.json)
--log-level string      log level for the application (default "ERROR")
--skip-update-check     skip check for new versions
```

<a id="avalanche-node-scp"></a>
### scp

(ALPHA Warning) This command is currently in experimental mode.

The node scp command securely copies files to and from nodes. Remote source or destionation can be specified using the following format:
[clusterName|nodeID|instanceID|IP]:/path/to/file. Regular expressions are supported for the source files like /tmp/*.txt.
File transfer to the nodes are parallelized. IF source or destination is cluster, the other should be a local file path. 
If both destinations are remote, they must be nodes for the same cluster and not clusters themselves.
For example:
$ avalanche node scp [cluster1|node1]:/tmp/file.txt /tmp/file.txt
$ avalanche node scp /tmp/file.txt [cluster1|NodeID-XXXX]:/tmp/file.txt
$ avalanche node scp node1:/tmp/file.txt NodeID-XXXX:/tmp/file.txt

**Usage:**
```bash
avalanche node scp [subcommand] [flags]
```

**Flags:**

```bash
--compress             use compression for ssh
-h, --help             help for scp
--recursive            copy directories recursively
--with-loadtest        include loadtest node for scp cluster operations
--with-monitor         include monitoring node for scp cluster operations
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-node-ssh"></a>
### ssh

(ALPHA Warning) This command is currently in experimental mode.

The node ssh command execute a given command [cmd] using ssh on all nodes in the cluster if ClusterName is given.
If no command is given, just prints the ssh command to be used to connect to each node in the cluster.
For provided NodeID or InstanceID or IP, the command [cmd] will be executed on that node.
If no [cmd] is provided for the node, it will open ssh shell there.

**Usage:**
```bash
avalanche node ssh [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for ssh
--parallel             run ssh command on all nodes in parallel
--with-loadtest        include loadtest node for ssh cluster operations
--with-monitor         include monitoring node for ssh cluster operations
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-node-status"></a>
### status

(ALPHA Warning) This command is currently in experimental mode.

The node status command gets the bootstrap status of all nodes in a cluster with the Primary Network. 
If no cluster is given, defaults to node list behaviour.

To get the bootstrap status of a node with a Blockchain, use --blockchain flag

**Usage:**
```bash
avalanche node status [subcommand] [flags]
```

**Flags:**

```bash
--blockchain string    specify the blockchain the node is syncing with
-h, --help             help for status
--subnet string        specify the blockchain the node is syncing with
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-node-sync"></a>
### sync

(ALPHA Warning) This command is currently in experimental mode.

The node sync command enables all nodes in a cluster to be bootstrapped to a Blockchain.
You can check the blockchain bootstrap status by calling avalanche node status `clusterName` --blockchain `blockchainName`

**Usage:**
```bash
avalanche node sync [subcommand] [flags]
```

**Flags:**

```bash
-h, --help                  help for sync
--no-checks                 do not check for bootstrapped/healthy status or rpc compatibility of nodes against subnet
--subnet-aliases strings    subnet alias to be used for RPC calls. defaults to subnet blockchain ID
--validators strings        sync subnet into given comma separated list of validators. defaults to all cluster nodes
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check         skip check for new versions
```

<a id="avalanche-node-update"></a>
### update

(ALPHA Warning) This command is currently in experimental mode.

The node update command suite provides a collection of commands for nodes to update
their avalanchego or VM config.

You can check the status after update by calling avalanche node status

**Usage:**
```bash
avalanche node update [subcommand] [flags]
```

**Subcommands:**

- [`subnet`](#avalanche-node-update-subnet): (ALPHA Warning) This command is currently in experimental mode.

The node update subnet command updates all nodes in a cluster with latest Subnet configuration and VM for custom VM.
You can check the updated subnet bootstrap status by calling avalanche node status `clusterName` --subnet `subnetName`

**Flags:**

```bash
-h, --help             help for update
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-node-update-subnet"></a>
#### update subnet

(ALPHA Warning) This command is currently in experimental mode.

The node update subnet command updates all nodes in a cluster with latest Subnet configuration and VM for custom VM.
You can check the updated subnet bootstrap status by calling avalanche node status `clusterName` --subnet `subnetName`

**Usage:**
```bash
avalanche node update subnet [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for subnet
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-node-upgrade"></a>
### upgrade

(ALPHA Warning) This command is currently in experimental mode.

The node update command suite provides a collection of commands for nodes to update
their avalanchego or VM version.

You can check the status after upgrade by calling avalanche node status

**Usage:**
```bash
avalanche node upgrade [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for upgrade
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-node-validate"></a>
### validate

(ALPHA Warning) This command is currently in experimental mode.

The node validate command suite provides a collection of commands for nodes to join
the Primary Network and Subnets as validators.
If any of the commands is run before the nodes are bootstrapped on the Primary Network, the command 
will fail. You can check the bootstrap status by calling avalanche node status `clusterName`

**Usage:**
```bash
avalanche node validate [subcommand] [flags]
```

**Subcommands:**

- [`primary`](#avalanche-node-validate-primary): (ALPHA Warning) This command is currently in experimental mode.

The node validate primary command enables all nodes in a cluster to be validators of Primary
Network.
- [`subnet`](#avalanche-node-validate-subnet): (ALPHA Warning) This command is currently in experimental mode.

The node validate subnet command enables all nodes in a cluster to be validators of a Subnet.
If the command is run before the nodes are Primary Network validators, the command will first
make the nodes Primary Network validators before making them Subnet validators. 
If The command is run before the nodes are bootstrapped on the Primary Network, the command will fail. 
You can check the bootstrap status by calling avalanche node status `clusterName`
If The command is run before the nodes are synced to the subnet, the command will fail.
You can check the subnet sync status by calling avalanche node status `clusterName` --subnet `subnetName`

**Flags:**

```bash
-h, --help             help for validate
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-node-validate-primary"></a>
#### validate primary

(ALPHA Warning) This command is currently in experimental mode.

The node validate primary command enables all nodes in a cluster to be validators of Primary
Network.

**Usage:**
```bash
avalanche node validate primary [subcommand] [flags]
```

**Flags:**

```bash
-e, --ewoq                   use ewoq key [fuji/devnet only]
-h, --help                   help for primary
-k, --key string             select the key to use [fuji only]
-g, --ledger                 use ledger instead of key (always true on mainnet, defaults to false on fuji/devnet)
--ledger-addrs strings       use the given ledger addresses
--stake-amount uint          how many AVAX to stake in the validator
--staking-period duration    how long validator validates for after start time
--start-time string          UTC start time when this validator starts validating, in 'YYYY-MM-DD HH:MM:SS' format
--config string              config file (default is $HOME/.avalanche-cli/config.json)
--log-level string           log level for the application (default "ERROR")
--skip-update-check          skip check for new versions
```

<a id="avalanche-node-validate-subnet"></a>
#### validate subnet

(ALPHA Warning) This command is currently in experimental mode.

The node validate subnet command enables all nodes in a cluster to be validators of a Subnet.
If the command is run before the nodes are Primary Network validators, the command will first
make the nodes Primary Network validators before making them Subnet validators. 
If The command is run before the nodes are bootstrapped on the Primary Network, the command will fail. 
You can check the bootstrap status by calling avalanche node status `clusterName`
If The command is run before the nodes are synced to the subnet, the command will fail.
You can check the subnet sync status by calling avalanche node status `clusterName` --subnet `subnetName`

**Usage:**
```bash
avalanche node validate subnet [subcommand] [flags]
```

**Flags:**

```bash
--default-validator-params    use default weight/start/duration params for subnet validator
-e, --ewoq                    use ewoq key [fuji/devnet only]
-h, --help                    help for subnet
-k, --key string              select the key to use [fuji/devnet only]
-g, --ledger                  use ledger instead of key (always true on mainnet, defaults to false on fuji/devnet)
--ledger-addrs strings        use the given ledger addresses
--no-checks                   do not check for bootstrapped status or healthy status
--no-validation-checks        do not check if subnet is already synced or validated (default true)
--stake-amount uint           how many AVAX to stake in the validator
--staking-period duration     how long validator validates for after start time
--start-time string           UTC start time when this validator starts validating, in 'YYYY-MM-DD HH:MM:SS' format
--validators strings          validate subnet for the given comma separated list of validators. defaults to all cluster nodes
--config string               config file (default is $HOME/.avalanche-cli/config.json)
--log-level string            log level for the application (default "ERROR")
--skip-update-check           skip check for new versions
```

<a id="avalanche-node-whitelist"></a>
### whitelist

(ALPHA Warning) The whitelist command suite provides a collection of tools for granting access to the cluster.

	Command adds IP if --ip params provided to cloud security access rules allowing it to access all nodes in the cluster via ssh or http.
	It also command adds SSH public key to all nodes in the cluster if --ssh params is there.
	If no params provided it detects current user IP automaticaly and whitelists it

**Usage:**
```bash
avalanche node whitelist [subcommand] [flags]
```

**Flags:**

```bash
-y, --current-ip       whitelist current host ip
-h, --help             help for whitelist
--ip string            ip address to whitelist
--ssh string           ssh public key to whitelist
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-primary"></a>
## avalanche primary

The primary command suite provides a collection of tools for interacting with the
Primary Network

**Usage:**
```bash
avalanche primary [subcommand] [flags]
```

**Subcommands:**

- [`addValidator`](#avalanche-primary-addvalidator): The primary addValidator command adds a node as a validator 
in the Primary Network
- [`describe`](#avalanche-primary-describe): The subnet describe command prints details of the primary network configuration to the console.

**Flags:**

```bash
-h, --help             help for primary
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-primary-addvalidator"></a>
### addValidator

The primary addValidator command adds a node as a validator 
in the Primary Network

**Usage:**
```bash
avalanche primary addValidator [subcommand] [flags]
```

**Flags:**

```bash
--cluster string                operate on the given cluster
--delegation-fee uint32         set the delegation fee (20 000 is equivalent to 2%)
--devnet                        operate on a devnet network
--endpoint string               use the given endpoint for network operations
-f, --fuji                      testnet                 operate on fuji (alias to testnet
-h, --help                      help for addValidator
-k, --key string                select the key to use [fuji only]
-g, --ledger                    use ledger instead of key (always true on mainnet, defaults to false on fuji)
--ledger-addrs strings          use the given ledger addresses
-m, --mainnet                   operate on mainnet
--nodeID string                 set the NodeID of the validator to add
--proof-of-possession string    set the BLS proof of possession of the validator to add
--public-key string             set the BLS public key of the validator to add
--staking-period duration       how long this validator will be staking
--start-time string             UTC start time when this validator starts validating, in 'YYYY-MM-DD HH:MM:SS' format
-t, --testnet                   fuji                 operate on testnet (alias to fuji)
--weight uint                   set the staking weight of the validator to add
--config string                 config file (default is $HOME/.avalanche-cli/config.json)
--log-level string              log level for the application (default "ERROR")
--skip-update-check             skip check for new versions
```

<a id="avalanche-primary-describe"></a>
### describe

The subnet describe command prints details of the primary network configuration to the console.

**Usage:**
```bash
avalanche primary describe [subcommand] [flags]
```

**Flags:**

```bash
--cluster string       operate on the given cluster
-h, --help             help for describe
-l, --local            operate on a local network
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-transaction"></a>
## avalanche transaction

The transaction command suite provides all of the utilities required to sign multisig transactions.

**Usage:**
```bash
avalanche transaction [subcommand] [flags]
```

**Subcommands:**

- [`commit`](#avalanche-transaction-commit): The transaction commit command commits a transaction by submitting it to the P-Chain.
- [`sign`](#avalanche-transaction-sign): The transaction sign command signs a multisig transaction.

**Flags:**

```bash
-h, --help             help for transaction
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-transaction-commit"></a>
### commit

The transaction commit command commits a transaction by submitting it to the P-Chain.

**Usage:**
```bash
avalanche transaction commit [subcommand] [flags]
```

**Flags:**

```bash
-h, --help                    help for commit
--input-tx-filepath string    Path to the transaction signed by all signatories
--config string               config file (default is $HOME/.avalanche-cli/config.json)
--log-level string            log level for the application (default "ERROR")
--skip-update-check           skip check for new versions
```

<a id="avalanche-transaction-sign"></a>
### sign

The transaction sign command signs a multisig transaction.

**Usage:**
```bash
avalanche transaction sign [subcommand] [flags]
```

**Flags:**

```bash
-h, --help                    help for sign
--input-tx-filepath string    Path to the transaction file for signing
-k, --key string              select the key to use [fuji only]
-g, --ledger                  use ledger instead of key (always true on mainnet, defaults to false on fuji)
--ledger-addrs strings        use the given ledger addresses
--config string               config file (default is $HOME/.avalanche-cli/config.json)
--log-level string            log level for the application (default "ERROR")
--skip-update-check           skip check for new versions
```

<a id="avalanche-update"></a>
## avalanche update

Check if an update is available, and prompt the user to install it

**Usage:**
```bash
avalanche update [subcommand] [flags]
```

**Flags:**

```bash
-c, --confirm          Assume yes for installation
-h, --help             help for update
-v, --version          version for update
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-validator"></a>
## avalanche validator

The validator command suite provides a collection of tools for managing validator
balance on P-Chain.

Validator's balance is used to pay for continuous fee to the P-Chain. When this Balance reaches 0, 
the validator will be considered inactive and will no longer participate in validating the L1

**Usage:**
```bash
avalanche validator [subcommand] [flags]
```

**Subcommands:**

- [`getBalance`](#avalanche-validator-getbalance): This command gets the remaining validator P-Chain balance that is available to pay
P-Chain continuous fee
- [`increaseBalance`](#avalanche-validator-increasebalance): This command increases the validator P-Chain balance
- [`list`](#avalanche-validator-list): This command gets a list of the validators of the L1

**Flags:**

```bash
-h, --help             help for validator
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-validator-getbalance"></a>
### getBalance

This command gets the remaining validator P-Chain balance that is available to pay
P-Chain continuous fee

**Usage:**
```bash
avalanche validator getBalance [subcommand] [flags]
```

**Flags:**

```bash
--cluster string          operate on the given cluster
--devnet                  operate on a devnet network
--endpoint string         use the given endpoint for network operations
-f, --fuji                testnet           operate on fuji (alias to testnet
-h, --help                help for getBalance
--l1 string               name of L1
-l, --local               operate on a local network
-m, --mainnet             operate on mainnet
--node-id string          node ID of the validator
-t, --testnet             fuji           operate on testnet (alias to fuji)
--validation-id string    validation ID of the validator
--config string           config file (default is $HOME/.avalanche-cli/config.json)
--log-level string        log level for the application (default "ERROR")
--skip-update-check       skip check for new versions
```

<a id="avalanche-validator-increasebalance"></a>
### increaseBalance

This command increases the validator P-Chain balance

**Usage:**
```bash
avalanche validator increaseBalance [subcommand] [flags]
```

**Flags:**

```bash
--balance float           amount of AVAX to increase validator's balance by
--cluster string          operate on the given cluster
--devnet                  operate on a devnet network
--endpoint string         use the given endpoint for network operations
-f, --fuji                testnet           operate on fuji (alias to testnet
-h, --help                help for increaseBalance
-k, --key string          select the key to use [fuji/devnet deploy only]
--l1 string               name of L1 (to increase balance of bootstrap validators only)
-l, --local               operate on a local network
-m, --mainnet             operate on mainnet
--node-id string          node ID of the validator
-t, --testnet             fuji           operate on testnet (alias to fuji)
--validation-id string    validationIDStr of the validator
--config string           config file (default is $HOME/.avalanche-cli/config.json)
--log-level string        log level for the application (default "ERROR")
--skip-update-check       skip check for new versions
```

<a id="avalanche-validator-list"></a>
### list

This command gets a list of the validators of the L1

**Usage:**
```bash
avalanche validator list [subcommand] [flags]
```

**Flags:**

```bash
--cluster string       operate on the given cluster
--devnet               operate on a devnet network
--endpoint string      use the given endpoint for network operations
-f, --fuji             testnet      operate on fuji (alias to testnet
-h, --help             help for list
-l, --local            operate on a local network
-m, --mainnet          operate on mainnet
-t, --testnet          fuji      operate on testnet (alias to fuji)
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

# RPC APIs (/docs/rpcs)

---
title: RPC APIs
description: AvalancheGo RPC API References for interacting with Avalanche nodes
---

# RPC APIs

This section contains comprehensive documentation for all RPC (Remote Procedure Call) APIs available in the Avalanche ecosystem.

## Chain-Specific APIs

### C-Chain (Contract Chain)
The C-Chain is an instance of the Ethereum Virtual Machine (EVM). Documentation for C-Chain RPC methods and transaction formats.

### P-Chain (Platform Chain)
The P-Chain manages validators, staking, and subnets. Documentation for P-Chain RPC methods and transaction formats.

### X-Chain (Exchange Chain)
The X-Chain is responsible for asset creation and trading. Documentation for X-Chain RPC methods and transaction formats.

### Subnet-EVM
The Subnet-EVM is an instance of the EVM for Subnet / Layer 1 chains. Documentation for Subnet-EVM RPC methods and transaction formats.

## Other APIs

Additional RPC APIs for node administration, health monitoring, indexing, metrics, and more.



# Introduction (/docs/virtual-machines/evm-l1-customization)

---
title: Introduction
description: Learn how to customize the Ethereum Virtual Machine with EVM and Precompiles.
root: true
---

Welcome to the EVM customization guide. This documentation provides an overview of **EVM**, the purpose of **Validator Manager Contracts**, the capabilities of **precompiles**, and how you can create custom precompiles to extend the functionality of the Ethereum Virtual Machine (EVM).

## Overview of EVM

EVM is Avalanche's customized version of the Ethereum Virtual Machine, tailored to run on Avalanche L1s. It allows developers to deploy Solidity smart contracts with enhanced capabilities, benefiting from Avalanche's high throughput and low latency. EVM enables more flexibility and performance optimizations compared to the standard EVM.

## Validator Manager Contracts

Validator Manager Contracts (VMCs) are smart contracts that manage the validators of an L1. They allow you to define rules and criteria for validator participation directly within smart contracts. VMCs enable dynamic validator sets, making it easier to add or remove validators without requiring a network restart. This provides greater control over the L1's validator management and enhances network governance.

## Precompiles

Precompiles are specialized smart contracts that execute native Go code within the EVM context. They act as a bridge between Solidity and lower-level functionalities, allowing for performance optimizations and access to features not available in Solidity alone.

### Default Precompiles in EVM

EVM comes with a set of default precompiles that extend the EVM's functionality. For detailed documentation on each precompile, visit the [Avalanche L1s Precompiles](/docs/avalanche-l1s/evm-configuration/evm-l1-customization#precompiles) section:

- [AllowList](/docs/avalanche-l1s/evm-configuration/allowlist): A reusable interface for permission management
- [Permissions](/docs/avalanche-l1s/evm-configuration/permissions): Control contract deployment and transaction submission
- [Tokenomics](/docs/avalanche-l1s/evm-configuration/tokenomics): Manage native token supply and minting
- [Transaction Fees](/docs/avalanche-l1s/evm-configuration/transaction-fees): Configure fee parameters and reward mechanisms
- [Warp Messenger](/docs/avalanche-l1s/evm-configuration/warpmessenger): Perform cross-chain operations

## Custom Precompiles

One of the powerful features of EVM is the ability to create custom precompiles. By writing Go code and integrating it as a precompile, you can extend the EVM's functionality to suit specific use cases. Custom precompiles allow you to:

- Achieve higher performance for computationally intensive tasks.
- Access lower-level system functions not available in Solidity.
- Implement custom cryptographic functions or algorithms.
- Interact with external systems or data sources.

Creating custom precompiles opens up a wide range of possibilities for developers to optimize and expand their decentralized applications on Avalanche L1s.

By leveraging EVM, Validator Manager Contracts, and precompiles, you can build customized and efficient decentralized applications with greater control and enhanced functionality. Explore the following sections to learn how to implement and utilize these powerful features.


# Introduction (/docs/virtual-machines)

---
title: Introduction
description: Learn about the execution layer of a blockchain network.
---

A Virtual Machine (VM) is a blueprint for a blockchain. Blockchains are instantiated from a VM, similar to how objects are instantiated from a class definition. VMs can define anything you want, but will generally define transactions that are executed and how blocks are created.

## Blocks and State

Virtual Machines deal with blocks and state. The functionality provided by VMs is to:

- Define the representation of a blockchain's state
- Represent the operations in that state
- Apply the operations in that state

Each block in the blockchain contains a set of state transitions. Each block is applied in order from the blockchain's initial genesis block to its last accepted block to reach the latest state of the blockchain.

## Blockchain

A blockchain relies on two major components: The **Consensus Engine** and the **VM**. The VM defines application specific behavior and how blocks are built and parsed to create the blockchain. All VMs run on top of the Avalanche Consensus Engine, which allows nodes in the network to agree on the state of the blockchain. Here's a quick example of how VMs interact with consensus:

1.  A node wants to update the blockchain's state
2.  The node's VM will notify the consensus engine that it wants to update the state
3.  The consensus engine will request the block from the VM
4.  The consensus engine will verify the returned block using the VM's implementation of `Verify()`
5.  The consensus engine will get the network to reach consensus on whether to accept or reject the newly verified block. Every virtuous (well-behaved) node on the network will have the same preference for a particular block
6.  Depending upon the consensus results, the engine will either accept or reject the block. What happens when a block is accepted or rejected is specific to the implementation of the VM

AvalancheGo provides the consensus engine for every blockchain on the Avalanche Network. The consensus engine relies on the VM interface to handle building, parsing, and storing blocks as well as verifying and executing on behalf of the consensus engine.

This decoupling between the application and consensus layer allows developers to build their applications quickly by implementing virtual machines, without having to worry about the consensus layer managed by Avalanche which deals with how nodes agree on whether or not to accept a block.

## Installing a VM

VMs are supplied as binaries to a node running `AvalancheGo`. These binaries must be named the VM's assigned **VMID**. A VMID is a 32-byte hash encoded in CB58 that is generated when you build your VM.

In order to install a VM, its binary must be installed in the `AvalancheGo` plugin path. See [here](/docs/nodes/configure/configs-flags#--plugin-dir-string) for more details. Multiple VMs can be installed in this location.

Each VM runs as a separate process from AvalancheGo and communicates with `AvalancheGo` using gRPC calls. This functionality is enabled by **RPCChainVM**, a special VM which wraps around other VM implementations and bridges the VM and AvalancheGo, establishing a standardized communication protocol between them.

<Callout title="Note">
During VM creation, handshake messages are exchanged via **RPCChainVM** between AvalancheGo and the VM installation. Ensure matching **RPCChainVM** protocol versions to avoid errors, by updating your VM or using a [different version of AvalancheGo](https://github.com/ava-labs/AvalancheGo/releases).

Note that some VMs may not support the latest protocol version.
</Callout>

### API Handlers

Users can interact with a blockchain and its VM through handlers exposed by the VM's API.

VMs expose two types of handlers to serve responses for incoming requests:

- **Blockchain Handlers**: Referred to as handlers, these expose APIs to interact with a blockchain instantiated by a VM. The API endpoint will be different for each chain. The endpoint for a handler is `/ext/bc/[chainID]`.
- **VM Handlers**: Referred to as static handlers, these expose APIs to interact with the VM directly. One example API would be to parse genesis data to instantiate a new blockchain. The endpoint for a static handler is `/ext/vm/[vmID]`.

For any readers familiar with object-oriented programming, static and non-static handlers on a VM are analogous to static and non-static methods on a class. Blockchain handlers can be thought of as methods on an object, whereas VM handlers can be thought of as static methods on a class.

### Instantiate a VM

The `vm.Factory` interface is implemented to create new VM instances from which a blockchain can be initialized. The factory's `New` method shown below provides `AvalancheGo` with an instance of the VM. It's defined in the [`factory.go`](https://github.com/ava-labs/timestampvm/blob/main/timestampvm/factory.go) file of the `timestampvm` repository.

```go
// Returning a new VM instance from VM's factory
func (f *Factory) New(*snow.Context) (interface{}, error) { return &vm.VM{}, nil }
```

### Initializing a VM to Create a Blockchain

Before a VM can run, AvalancheGo will initialize it by invoking its `Initialize` method. Here, the VM will bootstrap itself and sets up anything it requires before it starts running.

This might involve setting up its database, mempool, genesis state, or anything else the VM requires to run.

```go
if err := vm.Initialize(
    ctx.Context,
    vmDBManager,
    genesisData,
    chainConfig.Upgrade,
    chainConfig.Config,
    msgChan,
    fxs,
    sender,
);
```

You can refer to the [implementation](https://github.com/ava-labs/timestampvm/blob/main/timestampvm/vm.go#L75) of `vm.initialize` in the TimestampVM repository.

## Interfaces

Every VM should implement the following interfaces:

### `block.ChainVM`

To reach a consensus on linear blockchains, Avalanche uses the Snowman consensus engine. To be compatible with Snowman, a VM must implement the `block.ChainVM` interface.

For more information, see [here](https://github.com/ava-labs/avalanchego/blob/master/snow/engine/snowman/block/vm.go).

```go title="snow/engine/snowman/block/vm.go"
// ChainVM defines the required functionality of a Snowman VM.
//
// A Snowman VM is responsible for defining the representation of the state,
// the representation of operations in that state, the application of operations
// on that state, and the creation of the operations. Consensus will decide on
// if the operation is executed and the order operations are executed.
//
// For example, suppose we have a VM that tracks an increasing number that
// is agreed upon by the network.
// The state is a single number.
// The operation is setting the number to a new, larger value.
// Applying the operation will save to the database the new value.
// The VM can attempt to issue a new number, of larger value, at any time.
// Consensus will ensure the network agrees on the number at every block height.
type ChainVM interface {
	common.VM
	Getter
	Parser

	// Attempt to create a new block from data contained in the VM.
	//
	// If the VM doesn't want to issue a new block, an error should be
	// returned.
	BuildBlock() (snowman.Block, error)

	// Notify the VM of the currently preferred block.
	//
	// This should always be a block that has no children known to consensus.
	SetPreference(ids.ID) error

	// LastAccepted returns the ID of the last accepted block.
	//
	// If no blocks have been accepted by consensus yet, it is assumed there is
	// a definitionally accepted block, the Genesis block, that will be
	// returned.
	LastAccepted() (ids.ID, error)
}

// Getter defines the functionality for fetching a block by its ID.
type Getter interface {
	// Attempt to load a block.
	//
	// If the block does not exist, an error should be returned.
	//
	GetBlock(ids.ID) (snowman.Block, error)
}

// Parser defines the functionality for fetching a block by its bytes.
type Parser interface {
	// Attempt to create a block from a stream of bytes.
	//
	// The block should be represented by the full byte array, without extra
	// bytes.
	ParseBlock([]byte) (snowman.Block, error)
}
```

### `common.VM`

`common.VM` is a type that every `VM` must implement. For more information, you can see the full file [here](https://github.com/ava-labs/avalanchego/blob/master/snow/engine/common/vm.go).

```go title="snow/engine/common/vm.go"
// VM describes the interface that all consensus VMs must implement
type VM interface {
    // Contains handlers for VM-to-VM specific messages
	AppHandler

	// Returns nil if the VM is healthy.
	// Periodically called and reported via the node's Health API.
	health.Checkable

	// Connector represents a handler that is called on connection connect/disconnect
	validators.Connector

	// Initialize this VM.
	// [ctx]: Metadata about this VM.
	//     [ctx.networkID]: The ID of the network this VM's chain is running on.
	//     [ctx.chainID]: The unique ID of the chain this VM is running on.
	//     [ctx.Log]: Used to log messages
	//     [ctx.NodeID]: The unique staker ID of this node.
	//     [ctx.Lock]: A Read/Write lock shared by this VM and the consensus
	//                 engine that manages this VM. The write lock is held
	//                 whenever code in the consensus engine calls the VM.
	// [dbManager]: The manager of the database this VM will persist data to.
	// [genesisBytes]: The byte-encoding of the genesis information of this
	//                 VM. The VM uses it to initialize its state. For
	//                 example, if this VM were an account-based payments
	//                 system, `genesisBytes` would probably contain a genesis
	//                 transaction that gives coins to some accounts, and this
	//                 transaction would be in the genesis block.
	// [toEngine]: The channel used to send messages to the consensus engine.
	// [fxs]: Feature extensions that attach to this VM.
	Initialize(
		ctx *snow.Context,
		dbManager manager.Manager,
		genesisBytes []byte,
		upgradeBytes []byte,
		configBytes []byte,
		toEngine chan<- Message,
		fxs []*Fx,
		appSender AppSender,
	) error

	// Bootstrapping is called when the node is starting to bootstrap this chain.
	Bootstrapping() error

	// Bootstrapped is called when the node is done bootstrapping this chain.
	Bootstrapped() error

	// Shutdown is called when the node is shutting down.
	Shutdown() error

	// Version returns the version of the VM this node is running.
	Version() (string, error)

	// Creates the HTTP handlers for custom VM network calls.
	//
	// This exposes handlers that the outside world can use to communicate with
	// a static reference to the VM. Each handler has the path:
	// [Address of node]/ext/VM/[VM ID]/[extension]
	//
	// Returns a mapping from [extension]s to HTTP handlers.
	//
	// Each extension can specify how locking is managed for convenience.
	//
	// For example, it might make sense to have an extension for creating
	// genesis bytes this VM can interpret.
	CreateStaticHandlers() (map[string]*HTTPHandler, error)

	// Creates the HTTP handlers for custom chain network calls.
	//
	// This exposes handlers that the outside world can use to communicate with
	// the chain. Each handler has the path:
	// [Address of node]/ext/bc/[chain ID]/[extension]
	//
	// Returns a mapping from [extension]s to HTTP handlers.
	//
	// Each extension can specify how locking is managed for convenience.
	//
	// For example, if this VM implements an account-based payments system,
	// it have an extension called `accounts`, where clients could get
	// information about their accounts.
	CreateHandlers() (map[string]*HTTPHandler, error)
}
```

### `snowman.Block`

The `snowman.Block` interface It define the functionality a block must implement to be a block in a linear Snowman chain. For more information, you can see the full file [here](https://github.com/ava-labs/avalanchego/blob/master/snow/consensus/snowman/block.go).

```go title="snow/consensus/snowman/block.go"
// Block is a possible decision that dictates the next canonical block.
//
// Blocks are guaranteed to be Verified, Accepted, and Rejected in topological
// order. Specifically, if Verify is called, then the parent has already been
// verified. If Accept is called, then the parent has already been accepted. If
// Reject is called, the parent has already been accepted or rejected.
//
// If the status of the block is Unknown, ID is assumed to be able to be called.
// If the status of the block is Accepted or Rejected; Parent, Verify, Accept,
// and Reject will never be called.
type Block interface {
    choices.Decidable

    // Parent returns the ID of this block's parent.
    Parent() ids.ID

    // Verify that the state transition this block would make if accepted is
    // valid. If the state transition is invalid, a non-nil error should be
    // returned.
    //
    // It is guaranteed that the Parent has been successfully verified.
    Verify() error

    // Bytes returns the binary representation of this block.
    //
    // This is used for sending blocks to peers. The bytes should be able to be
    // parsed into the same block on another node.
    Bytes() []byte

    // Height returns the height of this block in the chain.
    Height() uint64
}
```

### `choices.Decidable`

This interface is a superset of every decidable object, such as transactions, blocks, and vertices. For more information, you can see the full file [here](https://github.com/ava-labs/avalanchego/blob/master/snow/choices/decidable.go).

```go title="snow/choices/decidable.go"
// Decidable represents element that can be decided.
//
// Decidable objects are typically thought of as either transactions, blocks, or
// vertices.
type Decidable interface {
	// ID returns a unique ID for this element.
	//
	// Typically, this is implemented by using a cryptographic hash of a
	// binary representation of this element. An element should return the same
	// IDs upon repeated calls.
	ID() ids.ID

	// Accept this element.
	//
	// This element will be accepted by every correct node in the network.
	Accept() error

	// Reject this element.
	//
	// This element will not be accepted by any correct node in the network.
	Reject() error

	// Status returns this element's current status.
	//
	// If Accept has been called on an element with this ID, Accepted should be
	// returned. Similarly, if Reject has been called on an element with this
	// ID, Rejected should be returned. If the contents of this element are
	// unknown, then Unknown should be returned. Otherwise, Processing should be
	// returned.
	Status() Status
}
```


# Manage VM Binaries (/docs/virtual-machines/manage-vm-binaries)

---
title: Manage VM Binaries
description: Learn about Avalanche  Plugin Manager (APM) and how to use it to manage virtual machines binaries on existing AvalancheGo instances.
---

Avalanche Plugin Manager (APM) is a command-line tool to manage virtual machines binaries on existing AvalancheGo instances. It enables to add/remove nodes to Avalanche L1s, upgrade the VM plugin binaries as new versions get released to the plugin repository.

GitHub: [https://github.com/ava-labs/apm](https://github.com/ava-labs/apm)

## `avalanche-plugins-core`

`avalanche-plugins-core` is plugin repository that ships with the `apm`. A plugin repository consists of a set of virtual machine and Avalanche L1 definitions that the `apm` consumes to allow users to quickly and easily download and manage VM binaries.

GitHub: [https://github.com/ava-labs/avalanche-plugins-core](https://github.com/ava-labs/avalanche-plugins-core)

# Simple VM in Any Language (/docs/virtual-machines/simple-vm-any-language)

---
title: Simple VM in Any Language
description: Learn how to implement a simple virtual machine in any language.
---

This is a language-agnostic high-level documentation explaining the basics of how to get started at implementing your own virtual machine from scratch.

Avalanche virtual machines are grpc servers implementing Avalanche's [Proto interfaces](https://buf.build/ava-labs/avalanche). This means that it can be done in [any language that has a grpc implementation](https://grpc.io/docs/languages/).

## Minimal Implementation

To get the process started, at the minimum, you will to implement the following interfaces:

- [`vm.Runtime`](https://buf.build/ava-labs/avalanche/docs/main:vm.runtime) (Client)
- [`vm.VM`](https://buf.build/ava-labs/avalanche/docs/main:vm) (Server)

To build a blockchain taking advantage of AvalancheGo's consensus to build blocks, you will need to implement:

- [AppSender](https://buf.build/ava-labs/avalanche/docs/main:appsender) (Client)
- [Messenger](https://buf.build/ava-labs/avalanche/docs/main:messenger) (Client)

To have a json-RPC endpoint, `/ext/bc/subnetId/rpc` exposed by AvalancheGo, you will need to implement:

- [`Http`](https://buf.build/ava-labs/avalanche/docs/main:http) (Server)

You can and should use a tool like `buf` to generate the (Client/Server) code from the interfaces as stated in the [Avalanche module](https://buf.build/ava-labs/avalanche)'s page.

<Callout title="Note">
There are _server_ and _client_ interfaces to implement. AvalancheGo calls the _server_ interfaces exposed by your VM and your VM calls the _client_ interfaces exposed by AvalancheGo.
</Callout>

## Starting Process

Your VM is started by AvalancheGo launching your binary. Your binary is started as a sub-process of AvalancheGo. While launching your binary, AvalancheGo passes an environment variable `AVALANCHE_VM_RUNTIME_ENGINE_ADDR` containing an url. We must use this url to initialize a `vm.Runtime` client.

Your VM, after having started a grpc server implementing the VM interface must call the [`vm.Runtime.InitializeRequest`](https://buf.build/ava-labs/avalanche/docs/main:vm.runtime#vm.runtime.InitializeRequest) with the following parameters.

- `protocolVersion`: It must match the `supported plugin version` of the [AvalancheGo release](https://github.com/ava-labs/AvalancheGo/releases) you are using. It is always part of the release notes.  
- `addr`: It is your grpc server's address. It must be in the following format `host:port` (example `localhost:12345`)
    
## VM Initialization

The service methods are described in the same order as they are called. You will need to implement these methods in your server.

### Pre-Initialization Sequence

AvalancheGo starts/stops your process multiple times before launching the real initialization sequence.

1. [VM.Version](https://buf.build/ava-labs/avalanche/docs/main:vm#vm.VM.Version)
    - Return: your VM's version.
2. [VM.CreateStaticHandler](https://buf.build/ava-labs/avalanche/docs/main:vm#vm.VM.CreateStaticHandlers)
    - Return: an empty array - (Not absolutely required).
3. [VM.Shutdown](https://buf.build/ava-labs/avalanche/docs/main:vm#vm.VM.Shutdown)
    - You should gracefully stop your process.
    - Return: Empty

### Initialization Sequence

1. [VM.CreateStaticHandlers](https://buf.build/ava-labs/avalanche/docs/main:vm#vm.VM.CreateStaticHandlers)
    - Return an empty array - (Not absolutely required).
2. [VM.Initialize](https://buf.build/ava-labs/avalanche/docs/main:vm#vm.VM.Initialize)
    - Param: an [InitializeRequest](https://buf.build/ava-labs/avalanche/docs/main:vm#vm.InitializeRequest).
    - You must use this data to initialize your VM.
    - You should add the genesis block to your blockchain and set it as the last accepted block.
    - Return: an [InitializeResponse](https://buf.build/ava-labs/avalanche/docs/main:vm#vm.InitializeResponse) containing data about the genesis extracted from the `genesis_bytes` that was sent in the request.
3. [VM.VerifyHeightIndex](https://buf.build/ava-labs/avalanche/docs/main:vm#vm.VM.VerifyHeightIndex)
    - Return: a [VerifyHeightIndexResponse](https://buf.build/ava-labs/avalanche/docs/main:vm#vm.VerifyHeightIndexResponse) with the code `ERROR_UNSPECIFIED` to indicate that no error has occurred.
4. [VM.CreateHandlers](https://buf.build/ava-labs/avalanche/docs/main:vm#vm.VM.CreateHandlers)
    - To serve json-RPC endpoint, `/ext/bc/subnetId/rpc` exposed by AvalancheGo
    - See [json-RPC](#json-rpc) for more detail
    - Create a [`Http`](https://buf.build/ava-labs/avalanche/docs/main:http) server and get its url.
    - Return: a `CreateHandlersResponse` containing a single item with the server's url. (or an empty array if not implementing the json-RPC endpoint)
5. [VM.StateSyncEnabled](https://buf.build/ava-labs/avalanche/docs/main:vm#vm.VM.StateSyncEnabled)
    - Return: `true` if you want to enable StateSync, `false` otherwise.
6. [VM.SetState](https://buf.build/ava-labs/avalanche/docs/main:vm#vm.VM.SetState) _If you had specified `true` in the `StateSyncEnabled` result_
    - Param: a [SetStateRequest](https://buf.build/ava-labs/avalanche/docs/main:vm#vm.SetStateRequest) with the `StateSyncing` value
    - Set your blockchain's state to `StateSyncing`
    - Return: a [SetStateResponse](https://buf.build/ava-labs/avalanche/docs/main:vm#vm.SetStateResponse) built from the genesis block.
7. [VM.GetOngoingSyncStateSummary](https://buf.build/ava-labs/avalanche/docs/main:vm#vm.VM.GetOngoingSyncStateSummary) _If you had specified `true` in the `StateSyncEnabled` result_
    - Return: a [GetOngoingSyncStateSummaryResponse](https://buf.build/ava-labs/avalanche/docs/main:vm#vm.GetOngoingSyncStateSummaryResponse) built from the genesis block.
8. [VM.SetState](https://buf.build/ava-labs/avalanche/docs/main:vm#vm.VM.SetState)
    - Param: a [SetStateRequest](https://buf.build/ava-labs/avalanche/docs/main:vm#vm.SetStateRequest) with the `Bootstrapping` value
    - Set your blockchain's state to `Bootstrapping`
    - Return: a [SetStateResponse](https://buf.build/ava-labs/avalanche/docs/main:vm#vm.SetStateResponse) built from the genesis block.
9. [VM.SetPreference](https://buf.build/ava-labs/avalanche/docs/main:vm#vm.VM.SetPreference)
    - Param: `SetPreferenceRequest` containing the preferred block ID
    - Return: Empty
10. [VM.SetState](https://buf.build/ava-labs/avalanche/docs/main:vm#vm.VM.SetState)
    - Param: a [SetStateRequest](https://buf.build/ava-labs/avalanche/docs/main:vm#vm.SetStateRequest) with the `NormalOp` value
    - Set your blockchain's state to `NormalOp`
    - Return: a [SetStateResponse](https://buf.build/ava-labs/avalanche/docs/main:vm#vm.SetStateResponse) built from the genesis block.
11. [VM.Connected](https://buf.build/ava-labs/avalanche/docs/main:vm#vm.VM.Connected) (for every other node validating this Avalanche L1 in the network)
    - Param: a [ConnectedRequest](https://buf.build/ava-labs/avalanche/docs/main:vm#vm.ConnectedRequest) with the NodeID and the version of AvalancheGo.
    - Return: Empty
12. [VM.Health](https://buf.build/ava-labs/avalanche/docs/main:vm#vm.VM.Health)
    - Param: Empty
    - Return: a [HealthResponse](https://buf.build/ava-labs/avalanche/docs/main:vm#vm.HealthResponse) with an empty `details` property.
13. [VM.ParseBlock](https://buf.build/ava-labs/avalanche/docs/main:vm#vm.VM.ParseBlock)
    - Param: A byte array containing a Block (the genesis block in this case)
    - Return: a [ParseBlockResponse](https://buf.build/ava-labs/avalanche/docs/main:vm#vm.ParseBlockResponse) built from the last accepted block.

At this point, your VM is fully started and initialized.

### Building Blocks

#### Transaction Gossiping Sequence

When your VM receives transactions (for example using the [json-RPC](#json-rpc) endpoints), it can gossip them to the other nodes by using the [AppSender](https://buf.build/ava-labs/avalanche/docs/main:appsender) service.

Supposing we have a 3 nodes network with nodeX, nodeY, nodeZ. Let's say NodeX has received a new transaction on it's json-RPC endpoint.

<Accordions>
<Accordion title="On NodeX">
[`AppSender.SendAppGossip`](https://buf.build/ava-labs/avalanche/docs/main:appsender#appsender.AppSender.SendAppGossip) (_client_): You must serialize your transaction data into a byte array and call the `SendAppGossip` to propagate the transaction.

AvalancheGo then propagates this to the other nodes.
</Accordion>
<Accordion title="On NodeY and NodeZ">
[VM.AppGossip](https://buf.build/ava-labs/avalanche/docs/main:vm#vm.VM.AppGossip): You must deserialize the transaction and store it for the next block.

- Param: A byte array containing your transaction data, and the NodeID of the node which sent the gossip message.
- Return: Empty
</Accordion>
</Accordions>

#### Block Building Sequence

Whenever your VM is ready to build a new block, it will initiate the block building process by using the [Messenger](https://buf.build/ava-labs/avalanche/docs/main:messenger) service. Supposing that nodeY wants to build the block. you probably will implement some kind of background worker checking every second if there are any pending transactions:

<Accordions>
<Accordion title="On NodeY">
_client_ [`Messenger.Notify`](https://buf.build/ava-labs/avalanche/docs/main:messenger#messenger.Messenger.Notify): You must issue a notify request to AvalancheGo by calling the method with the `MESSAGE_BUILD_BLOCK` value.

1. [VM.BuildBlock](https://buf.build/ava-labs/avalanche/docs/main:vm#vm.VM.BuildBlock)
    - Param: Empty
    - You must build a block with your pending transactions. Serialize it to a byte array.
    - Store this block in memory as a "pending blocks"
    - Return: a [BuildBlockResponse](https://buf.build/ava-labs/avalanche/docs/main:vm#vm.BuildBlockResponse) from the newly built block and it's associated data (`id`, `parent_id`, `height`, `timestamp`).
2. [VM.BlockVerify](https://buf.build/ava-labs/avalanche/docs/main:vm#vm.VM.BlockVerify)
    - Param: The byte array containing the block data
    - Return: the block's timestamp
3. [VM.SetPreference](https://buf.build/ava-labs/avalanche/docs/main:vm#vm.VM.SetPreference)
    - Param: The block's ID
    - You must mark this block as the next preferred block.
    - Return: Empty
</Accordion>
<Accordion title="On NodeX and NodeZ">
1. [VM.ParseBlock](https://buf.build/ava-labs/avalanche/docs/main:vm#vm.VM.ParseBlock)
    - Param: A byte array containing a the newly built block's data
    - Store this block in memory as a "pending blocks"
    - Return: a [ParseBlockResponse](https://buf.build/ava-labs/avalanche/docs/main:vm#vm.ParseBlockResponse) built from the last accepted block.
2. [VM.BlockVerify](https://buf.build/ava-labs/avalanche/docs/main:vm#vm.VM.BlockVerify)
    - Param: The byte array containing the block data
    - Return: the block's timestamp
3. [VM.SetPreference](https://buf.build/ava-labs/avalanche/docs/main:vm#vm.VM.SetPreference)
    - Param: The block's ID
    - You must mark this block as the next preferred block.
    - Return: Empty
</Accordion>
<Accordion title="On All Nodes">
[VM.BlockAccept](https://buf.build/ava-labs/avalanche/docs/main:vm#vm.VM.BlockAccept): You must accept this block as your last final block.
    - Param: The block's ID
    - Return: Empty
</Accordion>
</Accordions>

#### Managing Conflicts

Conflicts happen when two or more nodes propose the next block at the same time. AvalancheGo takes care of this and decides which block should be considered final, and which blocks should be rejected using Snowman consensus. On the VM side, all there is to do is implement the `VM.BlockAccept` and `VM.BlockReject` methods.

_nodeX proposes block `0x123...`, nodeY proposes block `0x321...` and nodeZ proposes block `0x456`_

There are three conflicting blocks (different hashes), and if we look at our VM's log files, we can see that AvalancheGo uses Snowman to decide which block must be accepted.

```bash
... snowman/voter.go:58 filtering poll results ...
... snowman/voter.go:65 finishing poll ...
... snowman/voter.go:87 Snowman engine can't quiesce
... 
... snowman/voter.go:58 filtering poll results ...
... snowman/voter.go:65 finishing poll ...
... snowman/topological.go:600 accepting block
```

Supposing that AvalancheGo accepts block `0x123...`. The following RPC methods are called on all nodes:

1. [VM.BlockAccept](https://buf.build/ava-labs/avalanche/docs/main:vm#vm.VM.BlockAccept): You must accept this block as your last final block.
    - Param: The block's ID (`0x123...`)
    - Return: Empty
2. [VM.BlockReject](https://buf.build/ava-labs/avalanche/docs/main:vm#vm.VM.BlockReject): You must mark this block as rejected.
    - Param: The block's ID (`0x321...`)
    - Return: Empty
3. [VM.BlockReject](https://buf.build/ava-labs/avalanche/docs/main:vm#vm.VM.BlockReject): You must mark this block as rejected.
    - Param: The block's ID (`0x456...`)
    - Return: Empty

### JSON-RPC

To enable your json-RPC endpoint, you must implement the [HandleSimple](https://buf.build/ava-labs/avalanche/docs/main:http#http.HTTP.HandleSimple) method of the [`Http`](https://buf.build/ava-labs/avalanche/docs/main:http) interface.

- Param: a [HandleSimpleHTTPRequest](https://buf.build/ava-labs/avalanche/docs/main:http#http.HandleSimpleHTTPRequest) containing the original request's method, url, headers, and body.
- Analyze, deserialize and handle the request. For example: if the request represents a transaction, we must deserialize it, check the signature, store it and gossip it to the other nodes using the [messenger client](#block-building-sequence)).
- Return the [HandleSimpleHTTPResponse](https://buf.build/ava-labs/avalanche/docs/main:http#http.HandleSimpleHTTPResponse) response that will be sent back to the original sender.
        
This server is registered with AvalancheGo during the [initialization process](#initialization-sequence) when the `VM.CreateHandlers` method is called. You must simply respond with the server's url in the `CreateHandlersResponse` result.

# Getting Started (/docs/api-reference/metrics-api/getting-started)

---
title: Getting Started
description: Getting Started with the Metrics API
icon: Rocket
---

The Metrics API is designed to be simple and accessible, requiring no authentication to get started. Just choose your endpoint, make your query, and instantly access on-chain data and analytics to power your applications.

The following query retrieves the daily count of active addresses on the Avalanche C-Chain(43114) over the course of one month (from August 1, 2024 12:00:00 AM to August 31, 2024 12:00:00 AM), providing insights into user activity on the chain for each day during that period. With this data you can use JavaScript visualization tools like Chart.js, D3.js, Highcharts, Plotly.js, or Recharts to create interactive and insightful visual representations.

```bash
curl --request GET \
  --url 'https://metrics.avax.network/v2/chains/43114/metrics/activeAddresses?startTimestamp=1722470400&endTimestamp=1725062400&timeInterval=day&pageSize=31'
```

Response:

```json
{
  "results": [
    {
      "value": 37738,
      "timestamp": 1724976000
    },
    {
      "value": 53934,
      "timestamp": 1724889600
    },
    {
      "value": 58992,
      "timestamp": 1724803200
    },
    {
      "value": 73792,
      "timestamp": 1724716800
    },
    {
      "value": 70057,
      "timestamp": 1724630400
    },
    {
      "value": 46452,
      "timestamp": 1724544000
    },
    {
      "value": 46323,
      "timestamp": 1724457600
    },
    {
      "value": 73399,
      "timestamp": 1724371200
    },
    {
      "value": 52661,
      "timestamp": 1724284800
    },
    {
      "value": 52497,
      "timestamp": 1724198400
    },
    {
      "value": 50574,
      "timestamp": 1724112000
    },
    {
      "value": 46999,
      "timestamp": 1724025600
    },
    {
      "value": 45320,
      "timestamp": 1723939200
    },
    {
      "value": 54964,
      "timestamp": 1723852800
    },
    {
      "value": 60251,
      "timestamp": 1723766400
    },
    {
      "value": 48493,
      "timestamp": 1723680000
    },
    {
      "value": 71091,
      "timestamp": 1723593600
    },
    {
      "value": 50456,
      "timestamp": 1723507200
    },
    {
      "value": 46989,
      "timestamp": 1723420800
    },
    {
      "value": 50984,
      "timestamp": 1723334400
    },
    {
      "value": 46988,
      "timestamp": 1723248000
    },
    {
      "value": 66943,
      "timestamp": 1723161600
    },
    {
      "value": 64209,
      "timestamp": 1723075200
    },
    {
      "value": 57478,
      "timestamp": 1722988800
    },
    {
      "value": 80553,
      "timestamp": 1722902400
    },
    {
      "value": 70472,
      "timestamp": 1722816000
    },
    {
      "value": 53678,
      "timestamp": 1722729600
    },
    {
      "value": 70818,
      "timestamp": 1722643200
    },
    {
      "value": 99842,
      "timestamp": 1722556800
    },
    {
      "value": 76515,
      "timestamp": 1722470400
    }
  ]
}
```

Congratulations! You’ve successfully made your first query to the Metrics API. 🚀🚀🚀

# Metrics API (/docs/api-reference/metrics-api)

---
title: Metrics API
description: Access real-time and historical metrics for Avalanche networks
icon: ChartLine
---

### What is the Metrics API?

The Metrics API equips web3 developers with a robust suite of tools to access and analyze on-chain activity across Avalanche’s primary network, Avalanche L1s, and other supported EVM chains. This API delivers comprehensive metrics and analytics, enabling you to seamlessly integrate historical data on transactions, gas consumption, throughput, staking, and more into your applications.

The Metrics API, along with the [Data API](/docs/api-reference/data-api) are the driving force behind every graph you see on the [Avalanche Explorer](https://explorer.avax.network/). From transaction trends to staking insights, the visualizations and data presented are all powered by these APIs, offering real-time and historical insights that are essential for building sophisticated, data-driven blockchain products..

<img src="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/avalanche-explorer.png?fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=08e429fcecc76e4dbb0145c1e6f70091" data-og-width="2740" width="2740" data-og-height="1712" height="1712" data-path="images/avalanche-explorer.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/avalanche-explorer.png?w=280&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=6efd803862ca61ccc7cd7f8fa1b9224f 280w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/avalanche-explorer.png?w=560&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=437286118598cac1ccef8bd14e067386 560w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/avalanche-explorer.png?w=840&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=55300c3beff337df77b4d32c6af3dbcc 840w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/avalanche-explorer.png?w=1100&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=d23700079e91c34daa139dea5925d36d 1100w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/avalanche-explorer.png?w=1650&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=3f64292ba88b83f5bcc9208c7a245bef 1650w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/avalanche-explorer.png?w=2500&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=6e2318fbd7684a8bf630fc0aa9a1dfc2 2500w" />

### Features

* **Chain Throughput:** Retrieve detailed metrics on gas consumption, Transactions Per Second (TPS), and gas prices, including rolling windows of data for granular analysis.
* **Cumulative Metrics:** Access cumulative data on addresses, contracts, deployers, and transaction counts, providing insights into network growth over time.
* **Staking Information:** Obtain staking-related data, including the number of validators and delegators, along with their respective weights, across different subnets.
* **Blockchains and Subnets:** Get information about supported blockchains, including EVM Chain IDs, blockchain IDs, and subnet associations, facilitating multi-chain analytics.
* **Composite Queries:** Perform advanced queries by combining different metric types and conditions, enabling detailed and customizable data retrieval.

The Metrics API is designed to provide developers with powerful tools to analyze and monitor on-chain activity across Avalanche’s primary network, Avalanche L1s, and other supported EVM chains. Below is an overview of the key features available:

### Chain Throughput Metrics

* **Gas Consumption** <br />
  Track the average and maximum gas consumption per second, helping to understand network performance and efficiency.
<img src="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/gas-used.png?fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=83d49ef5099a46f6b3edd6f68d9ca66d" data-og-width="2246" width="2246" data-og-height="508" height="508" data-path="images/gas-used.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/gas-used.png?w=280&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=62bbb54209b950d250525294cc10000d 280w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/gas-used.png?w=560&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=428912fb2f4abd5e986e2ec1a1727e72 560w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/gas-used.png?w=840&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=e49eee5ca5b3e3fc12ef069ef4153748 840w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/gas-used.png?w=1100&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=4d7d66d5f0d413475639d39184939102 1100w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/gas-used.png?w=1650&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=e1c042fb157ad8c67fe4463525c66076 1650w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/gas-used.png?w=2500&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=8cfe05e47b58a5c005324dab963d8f85 2500w" />

* **Transactions Per Second (TPS)** <br />
  Monitor the average and peak TPS to assess the network’s capacity and utilization.
<img src="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/tps.png?fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=4b4e5a7f30eb9e226d2b83974f9b9d96" data-og-width="2134" width="2134" data-og-height="524" height="524" data-path="images/tps.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/tps.png?w=280&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=39fb9f2df105997f86c12d1c2ac201f6" />

* **Gas Prices** <br />
  Analyze average and maximum gas prices over time to optimize transaction costs and predict fee trends.
  Monitor the average and peak TPS to assess the network’s capacity and utilization.
<img src="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/gas-price.png?fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=5cd95e5758a216c2d98b87ffa00c193f" data-og-width="2234" width="2234" data-og-height="518" height="518" data-path="images/gas-price.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/gas-price.png?w=280&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=34e7c202742fe4016ad74d42f19db11a 280w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/gas-price.png?w=560&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=8fad40d98664857be14d6d688479e26a 560w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/gas-price.png?w=840&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=25d117b92ac9331638245bfa51a892ef 840w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/gas-price.png?w=1100&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=a37864a27babcbd782dde2b191dc6a04 1100w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/gas-price.png?w=1650&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=dd2ff9b6f97dc9ffd4b2b959642cc86f 1650w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/gas-price.png?w=2500&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=0a4bae90df88abbd194d39e81df82904 2500w" />

### Cumulative Metrics

* **Address Growth** <br />
  Access the cumulative number of active addresses on a chain, providing insights into network adoption and user activity.
    <img src="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/address-growth.png?fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=9711fbab3952cb4fc83b3669644bd61f" data-og-width="1270" width="1270" data-og-height="526" height="526" data-path="images/address-growth.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/address-growth.png?w=280&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=8b4122f7d6c39acb7fa760b7d9ed4d53 280w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/address-growth.png?w=560&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=db773dd8f4feb931ad39f9d8eb912881 560w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/address-growth.png?w=840&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=e0658680af8315123920de3da152741f 840w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/address-growth.png?w=1100&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=bf1a7ea0bbb618a39f62ff0c2e4af582 1100w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/address-growth.png?w=1650&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=c66f8199193efb6fc7f70434e49472ce 1650w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/address-growth.png?w=2500&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=1b5fa8eac8517e9d28067a0822d51d99 2500w" />
* **Contract Deployment** <br />
  Monitor the cumulative number of smart contracts deployed, helping to gauge developer engagement and platform usage.
    <img src="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/contracts-deployed.png?fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=0c935a91f11317572c4bbf7d77605267" data-og-width="1274" width="1274" data-og-height="514" height="514" data-path="images/contracts-deployed.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/contracts-deployed.png?w=280&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=9fa8e3c3557ba148be0b3eed9429fb7e 280w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/contracts-deployed.png?w=560&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=130d0162d4352a5de81f0a1a00eb62dc 560w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/contracts-deployed.png?w=840&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=5c9d1647deb4844f9f00c010c328beb9 840w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/contracts-deployed.png?w=1100&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=49cd8a081dc663f251ba27ef33d4b3e8 1100w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/contracts-deployed.png?w=1650&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=683fe8e66667b1a900b36fb3a34d51ca 1650w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/contracts-deployed.png?w=2500&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=9b2bc5bebcbe0e7d731ead264a4d150e 2500w" />
* **Transaction Count** <br />
  Track the cumulative number of transactions, offering a clear view of network activity and transaction volume.
    <img src="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/transactions.png?fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=d271db14bc0f4587deec117295328480" data-og-width="1274" width="1274" data-og-height="530" height="530" data-path="images/transactions.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/transactions.png?w=280&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=4804932f216177724f67934e272513f5 280w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/transactions.png?w=560&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=579942ac2a6525e32c407d1849f3fdcd 560w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/transactions.png?w=840&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=6f833b20237305ebb0e06ed3a2e2085f 840w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/transactions.png?w=1100&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=f7c3197b2661ca78d2b99826e123d4af 1100w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/transactions.png?w=1650&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=8466c708703a5a78fa23fd925e9eb6c5 1650w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/transactions.png?w=2500&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=cd62a755b5e0e8a5836ad9bfcfaa00ca 2500w" />

### Staking Information

* **Validator and Delegator Counts** <br />
  Retrieve the number of active validators and delegators for a given L1, crucial for understanding network security and decentralization.
    <img src="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/validator-count.png?fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=0e7b9f73d99ea625c8b0657937a20002" data-og-width="2310" width="2310" data-og-height="516" height="516" data-path="images/validator-count.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/validator-count.png?w=280&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=99cbf647d41304d1cdc6d89a773fab85 280w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/validator-count.png?w=560&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=4a65f19673493f99fd70f8880415d1cf 560w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/validator-count.png?w=840&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=54532d69bf22968b129b8d59fa0d83d3 840w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/validator-count.png?w=1100&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=c394379424beb4c6e6b057bdead1a8b8 1100w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/validator-count.png?w=1650&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=00fb6eef9ce7eef53bfb640f42c6644c 1650w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/validator-count.png?w=2500&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=1265b3d9392ade6401d627f252b59faa 2500w" />
* **Staking Weights** <br />
  Access the total stake weight of validators and delegators, helping to assess the distribution of staked assets across the network.
    <img src="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/staking-weight.png?fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=0a3588249d0de25c08b2dedfacc04703" data-og-width="2304" width="2304" data-og-height="520" height="520" data-path="images/staking-weight.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/staking-weight.png?w=280&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=e56a254b64ae7b5aeea79adf4aff8bfc 280w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/staking-weight.png?w=560&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=8e654871f59c6cce994f3c87956b3a32 560w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/staking-weight.png?w=840&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=d07693fc9719b402d664d9aa8b645e55 840w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/staking-weight.png?w=1100&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=be32e1515db1b7c8dea17b57da2ba6a8 1100w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/staking-weight.png?w=1650&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=76650855af82fb3d77ec6aaf66fac2d0 1650w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/staking-weight.png?w=2500&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=2e0c844674f5ae99103553a748342481 2500w" />

### Rolling Window Analytics

* **Short-Term and Long-Term Metrics:** Perform rolling window analysis on various metrics like gas used, TPS, and gas prices, allowing for both short-term and long-term trend analysis.
* **Customizable Time Frames:** Choose from different time intervals (hourly, daily, monthly) to suit your specific analytical needs.

### Blockchain and L1 Information

* **Chain and L1 Mapping:** Get detailed information about EVM chains and their associated L1s, including chain IDs, blockchain IDs, and subnet IDs, facilitating cross-chain analytics.

### Advanced Composite Queries

* **Custom Metrics Combinations**: Combine multiple metrics and apply logical operators to perform sophisticated queries, enabling deep insights and tailored analytics.
* **Paginated Results:** Handle large datasets efficiently with paginated responses, ensuring seamless data retrieval in your applications.

The Metrics API equips developers with the tools needed to build robust analytics, monitoring, and reporting solutions, leveraging the full power of multi-chain data across the Avalanche ecosystem and beyond.

# Rate Limits (/docs/api-reference/metrics-api/rate-limits)

---
title: Rate Limits
description: Rate Limits for the Metrics API
icon: Clock
---
# Rate Limits

Rate limiting is managed through a weighted scoring system, known as Compute Units (CUs). Each API request consumes a specified number of CUs, determined by the complexity of the request. This system is designed to accommodate basic requests while efficiently handling more computationally intensive operations.

## Rate Limit Tiers

The maximum CUs (rate-limiting score) for a user depends on their subscription level and is delineated in the following table:

| Subscription Level | Per Minute Limit (CUs) | Per Day Limit (CUs) |
| :----------------- | :--------------------- | :------------------ |
| Free               | 8,000                  | 1,200,000           |

> We are working on new subscription tiers with higher rate limits to support even greater request volumes.

## Rate Limit Categories

The CUs for each category are defined in the following table:

| Weight | CU Value |
| :----- | :------- |
| Free   | 1        |
| Small  | 20       |
| Medium | 100      |
| Large  | 500      |
| XL     | 1000     |
| XXL    | 3000     |

## Rate Limits for Metrics Endpoints

The CUs for each route are defined in the table below:

| Endpoint                                                    | Method | Weight | CU Value |
| :---------------------------------------------------------- | :----- | :----- | :------- |
| `/v2/health-check`                                          | GET    | Free   | 1        |
| `/v2/chains`                                                | GET    | Free   | 1        |
| `/v2/chains/{chainId}`                                      | GET    | Free   | 1        |
| `/v2/chains/{chainId}/metrics/{metric}`                     | GET    | Medium | 100      |
| `/v2/chains/{chainId}/teleporterMetrics/{metric}`           | GET    | Medium | 100      |
| `/v2/chains/{chainId}/rollingWindowMetrics/{metric}`        | GET    | Medium | 100      |
| `/v2/networks/{network}/metrics/{metric}`                   | GET    | Medium | 100      |
| `/v2/chains/{chainId}/contracts/{address}/nfts:listHolders` | GET    | Large  | 500      |
| `/v2/chains/{chainId}/contracts/{address}/balances`         | GET    | XL     | 1000     |
| `/v2/chains/43114/btcb/bridged:getAddresses`                | GET    | Large  | 500      |
| `/v2/subnets/{subnetId}/validators:getAddresses`            | GET    | Large  | 500      |
| `/v2/lookingGlass/compositeQuery`                           | POST   | XXL    | 3000     |

<Info> All rate limits, weights, and CU values are subject to change. </Info>

# Usage Guide (/docs/api-reference/metrics-api/usage-guide)

---
title: Usage Guide
description: Usage Guide for the Metrics API
icon: Code
---

The Metrics API does not require authentication, making it straightforward to integrate into your applications. You can start making API requests without the need for an API key or any authentication headers.

#### Making Requests

You can interact with the Metrics API by sending HTTP GET requests to the provided endpoints. Below is an example of a simple `curl` request.

```bash
curl -H "Content-Type: Application/json" "https://metrics.avax.network/v1/avg_tps/{chainId}"
```

In the above request Replace `chainId` with the specific chain ID you want to query. For example, to retrieve the average transactions per second (TPS) for a specific chain (in this case, chain ID 43114), you can use the following endpoint:

```bash
curl "https://metrics.avax.network/v1/avg_tps/43114"
```

The API will return a JSON response containing the average TPS for the specified chain over a series of timestamps and `lastRun` is a timestamp indicating when the last data point was updated:

```json
{
  "results": [
    {"timestamp": 1724716800, "value": 1.98},
    {"timestamp": 1724630400, "value": 2.17},
    {"timestamp": 1724544000, "value": 1.57},
    {"timestamp": 1724457600, "value": 1.82},
    // Additional data points...
  ],
  "status": 200,
  "lastRun": 1724780812
}
```

### Rate Limits

Even though the Metrics API does not require authentication, it still enforces rate limits to ensure stability and performance. If you exceed these limits, the server will respond with a 429 Too Many Requests HTTP response code.

### Error Types

The API generates standard error responses along with error codes based on provided requests and parameters.

Typically, response codes within the `2XX` range signifies successful requests, while those within the `4XX` range points to errors originating from the client's side. Meanwhile, response codes within the `5XX` range indicates problems on the server's side.

The error response body is formatted like this:

```json
{
  "message": ["Invalid address format"], // route specific error message
  "error": "Bad Request", // error type
  "statusCode": 400 // http response code
}
```

Let's go through every error code that we can respond with:

| Error Code | Error Type            | Description                                                                                                                                                                                                                   |
| ---------- | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **400**    | Bad Request           | Bad requests generally mean the client has passed invalid or malformed parameters. Error messages in the response could help in evaluating the error.                                                                         |
| **401**    | Unauthorized          | When a client attempts to access resources that require authorization credentials but the client lacks proper authentication in the request, the server responds with 401.                                                    |
| **403**    | Forbidden             | When a client attempts to access resources with valid credentials but doesn't have the privilege to perform that action, the server responds with 403.                                                                        |
| **404**    | Not Found             | The 404 error is mostly returned when the client requests with either mistyped URL, or the passed resource is moved or deleted, or the resource doesn't exist.                                                                |
| **500**    | Internal Server Error | The 500 error is a generic server-side error that is returned for any uncaught and unexpected issues on the server side. This should be very rare, and you may reach out to us if the problem persists for a longer duration. |
| **502**    | Bad Gateway           | This is an internal error indicating invalid response received by the client-facing proxy or gateway from the upstream server.                                                                                                |
| **503**    | Service Unavailable   | The 503 error is returned for certain routes on a particular Subnet. This indicates an internal problem with our Subnet node, and may not necessarily mean the Subnet is down or affected.                                    |

### Pagination

For endpoints that return large datasets, the Metrics API employs pagination to manage the results. When querying for lists of data, you may receive a nextPageToken in the response, which can be used to request the next page of data.

Example response with pagination:

```json
{
  "results": [...],
  "nextPageToken": "3d22deea-ea64-4d30-8a1e-c2a353b67e90"
}
```

To retrieve the next set of results, include the nextPageToken in your subsequent request:

```bash
curl -H "Content-Type: Application/json" \
  "https://metrics.avax.network/v1/avg_tps/{chainId}?pageToken=3d22deea-ea64-4d30-8a1e-c2a353b67e90"
```

### Pagination Details

#### Page Token Structure

The `nextPageToken` is a UUID-based token provided in the response when additional pages of data are available. This token serves as a pointer to the next set of data.

* **UUID Generation**: The `nextPageToken` is generated uniquely for each pagination scenario, ensuring security and ensuring predictability.
* **Expiration**: The token is valid for 24 hours from the time it is generated. After this period, the token will expire, and a new request starting from the initial page will be required.
* **Presence**: The token is only included in the response when there is additional data available. If no more data exists, the token will not be present.

#### Integration and Usage

To use the pagination system effectively:

* Check if the `nextPageToken` is present in the response.
* If present, include this token in the subsequent request to fetch the next page of results.
* Ensure that the follow-up request is made within the 24-hour window after the token was generated to avoid token expiration.

By utilizing the pagination mechanism, you can efficiently manage and navigate through large datasets, ensuring a smooth data retrieval process.

### Swagger API Reference

You can explore the full API definitions and interact with the endpoints in the Swagger documentation at:

<Cards cols={1}>
  <Card title="Swagger API Reference">
    [https://metrics.avax.network/api](https://metrics.avax.network/api)
  </Card>
</Cards>

# Webhooks API (/docs/api-reference/webhook-api)

---
title: Webhooks API
description: Real-time notifications for blockchain events on Avalanche networks
icon: Webhook
---

### What is the Webhooks API?

The Webhooks API lets you monitor real-time events on the Avalanche ecosystem, including the C-chain, L1s, and the Platform Chain (P/X chains). By subscribing to specific events, you can receive instant notifications for on-chain occurrences without continuously polling the network.

<img src="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/webhooks.png?fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=ee45e3165b9c7c74f85bf87bc248702e" alt="webhooks" data-og-width="3450" width="3450" data-og-height="2234" height="2234" data-path="images/webhooks.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/webhooks.png?w=280&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=5465ea56e0c0016d54166ef1ad2a069f 280w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/webhooks.png?w=560&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=9a236a383ca3cbf91a637920decef275 560w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/webhooks.png?w=840&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=104ba846be582735450055d716f68486 840w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/webhooks.png?w=1100&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=b2334bc28c374a56e5318bafa43649b9 1100w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/webhooks.png?w=1650&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=d45a14d32938b38a1537eeba5201457e 1650w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/webhooks.png?w=2500&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=f99ee41e46f2051dbb28befe65bab9bb 2500w" />

### Key Features:

* **Real-time notifications:** Receive immediate updates on specified on-chain activities without polling.
* **Customizable:** Specify the desired event type to listen for, customizing notifications based on your individual requirements.
* **Secure:** Employ shared secrets and signature-based verification to ensure that notifications originate from a trusted source.
* **Broad Coverage:**
  * **C-chain:** Mainnet and testnet, covering smart contract events, NFT transfers, and wallet-to-wallet transactions.
  * **Platform Chain (P and X chains):** Address and validator events, staking activities, and other platform-level transactions.

By supporting both the C-chain and the Platform Chain, you can monitor an even wider range of Avalanche activities.

### Use cases

* **NFT marketplace transactions**: Get alerts for NFT minting, transfers, auctions, bids, sales, and other interactions within NFT marketplaces.
* **Wallet notifications**: Receive alerts when an address performs actions such as sending, receiving, swapping, or burning assets.
* **DeFi activities**: Receive notifications for various DeFi activities such as liquidity provisioning, yield farming, borrowing, lending, and liquidations.
* **Staking rewards:** Get real-time notifications when a validator stakes, receives delegation, or earns staking rewards on the P-Chain, enabling seamless monitoring of validator earnings and participation.

## APIs for continuous polling vs. Webhooks for events data

The following example uses the address activity webhook topic to illustrate the difference between polling an API for wallet event data versus subscribing to a webhook topic to receive wallet events.
<img src="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/why_webhooks.png?fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=82bf00154bde6e6275bc7e6a65cd1058" alt="webhooks" data-og-width="3968" width="3968" data-og-height="2452" height="2452" data-path="images/why_webhooks.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/why_webhooks.png?w=280&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=f0f7f105bd3c3abb4badb47aa2989f4b 280w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/why_webhooks.png?w=560&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=9e65d0ef963e3d91c7c7c8e3adcd2eeb 560w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/why_webhooks.png?w=840&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=84287443edcf2e6d099939b3dfc867ad 840w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/why_webhooks.png?w=1100&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=0eae2268ecc70be64e6ff3c8120c6767 1100w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/why_webhooks.png?w=1650&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=d88c6b8dc09c3491f0dd2600e30060a8 1650w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/why_webhooks.png?w=2500&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=8762cf9e61a1c72e76068e5edd4837c7 2500w" />

### Continous polling

Continuous polling is a method where your application repeatedly sends requests to an API at fixed intervals to check for new data or events. Think of it like checking your mailbox every five minutes to see if new mail has arrived, whether or not anything is there.

* You want to track new transactions for a specific wallet.
* Your application calls an API every few seconds (e.g., every 5 seconds) with a query like, “Are there any new transactions for this wallet since my last check?”
* The API responds with either new transaction data or a confirmation that nothing has changed.

**Downsides of continuous polling**

* **Inefficiency:** Your app makes requests even when no new transactions occur, wasting computational resources, bandwidth, and potentially incurring higher API costs.
  For example, if no transactions happen for an hour, your app still sends hundreds of unnecessary requests.
* **Delayed updates:**
  Since polling happens at set intervals, there’s a potential delay in detecting events. If a transaction occurs just after a poll, your app won’t know until the next check—up to 5 seconds later in our example.
  This lag can be critical for time-sensitive applications, like trading or notifications.
* **Scalability challenges:** Monitoring one wallet might be manageable, but if you’re tracking dozens or hundreds of wallets, the number of requests multiplies quickly.

### Webhook subscription

Webhooks are an event-driven alternative where your application subscribes to specific events, and the Avalanche service notifies you instantly when those events occur. It’s like signing up for a delivery alert—when the package (event) arrives, you get a text message right away, instead of checking the tracking site repeatedly.

* Your app registers a webhook specifying an endpoint (e.g., `https://your-app.com/webhooks/transactions`) and the event type (e.g., `address_activity`).
* When a new transaction occurs we send a POST request to your endpoint with the transaction details.
* Your app receives the data only when something happens, with no need to ask repeatedly.

**Benefits of Avalanche webhooks**

* **Real-Time updates:** Notifications arrive the moment a transaction is processed, eliminating delays inherent in polling. This is ideal for applications needing immediate responses, like alerting users or triggering automated actions.
* **Efficiency:** Your app doesn’t waste resources making requests when there’s no new data. Data flows only when events occur. This reduces server load, bandwidth usage, and API call quotas.
* **Scalability:** You can subscribe to events for multiple wallets or event types (e.g., transactions, smart contract calls) without increasing the number of requests your app makes. We handle the event detection and delivery, so your app scales effortlessly as monitoring needs grow.

## Event payload structure

The Event structure always begins with the following parameters:

```json  theme={null}
{
  "webhookId": "6d1bd383-aa8d-47b5-b793-da6d8a115fde",
  "eventType": "address_activity",
  "messageId": "8e4e7284-852a-478b-b425-27631c8d22d2",
  "event": {
  }
}
```

**Parameters:**

* `webhookId`: Unique identifier for the webhook in your account.
* `eventType`: The event that caused the webhook to be triggered. In the future, there will be multiple types of events, for the time being only the address\_activity event is supported. The address\_activity event gets triggered whenever the specified addresses participate in a token or AVAX transaction.
* `messageId`: Unique identifier per event sent.
* `event`: Event payload. It contains details about the transaction, logs, and traces. By default logs and internal transactions are not included, if you want to include them use `"includeLogs": true`, and `"includeInternalTxs": true`.

### Address Activity webhook

The address activity webhook allows you to track any interaction with an address (any address). Here is an example of this type of event:

```json  theme={null}
{
  "webhookId": "263942d1-74a4-4416-aeb4-948b9b9bb7cc",
  "eventType": "address_activity",
  "messageId": "94df1881-5d93-49d1-a1bd-607830608de2",
  "event": {
    "transaction": {
      "blockHash": "0xbd093536009f7dd785e9a5151d80069a93cc322f8b2df63d373865af4f6ee5be",
      "blockNumber": "44568834",
      "from": "0xf73166f0c75a3DF444fAbdFDC7e5EE4a73fA51C7",
      "gas": "651108",
      "gasPrice": "31466275484",
      "maxFeePerGas": "31466275484",
      "maxPriorityFeePerGas": "31466275484",
      "txHash": "0xf6a791920652e87ccc91d2f1b20c1505a94452b88f359acdeb5a6fa8205638c4",
      "txStatus": "1",
      "input": "0xb80c2f090000000000000000000000000000000000000000000000000000000000000000000000000000000000000000eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee000000000000000000000000b97ef9ef8734c71904d8002f8b6bc66dd9c48a6e000000000000000000000000000000000000000000000000006ca0c737b131f2000000000000000000000000000000000000000000000000000000000011554e000000000000000000000000000000000000000000000000000000006627dadc0000000000000000000000000000000000000000000000000000000000000120000000000000000000000000000000000000000000000000000000000000016000000000000000000000000000000000000000000000000000000000000004600000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000006ca0c737b131f2000000000000000000000000000000000000000000000000000000000000000100000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000a000000000000000000000000000000000000000000000000000000000000000e000000000000000000000000000000000000000000000000000000000000001200000000000000000000000000000000000000000000000000000000000000160000000000000000000000000b31f66aa3c1e785363f0875a1b74e27b85fd66c70000000000000000000000000000000000000000000000000000000000000001000000000000000000000000be882fb094143b59dc5335d32cecb711570ebdd40000000000000000000000000000000000000000000000000000000000000001000000000000000000000000be882fb094143b59dc5335d32cecb711570ebdd400000000000000000000000000000000000000000000000000000000000000010000000000000000000027100e663593657b064e1bae76d28625df5d0ebd44210000000000000000000000000000000000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000000000000000c0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000400000000000000000000000000000000000000000000000000000000000000060000000000000000000000000b31f66aa3c1e785363f0875a1b74e27b85fd66c7000000000000000000000000b97ef9ef8734c71904d8002f8b6bc66dd9c48a6e0000000000000000000000000000000000000000000000000000000000000bb80000000000000000000000000000000000000000000000000000000000000000",
      "nonce": "4",
      "to": "0x1dac23e41fc8ce857e86fd8c1ae5b6121c67d96d",
      "transactionIndex": 0,
      "value": "30576074978046450",
      "type": 0,
      "chainId": "43114",
      "receiptCumulativeGasUsed": "212125",
      "receiptGasUsed": "212125",
      "receiptEffectiveGasPrice": "31466275484",
      "receiptRoot": "0xf355b81f3e76392e1b4926429d6abf8ec24601cc3d36d0916de3113aa80dd674",
      "erc20Transfers": [
        {
          "transactionHash": "0xf6a791920652e87ccc91d2f1b20c1505a94452b88f359acdeb5a6fa8205638c4",
          "type": "ERC20",
          "from": "0x1daC23e41Fc8ce857E86fD8C1AE5b6121C67D96d",
          "to": "0xbe882fb094143B59Dc5335D32cEcB711570EbDD4",
          "value": "30576074978046450",
          "blockTimestamp": 1713884373,
          "logIndex": 2,
          "erc20Token": {
            "address": "0xB31f66AA3C1e785363F0875A1B74E27b85FD66c7",
            "name": "Wrapped AVAX",
            "symbol": "WAVAX",
            "decimals": 18,
            "valueWithDecimals": "0.030576074978046448"
          }
        },
        {
          "transactionHash": "0xf6a791920652e87ccc91d2f1b20c1505a94452b88f359acdeb5a6fa8205638c4",
          "type": "ERC20",
          "from": "0x0E663593657B064e1baE76d28625Df5D0eBd4421",
          "to": "0xf73166f0c75a3DF444fAbdFDC7e5EE4a73fA51C7",
          "value": "1195737",
          "blockTimestamp": 1713884373,
          "logIndex": 3,
          "erc20Token": {
            "address": "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
            "name": "USD Coin",
            "symbol": "USDC",
            "decimals": 6,
            "valueWithDecimals": "1.195737"
          }
        },
        {
          "transactionHash": "0xf6a791920652e87ccc91d2f1b20c1505a94452b88f359acdeb5a6fa8205638c4",
          "type": "ERC20",
          "from": "0xbe882fb094143B59Dc5335D32cEcB711570EbDD4",
          "to": "0x0E663593657B064e1baE76d28625Df5D0eBd4421",
          "value": "30576074978046450",
          "blockTimestamp": 1713884373,
          "logIndex": 4,
          "erc20Token": {
            "address": "0xB31f66AA3C1e785363F0875A1B74E27b85FD66c7",
            "name": "Wrapped AVAX",
            "symbol": "WAVAX",
            "decimals": 18,
            "valueWithDecimals": "0.030576074978046448"
          }
        }
      ],
      "erc721Transfers": [],
      "erc1155Transfers": [],
      "internalTransactions": [
        {
          "from": "0xf73166f0c75a3DF444fAbdFDC7e5EE4a73fA51C7",
          "to": "0x1daC23e41Fc8ce857E86fD8C1AE5b6121C67D96d",
          "internalTxType": "CALL",
          "value": "30576074978046450",
          "gasUsed": "212125",
          "gasLimit": "651108",
          "transactionHash": "0xf6a791920652e87ccc91d2f1b20c1505a94452b88f359acdeb5a6fa8205638c4"
        },
        {
          "from": "0x1daC23e41Fc8ce857E86fD8C1AE5b6121C67D96d",
          "to": "0xF2781Bb34B6f6Bb9a6B5349b24de91487E653119",
          "internalTxType": "DELEGATECALL",
          "value": "30576074978046450",
          "gasUsed": "176417",
          "gasLimit": "605825",
          "transactionHash": "0xf6a791920652e87ccc91d2f1b20c1505a94452b88f359acdeb5a6fa8205638c4"
        },
        {
          "from": "0x1daC23e41Fc8ce857E86fD8C1AE5b6121C67D96d",
          "to": "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
          "internalTxType": "STATICCALL",
          "value": "0",
          "gasUsed": "9750",
          "gasLimit": "585767",
          "transactionHash": "0xf6a791920652e87ccc91d2f1b20c1505a94452b88f359acdeb5a6fa8205638c4"
        },
        {
          "from": "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
          "to": "0x30DFE0469803BcE76F8F62aC24b18d33D3d6FfE6",
          "internalTxType": "DELEGATECALL",
          "value": "0",
          "gasUsed": "2553",
          "gasLimit": "569571",
          "transactionHash": "0xf6a791920652e87ccc91d2f1b20c1505a94452b88f359acdeb5a6fa8205638c4"
        },
        {
          "from": "0x1daC23e41Fc8ce857E86fD8C1AE5b6121C67D96d",
          "to": "0xB31f66AA3C1e785363F0875A1B74E27b85FD66c7",
          "internalTxType": "CALL",
          "value": "30576074978046450",
          "gasUsed": "23878",
          "gasLimit": "566542",
          "transactionHash": "0xf6a791920652e87ccc91d2f1b20c1505a94452b88f359acdeb5a6fa8205638c4"
        },
        {
          "from": "0x1daC23e41Fc8ce857E86fD8C1AE5b6121C67D96d",
          "to": "0xB31f66AA3C1e785363F0875A1B74E27b85FD66c7",
          "internalTxType": "CALL",
          "value": "0",
          "gasUsed": "25116",
          "gasLimit": "540114",
          "transactionHash": "0xf6a791920652e87ccc91d2f1b20c1505a94452b88f359acdeb5a6fa8205638c4"
        },
        {
          "from": "0x1daC23e41Fc8ce857E86fD8C1AE5b6121C67D96d",
          "to": "0xbe882fb094143B59Dc5335D32cEcB711570EbDD4",
          "internalTxType": "CALL",
          "value": "0",
          "gasUsed": "81496",
          "gasLimit": "511279",
          "transactionHash": "0xf6a791920652e87ccc91d2f1b20c1505a94452b88f359acdeb5a6fa8205638c4"
        },
        {
          "from": "0xbe882fb094143B59Dc5335D32cEcB711570EbDD4",
          "to": "0xB31f66AA3C1e785363F0875A1B74E27b85FD66c7",
          "internalTxType": "STATICCALL",
          "value": "0",
          "gasUsed": "491",
          "gasLimit": "501085",
          "transactionHash": "0xf6a791920652e87ccc91d2f1b20c1505a94452b88f359acdeb5a6fa8205638c4"
        },
        {
          "from": "0xbe882fb094143B59Dc5335D32cEcB711570EbDD4",
          "to": "0x0E663593657B064e1baE76d28625Df5D0eBd4421",
          "internalTxType": "CALL",
          "value": "0",
          "gasUsed": "74900",
          "gasLimit": "497032",
          "transactionHash": "0xf6a791920652e87ccc91d2f1b20c1505a94452b88f359acdeb5a6fa8205638c4"
        },
        {
          "from": "0x0E663593657B064e1baE76d28625Df5D0eBd4421",
          "to": "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
          "internalTxType": "CALL",
          "value": "0",
          "gasUsed": "32063",
          "gasLimit": "463431",
          "transactionHash": "0xf6a791920652e87ccc91d2f1b20c1505a94452b88f359acdeb5a6fa8205638c4"
        },
        {
          "from": "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
          "to": "0x30DFE0469803BcE76F8F62aC24b18d33D3d6FfE6",
          "internalTxType": "DELEGATECALL",
          "value": "0",
          "gasUsed": "31363",
          "gasLimit": "455542",
          "transactionHash": "0xf6a791920652e87ccc91d2f1b20c1505a94452b88f359acdeb5a6fa8205638c4"
        },
        {
          "from": "0x0E663593657B064e1baE76d28625Df5D0eBd4421",
          "to": "0xB31f66AA3C1e785363F0875A1B74E27b85FD66c7",
          "internalTxType": "STATICCALL",
          "value": "0",
          "gasUsed": "2491",
          "gasLimit": "430998",
          "transactionHash": "0xf6a791920652e87ccc91d2f1b20c1505a94452b88f359acdeb5a6fa8205638c4"
        },
        {
          "from": "0x0E663593657B064e1baE76d28625Df5D0eBd4421",
          "to": "0xbe882fb094143B59Dc5335D32cEcB711570EbDD4",
          "internalTxType": "CALL",
          "value": "0",
          "gasUsed": "7591",
          "gasLimit": "427775",
          "transactionHash": "0xf6a791920652e87ccc91d2f1b20c1505a94452b88f359acdeb5a6fa8205638c4"
        },
        {
          "from": "0xbe882fb094143B59Dc5335D32cEcB711570EbDD4",
          "to": "0xB31f66AA3C1e785363F0875A1B74E27b85FD66c7",
          "internalTxType": "CALL",
          "value": "0",
          "gasUsed": "6016",
          "gasLimit": "419746",
          "transactionHash": "0xf6a791920652e87ccc91d2f1b20c1505a94452b88f359acdeb5a6fa8205638c4"
        },
        {
          "from": "0x0E663593657B064e1baE76d28625Df5D0eBd4421",
          "to": "0xB31f66AA3C1e785363F0875A1B74E27b85FD66c7",
          "internalTxType": "STATICCALL",
          "value": "0",
          "gasUsed": "491",
          "gasLimit": "419670",
          "transactionHash": "0xf6a791920652e87ccc91d2f1b20c1505a94452b88f359acdeb5a6fa8205638c4"
        },
        {
          "from": "0x1daC23e41Fc8ce857E86fD8C1AE5b6121C67D96d",
          "to": "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
          "internalTxType": "STATICCALL",
          "value": "0",
          "gasUsed": "3250",
          "gasLimit": "430493",
          "transactionHash": "0xf6a791920652e87ccc91d2f1b20c1505a94452b88f359acdeb5a6fa8205638c4"
        },
        {
          "from": "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
          "to": "0x30DFE0469803BcE76F8F62aC24b18d33D3d6FfE6",
          "internalTxType": "DELEGATECALL",
          "value": "0",
          "gasUsed": "2553",
          "gasLimit": "423121",
          "transactionHash": "0xf6a791920652e87ccc91d2f1b20c1505a94452b88f359acdeb5a6fa8205638c4"
        },
        {
          "from": "0x1daC23e41Fc8ce857E86fD8C1AE5b6121C67D96d",
          "to": "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
          "internalTxType": "STATICCALL",
          "value": "0",
          "gasUsed": "1250",
          "gasLimit": "426766",
          "transactionHash": "0xf6a791920652e87ccc91d2f1b20c1505a94452b88f359acdeb5a6fa8205638c4"
        },
        {
          "from": "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
          "to": "0x30DFE0469803BcE76F8F62aC24b18d33D3d6FfE6",
          "internalTxType": "DELEGATECALL",
          "value": "0",
          "gasUsed": "553",
          "gasLimit": "419453",
          "transactionHash": "0xf6a791920652e87ccc91d2f1b20c1505a94452b88f359acdeb5a6fa8205638c4"
        }
      ],
      "blockTimestamp": 1713884373
    }
  }
}
```



# Rate Limits (/docs/api-reference/webhook-api/rate-limits)

---
title: Rate Limits
description: Rate Limits for the Webhooks API
icon: Clock
---

Rate limiting is managed through a weighted scoring system, known as Compute Units (CUs). Each API request consumes a specified number of CUs, determined by the complexity of the request. This system is designed to accommodate basic requests while efficiently handling more computationally intensive operations.

## Rate Limit Tiers

The maximum CUs (rate-limiting score) for a user depends on their subscription level and is delineated in the following table:

| Subscription Level | Per Minute Limit (CUs) | Per Day Limit (CUs) |
| :----------------- | :--------------------- | :------------------ |
| Unauthenticated    | 6,000                  | 1,200,000           |
| Free               | 8,000                  | 2,000,000           |
| Base               | 10,000                 | 3,750,000           |
| Growth             | 14,000                 | 11,200,000          |
| Pro                | 20,000                 | 25,000,000          |

To update your subscription level use the [AvaCloud Portal](https://app.avacloud.io/)

<Info> Note: Rate limits apply collectively across both Webhooks and Data APIs, with usage from each counting toward your total CU limit. </Info>

## Rate Limit Categories

The CUs for each category are defined in the following table:

| Weight | CU Value |
| :----- | :------- |
| Free   | 1        |
| Small  | 10       |
| Medium | 20       |
| Large  | 50       |
| XL     | 100      |
| XXL    | 200      |

## Rate Limits for Webhook Endpoints

The CUs for each route are defined in the table below:

| Endpoint                                    | Method | Weight | CU Value |
| :------------------------------------------ | :----- | :----- | :------- |
| `/v1/webhooks`                              | POST   | Medium | 20       |
| `/v1/webhooks`                              | GET    | Small  | 10       |
| `/v1/webhooks/{id}`                         | GET    | Small  | 10       |
| `/v1/webhooks/{id}`                         | DELETE | Medium | 20       |
| `/v1/webhooks/{id}`                         | PATCH  | Medium | 20       |
| `/v1/webhooks:generateOrRotateSharedSecret` | POST   | Medium | 20       |
| `/v1/webhooks:getSharedSecret`              | GET    | Small  | 10       |
| `/v1/webhooks/{id}/addresses`               | PATCH  | Medium | 20       |
| `/v1/webhooks/{id}/addresses`               | DELETE | Medium | 20       |
| `/v1/webhooks/{id}/addresses`               | GET    | Medium | 20       |

<Info> All rate limits, weights, and CU values are subject to change. </Info>

# Retry mechanism (/docs/api-reference/webhook-api/retries)

---
title: Retry mechanism
description: Retry mechanism for the Webhook API
icon: RotateCcw
---

Our webhook system is designed to ensure you receive all your messages, even if temporary issues prevent immediate delivery. To achieve this, we’ve implemented a retry mechanism that resends messages if they don’t get through on the first attempt. Importantly, **retries are handled on a per-message basis**, meaning each webhook message follows its own independent retry schedule. This ensures that the failure of one message doesn’t affect the delivery attempts of others.

This guide will walk you through how the retry mechanism works, the differences between free and paid tier users, and practical steps you can take to ensure your system handles webhooks effectively.

## How it works

When we send a webhook message to your server, we expect a `200` status code within 10 seconds to confirm successful receipt. Your server should return this response immediately and process the message afterward. Processing the message before sending the response can lead to timeouts and trigger unnecessary retries.
<img src="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/retries.png?fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=3d303f125a03da321e15812c437c3ba9" alt="webhooks" data-og-width="1943" width="1943" data-og-height="1747" height="1747" data-path="images/retries.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/retries.png?w=280&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=9bb01f0aea8b651f793163a3631e0c14 280w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/retries.png?w=560&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=b41eeb02d1b91481723179fa56fad5ef 560w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/retries.png?w=840&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=4b785be5a3ea9e7a9493fd8669c22e1d 840w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/retries.png?w=1100&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=23a984a432ad4458928035daffb7edfb 1100w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/retries.png?w=1650&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=82c785972eab57f7d770ccb83e30024f 1650w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/retries.png?w=2500&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=caeac507f17204e13100649d5077ea0c 2500w" />

* **Attempt 1:** We send the message expecting a respose with `200` status code. If we do not receive a `200` status code within **10 seconds**, the attempt is considered failed. During this window, any non-`2xx` responses are ignored.
* **Attempt 2:** Occurs **10 seconds** after the first attempt, with another 10-second timeout and the same rule for ignoring non-`2xx` responses.
* **Retry Queue After Two Failed Attempts**
  If both initial attempts fail, the message enters a **retry queue** with progressively longer intervals between attempts. Each retry attempt still has a 10-second timeout, and non-`2xx` responses are ignored during this window.

The retry schedule is as follows:

| Attempt | Interval |
| ------- | -------- |
| 3       | 1 min    |
| 4       | 5 min    |
| 5       | 10 min   |
| 6       | 30 min   |
| 7       | 2 hours  |
| 8       | 6 hours  |
| 9       | 12 hours |
| 10      | 24 hours |

**Total Retry Duration:** Up to approximately 44.8 hours (2,688 minutes) if all retries are exhausted.

**Interval Timing:** Each retry interval starts 10 seconds after the previous attempt is deemed failed. For example, if attempt 2 fails at t=20 seconds, attempt 3 will start at t=80 seconds (20s + 1 minute interval + 10s).

<Callout>Since retries are per message, multiple messages can be in different stages of their retry schedules simultaneously without interfering with each other.</Callout>

## Differences Between Free and Paid Tier Users

The behavior of the retry mechanism varies based on your subscription tier:
**Free tier users**

* **Initial attempts limit:** If six messages fail both the first and second attempts, your webhook will be automatically deactivated.
* **Retry queue limit:** Only five messages can enter the retry queue over the lifetime of the subscription. If a sixth message requires retry queuing, or if any message fails all 10 retry attempts, the subscription will be deactivated.

**Paid tier users**

* For paid users, webhooks will be deactivated if a single message, retried at the 24-hour interval, fails to process successfully.

## What you can do

**Ensure server availability:**

* Keep your server running smoothly to receive webhook messages without interruption.
* Implement logging for incoming webhook requests and your server's responses to help identify any issues quickly.

**Design for idempotency**

* Set up your webhook handler so it can safely process the same message multiple times without causing errors or unwanted effects. This way, if retries occur, they won't negatively impact your system.
* The webhook retry mechanism is designed to maximize the reliability of message delivery while minimizing the impact of temporary issues. By understanding how retries work—especially the per-message nature of the system—and following best practices like ensuring server availability and designing for idempotency, you can ensure a seamless experience with webhooks.

## Key Takeaways

* Each message has its own retry schedule, ensuring isolation and reliability.
* Free tier users have limits on failed attempts and retry queue entries, while paid users do not.
* Implement logging and idempotency to handle retries effectively and avoid disruptions.
* By following this guide, you’ll be well-equipped to manage webhooks and ensure your system remains robust, even in the face of temporary challenges.

# Webhook Signature (/docs/api-reference/webhook-api/webhooks-signature)

---
title: Webhook Signature
description: Webhook Signature for the Webhook API
icon: Signature
---

To make your webhooks extra secure, you can verify that they originated from our side by generating an HMAC SHA-256 hash code using your Authentication Token and request body. You can get the signing secret through the AvaCloud portal or Glacier API.

### Find your signing secret

**Using the portal**\
Navigate to the webhook section and click on Generate Signing Secret. Create the secret and copy it to your code.

**Using Data API**\
The following endpoint retrieves a shared secret:

```bash
curl --location 'https://glacier-api.avax.network/v1/webhooks:getSharedSecret' \
--header 'x-glacier-api-key: <YOUR_API_KEY>' \
```

### Validate the signature received

Every outbound request will include an authentication signature in the header. This signature is generated by:

1. **Canonicalizing the JSON Payload**: This means arranging the JSON data in a standard format.
2. **Generating a Hash**: Using the HMAC SHA256 hash algorithm to create a hash of the canonicalized JSON payload.

To verify that the signature is from us, follow these steps:

1. Generate the HMAC SHA256 hash of the received JSON payload.
2. Compare this generated hash with the signature in the request header.
   This process, known as verifying the digital signature, ensures the authenticity and integrity of the request.

**Example Request Header**

```
Content-Type: application/json;
x-signature: your-hashed-signature
```

### Example Signature Validation Function

This Node.js code sets up an HTTP server using the Express framework. It listens for POST requests sent to the `/callback` endpoint. Upon receiving a request, it validates the signature of the request against a predefined `signingSecret`. If the signature is valid, it logs match; otherwise, it logs no match. The server responds with a JSON object indicating that the request was received.

### Node (JavaScript)
```javascript
  const express = require('express');
  const crypto = require('crypto');
  const { canonicalize } = require('json-canonicalize');

  const app = express();
  app.use(express.json({limit: '50mb'}));

  const signingSecret = 'c13cc017c4ed63bcc842c8edfb49df37512280326a32826de3b885340b8a3d53';

  function isValidSignature(signingSecret, signature, payload) {
  const canonicalizedPayload = canonicalize(payload);
  const hmac = crypto.createHmac('sha256', Buffer.from(signingSecret, 'hex'));
  const digest = hmac.update(canonicalizedPayload).digest('base64');
  console.log("signature: ", signature);
  console.log("digest", digest);
  return signature === digest;
  }

  app.post('/callback', express.json({ type: 'application/json' }), (request, response) => {
  const { body, headers } = request;
  const signature = headers['x-signature'];
  // Handle the event
  switch (body.evenType) {
  case 'address\*activity':
  console.log("\*\** Address*activity \*\*\*");
  console.log(body);
  if (isValidSignature(signingSecret, signature, body)) {
  console.log("match");
  } else {
  console.log("no match");
  }
  break;
  // ... handle other event types
  default:
  console.log(`Unhandled event type ${body}`);
  }
  // Return a response to acknowledge receipt of the event
  response.json({ received: true });
  });

  const PORT = 8000;
  app.listen(PORT, () => console.log(`Running on port ${PORT}`));

```

### Python (Flask)
```python
  from flask import Flask, request, jsonify
  import hmac
  import hashlib
  import base64
  import json

  app = Flask(__name__)

  SIGNING_SECRET = 'c13cc017c4ed63bcc842c8edfb49df37512280326a32826de3b885340b8a3d53'

  def canonicalize(payload):
      """Function to canonicalize JSON payload"""
      # In Python, canonicalization can be achieved by using sort_keys=True in json.dumps
      return json.dumps(payload, separators=(',', ':'), sort_keys=True)

  def is_valid_signature(signing_secret, signature, payload):
      canonicalized_payload = canonicalize(payload)
      hmac_obj = hmac.new(bytes.fromhex(signing_secret), canonicalized_payload.encode('utf-8'), hashlib.sha256)
      digest = base64.b64encode(hmac_obj.digest()).decode('utf-8')
      print("signature:", signature)
      print("digest:", digest)
      return signature == digest

  @app.route('/callback', methods=['POST'])
  def callback_handler():
      body = request.json
      signature = request.headers.get('x-signature')

      # Handle the event
      if body.get('eventType') == 'address_activity':
          print("*** Address_activity ***")
          print(body)
          if is_valid_signature(SIGNING_SECRET, signature, body):
              print("match")
          else:
              print("no match")
      else:
          print(f"Unhandled event type {body}")

      # Return a response to acknowledge receipt of the event
      return jsonify({"received": True})

  if __name__ == '__main__':
      PORT = 8000
      print(f"Running on port {PORT}")
      app.run(port=PORT)
```

### Go (net/http)
```go
  package main

  import (
  	"crypto/hmac"
  	"crypto/sha256"
  	"encoding/base64"
  	"encoding/hex"
  	"encoding/json"
  	"fmt"
  	"net/http"
  	"sort"
  	"strings"
  )

  const signingSecret = "c13cc017c4ed63bcc842c8edfb49df37512280326a32826de3b885340b8a3d53"

  // Canonicalize function sorts the JSON keys and produces a canonicalized string
  func Canonicalize(payload map[string]interface{}) (string, error) {
  	var sb strings.Builder
  	var keys []string
  	for k := range payload {
  		keys = append(keys, k)
  	}
  	sort.Strings(keys)
  	sb.WriteString("{")
  	for i, k := range keys {
  		v, err := json.Marshal(payload[k])
  		if err != nil {
  			return "", err
  		}
  		sb.WriteString(fmt.Sprintf("\"%s\":%s", k, v))
  		if i < len(keys)-1 {
  			sb.WriteString(",")
  		}
  	}
  	sb.WriteString("}")
  	return sb.String(), nil
  }

  func isValidSignature(signingSecret, signature string, payload map[string]interface{}) bool {
  	canonicalizedPayload, err := Canonicalize(payload)
  	if err != nil {
  		fmt.Println("Error canonicalizing payload:", err)
  		return false
  	}

  	key, err := hex.DecodeString(signingSecret)
  	if err != nil {
  		fmt.Println("Error decoding signing secret:", err)
  		return false
  	}

  	h := hmac.New(sha256.New, key)
  	h.Write([]byte(canonicalizedPayload))
  	digest := h.Sum(nil)
  	encodedDigest := base64.StdEncoding.EncodeToString(digest)

  	fmt.Println("signature:", signature)
  	fmt.Println("digest:", encodedDigest)

  	return signature == encodedDigest
  }

  func callbackHandler(w http.ResponseWriter, r *http.Request) {
  	var body map[string]interface{}
  	err := json.NewDecoder(r.Body).Decode(&body)
  	if err != nil {
  		fmt.Println("Error decoding body:", err)
  		http.Error(w, "Invalid request body", http.StatusBadRequest)
  		return
  	}

  	signature := r.Header.Get("x-signature")
  	eventType, ok := body["eventType"].(string)
  	if !ok {
  		fmt.Println("Error parsing eventType")
  		http.Error(w, "Invalid event type", http.StatusBadRequest)
  		return
  	}

  	switch eventType {
  	case "address_activity":
  		fmt.Println("*** Address_activity ***")
  		fmt.Println(body)
  		if isValidSignature(signingSecret, signature, body) {
  			fmt.Println("match")
  		} else {
  			fmt.Println("no match")
  		}
  	default:
  		fmt.Printf("Unhandled event type %s\n", eventType)
  	}

  	w.Header().Set("Content-Type", "application/json")
  	json.NewEncoder(w).Encode(map[string]bool{"received": true})
  }

  func main() {
  	http.HandleFunc("/callback", callbackHandler)
  	fmt.Println("Running on port 8000")
  	http.ListenAndServe(":8000", nil)
  }
```

### Rust (actix-web)
```rust
  use actix_web::{web, App, HttpServer, HttpResponse, Responder, post};
  use serde::Deserialize;
  use hmac::{Hmac, Mac};
  use sha2::Sha256;
  use base64::encode;
  use std::collections::BTreeMap;

  type HmacSha256 = Hmac<Sha256>;

  const SIGNING_SECRET: &str = "c13cc017c4ed63bcc842c8edfb49df37512280326a32826de3b885340b8a3d53";

  #[derive(Deserialize)]
  struct EventPayload {
      eventType: String,
      // Add other fields as necessary
  }

  // Canonicalize the JSON payload by sorting keys
  fn canonicalize(payload: &BTreeMap<String, serde_json::Value>) -> String {
      serde_json::to_string(payload).unwrap()
  }

  fn is_valid_signature(signing_secret: &str, signature: &str, payload: &BTreeMap<String, serde_json::Value>) -> bool {
      let canonicalized_payload = canonicalize(payload);

      let mut mac = HmacSha256::new_from_slice(signing_secret.as_bytes())
          .expect("HMAC can take key of any size");
      mac.update(canonicalized_payload.as_bytes());

      let result = mac.finalize();
      let digest = encode(result.into_bytes());

      println!("signature: {}", signature);
      println!("digest: {}", digest);

      digest == signature
  }

  #[post("/callback")]
  async fn callback(body: web::Json<BTreeMap<String, serde_json::Value>>, req: web::HttpRequest) -> impl Responder {
      let signature = req.headers().get("x-signature").unwrap().to_str().unwrap();

      if let Some(event_type) = body.get("eventType").and_then(|v| v.as_str()) {
          match event_type {
              "address_activity" => {
                  println!("*** Address_activity ***");
                  println!("{:?}", body);

                  if is_valid_signature(SIGNING_SECRET, signature, &body) {
                      println!("match");
                  } else {
                      println!("no match");
                  }
              }
              _ => {
                  println!("Unhandled event type: {}", event_type);
              }
          }
      } else {
          println!("Error parsing eventType");
          return HttpResponse::BadRequest().finish();
      }

      HttpResponse::Ok().json(serde_json::json!({ "received": true }))
  }

  #[actix_web::main]
  async fn main() -> std::io::Result<()> {
      HttpServer::new(|| {
          App::new()
              .service(callback)
      })
      .bind("0.0.0.0:8000")?
      .run()
      .await
  }
```

### TypeScript (ChainKit SDK)
```typescript
  import { isValidSignature } from '@avalanche-sdk/chainkit/utils';
  import express from 'express';

  const app = express();
  app.use(express.json());

  const signingSecret = 'your-signing-secret'; // Replace with your signing secret

  app.post('/webhook', (req, res) => {
      const signature = req.headers['x-signature'];
      const payload = req.body;

      if (isValidSignature(signingSecret, signature, payload)) {
          console.log('Valid signature');
          // Process the request
      } else {
          console.log('Invalid signature');
      }

      res.json({ received: true });
  });

  app.listen(8000, () => console.log('Server running on port 8000'));
```

# WebSockets vs Webhooks (/docs/api-reference/webhook-api/wss-vs-webhooks)

---
title: WebSockets vs Webhooks
description: WebSockets vs Webhooks for the Webhook API
icon: GitCompare
---

Reacting to real-time events from Avalanche smart contracts allows for immediate responses and automation, improving user experience and streamlining application functionality. It ensures that applications stay synchronized with the blockchain state.

There are two primary methods for receiving these on-chain events:

* **WebSockets**, using libraries like Ethers.js or Viem
* **Webhooks**, which send structured event data directly to your app via HTTP POST.

Both approaches enable real-time interactions, but they differ drastically in their reliability, ease of implementation, and long-term maintainability. In this post, we break down why Webhooks are the better, more resilient choice for most Avalanche developers.

## Architecture Overview

The diagram below compares the two models side-by-side:
<img src="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/wss_vs_webhooks.png?fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=bd1fc923c99a1a26bb714cc16bd2894a" alt="wss_vs_webhooks" data-og-width="3968" width="3968" data-og-height="2452" height="2452" data-path="images/wss_vs_webhooks.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/wss_vs_webhooks.png?w=280&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=5b0ad33c8f800b1f34d6e7efe4247620 280w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/wss_vs_webhooks.png?w=560&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=0ec85d4d7acdd3562d3ea22b8404bec8 560w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/wss_vs_webhooks.png?w=840&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=88baf84f807b5a021c8d4c647638914c 840w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/wss_vs_webhooks.png?w=1100&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=b8c5dbe183dba6503bab65585619b3ad 1100w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/wss_vs_webhooks.png?w=1650&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=880cd9dd1c8ac1cee9918967c0843b93 1650w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/wss_vs_webhooks.png?w=2500&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=8269d5dea94c0284a683fda9d6815e85 2500w" />
**WebSockets**

* The app connects to the Avalanche RPC API over WSS to receive raw log data.
* It must decode logs, manage connection state, and store data locally.
* On disconnection, it must re-sync via an external Data API or using standard `eth_*` RPC calls (e.g., `eth_getLogs`, `eth_getBlockByNumber`).

<Callout>Important: WSS is a transport protocol—not real-time by itself. Real-time capabilities come from the availability of `eth_subscribe`, which requires node support.</Callout>

**Webhooks**

* The app exposes a simple HTTP endpoint.
* Decoded event data is pushed directly via POST, including token metadata.
* Built-in retries ensure reliable delivery, even during downtime.

<Callout>Important: Webhooks have a 48-hour retry window. If your app is down for longer, you still need a re-sync strategy using `eth_*` calls to recover older missed events.</Callout>

***

## Using WebSockets: Real-time but high maintenance

WebSockets allow you to subscribe to events using methods like eth\_subscribe. These subscriptions notify your app in real-time whenever new logs, blocks, or pending transactions meet your criteria.

```javascript
import { createPublicClient, webSocket, formatUnits } from 'viem';
import { avalancheFuji } from 'viem/chains';
import { usdcAbi } from './usdc-abi.mjs'; // Ensure this includes the Transfer event

// Your wallet address (case-insensitive comparison)
const MY_WALLET = '0x8ae323046633A07FB162043f28Cea39FFc23B50A'.toLowerCase(); //Chrome

async function monitorTransfers() {
    try {
        // USDC.e contract address on Avalanche Fuji
        const usdcAddress = '0x5425890298aed601595a70AB815c96711a31Bc65';

        // Set up the WebSocket client for Avalanche Fuji
        const client = createPublicClient({
            chain: avalancheFuji,
            transport: webSocket('wss://api.avax-test.network/ext/bc/C/ws'),
        });

        // Watch for Transfer events on the USDC contract
        client.watchContractEvent({
            address: usdcAddress,
            abi: usdcAbi,
            eventName: 'Transfer',
            onLogs: (logs) => {
                logs.forEach((log) => {
                    const { from, to, value } = log.args;
                    const fromLower = from.toLowerCase();

                    // Filter for transactions where 'from' matches your wallet
                    if (fromLower === MY_WALLET) {
                        console.log('*******');
                        console.log('Transfer from my wallet:');
                        console.log(`From: ${from}`);
                        console.log(`To: ${to}`);
                        console.log(`Value: ${formatUnits(value, 6)} USDC`); // USDC has 6 decimals
                        console.log(`Transaction Hash: ${log.transactionHash}`);
                    }
                });
            },
            onError: (error) => {
                console.error('Event watching error:', error.message);
            },
        });

        console.log('Monitoring USDC Transfer events on Fuji...');
    } catch (error) {
        console.error('Error setting up transfer monitoring:', error.message);
    }
}

// Start monitoring
monitorTransfers();
```

The downside? If your connection drops, you lose everything in between. You’ll need to:

* Set up a database to track the latest processed block and log index.
* Correctly handling dropped connections and reconnection by hand can be challenging to get right.
* Use `eth_getLogs` to re-fetch missed logs.
* Decode and process raw logs yourself to rebuild app state.
  This requires extra infrastructure, custom recovery logic, and significant maintenance overhead.

***

## Webhooks: Resilient and developer-friendly

Webhooks eliminate the complexity of managing live connections. Instead, you register an HTTP endpoint to receive blockchain event payloads when they occur.

Webhook payload example:

```json
{
  "eventType": "address_activity",
  "event": {
    "transaction": {
      "txHash": "0x1d8f...",
      "from": "0x3D3B...",
      "to": "0x9702...",
      "erc20Transfers": [
        {
          "valueWithDecimals": "110.56",
          "erc20Token": {
            "symbol": "USDt",
            "decimals": 6
          }
        }
      ]
    }
  }
}
```

You get everything you need:

* Decoded event data
* Token metadata (name, symbol, decimals)
* Full transaction context
* No extra calls. No parsing. No manual re-sync logic.

***

## Key Advantages of Webhooks

* **Reliable delivery with zero effort:** Built-in retries ensure no missed events during downtime
* **Instant enrichment:** Payloads contain decoded logs, token metadata, and transaction context
* **No extra infrastructure:** No WebSocket connections, no DB, no external APIs
* **Faster development:**  Go from idea to production with fewer moving parts
* **Lower operational cost:** Less compute, fewer network calls, smaller surface area to manage

If we compare using a table:

| Feature                        | WebSockets (Ethers.js/Viem)                        | Webhooks                                             |   |   |
| :----------------------------- | :------------------------------------------------- | :--------------------------------------------------- | - | - |
| **Interruption Handling**      | Manual; Requires complex custom logic              | Automatic; Built-in queues & retries                 |   |   |
| **Data Recovery**              | Requires DB + External API for re-sync             | Handled by provider; No re-sync logic needed         |   |   |
| **Dev Complexity**             | High; Error-prone custom resilience code           | Low; Focus on processing incoming POST data          |   |   |
| **Infrastructure**             | WSS connection + DB + Potential Data API cost      | Application API endpoint                             |   |   |
| **Data Integrity**             | Risk of gaps if recovery logic fails               | High; Ensures eventual delivery                      |   |   |
| **Payload**                    | Often raw; Requires extra calls for context        | Typically enriched and ready-to-use                  |   |   |
| **Multiple addresses**         | Manual filtering or separate listeners per address | Supports direct configuration for multiple addresses |   |   |
| **Listen to wallet addresses** | Requires manual block/transaction filtering        | Can monitor wallet addresses and smart contracts     |   |   |

## Summary

* WebSockets offer real-time access to Avalanche data, but come with complexity: raw logs, reconnect logic, re-sync handling, and decoding responsibilities.
* Webhooks flip the model: the data comes to you, pre-processed and reliable. You focus on your product logic instead of infrastructure.
* If you want to ship faster, operate more reliably, and reduce overhead, Webhooks are the better path forward for Avalanche event monitoring.

# Data API vs RPC (/docs/api-reference/data-api/data-vs-rpc)

---
title: Data API vs RPC
description: Comparison of the Data API and RPC methods
icon: Server
---

In the rapidly evolving world of Web3 development, efficiently retrieving token balances for a user's address is a fundamental requirement. Whether you're building DeFi platforms, wallets, analytics tools, or exchanges, displaying accurate token balances is crucial for user engagement and trust. A typical use case involves showing a user's token portfolio in a wallet application, in this case, we have sAvax and USDC.

<img src="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/wallet.png?fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=9a7596035baaa07bbeca4c3e65d54459" alt="title" data-og-width="3267" width="3267" data-og-height="2112" height="2112" data-path="images/wallet.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/wallet.png?w=280&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=e7852463251bb0cede8143ff4e777aae 280w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/wallet.png?w=560&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=523f9034b79bb173a77c3e8f1d1d5a37 560w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/wallet.png?w=840&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=65ff3d5662f91787c3eb2ae4b7675587 840w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/wallet.png?w=1100&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=7e68f4a1c8457c54efde9a989b2015f0 1100w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/wallet.png?w=1650&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=46e8d62f6c222b5f202db739928da286 1650w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/wallet.png?w=2500&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=6d72d4bda1aca25d96bc63cda3c7cf25 2500w" />

Developers generally have two options to fetch this data:

1. **Using RPC methods to index blockchain data on their own**
2. **Leveraging an indexer provider like the Data API**

While both methods aim to achieve the same goal, the Data API offers a more efficient, scalable, and developer-friendly solution. This article delves into why using the Data API is better than relying on traditional RPC (Remote Procedure Call) methods.

### What Are RPC methods and their challenges?

Remote Procedure Call (RPC) methods allow developers to interact directly with blockchain nodes. One of their key advantages is that they are standardized and universally understood by blockchain developers across different platforms. With RPC, you can perform tasks such as querying data, submitting transactions, and interacting with smart contracts. These methods are typically low-level and synchronous, meaning they require a deep understanding of the blockchain’s architecture and specific command structures.
You can refer to the [official documentation](https://ethereum.org/en/developers/docs/apis/json-rpc/) to gain a more comprehensive understanding of the JSON-RPC API.

Here’s an example using the `eth_getBalance` method to retrieve the native balance of a wallet:

```bash 
curl --location 'https://api.avax.network/ext/bc/C/rpc' \
--header 'Content-Type: application/json' \
--data '{"method":"eth_getBalance","params":["0x8ae323046633A07FB162043f28Cea39FFc23B50A", "latest"],"id":1,"jsonrpc":"2.0"}'
```

This call returns the following response:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x284476254bc5d594"
}
```

The balance in this wallet is 2.9016 AVAX. However, despite the wallet holding multiple tokens such as USDC, the `eth_getBalance` method only returns the AVAX amount and it does so in Wei and in hexadecimal format. This is not particularly human-readable, adding to the challenge for developers who need to manually convert the balance to a more understandable format.

#### No direct RPC methods to retrieve token balances

Despite their utility, RPC methods come with significant limitations when it comes to retrieving detailed token and transaction data. Currently, RPC methods do not provide direct solutions for the following:

* **Listing all tokens held by a wallet**: There is no RPC method that provides a complete list of ERC-20 tokens owned by a wallet.
* **Retrieving all transactions for a wallet**: : There is no direct method for fetching all transactions associated with a wallet.
* **Getting ERC-20/721/1155 token balances**: The `eth_getBalance` method only returns the balance of the wallet’s native token (such as AVAX on Avalanche) and cannot be used to retrieve ERC-20/721/1155 token balances.

To achieve these tasks using RPC methods alone, you would need to:

* **Query every block for transaction logs**: Scan the entire blockchain, which is resource-intensive and impractical.
* **Parse transaction logs**: Identify and extract ERC-20 token transfer events from each transaction.
* **Aggregate data**: Collect and process this data to compute balances and transaction histories.

#### Manual blockchain indexing is difficult and costly

Using RPC methods to fetch token balances involves an arduous process:

1. You must connect to a node and subscribe to new block events.
2. For each block, parse every transaction to identify ERC-20 token transfers involving the user's address.
3. Extract contract addresses and other relevant data from the parsed transactions.
4. Compute balances by processing transfer events.
5. Store the processed data in a database for quick retrieval and aggregation.

#### Why this is difficult:

* **Resource-Intensive**: Requires significant computational power and storage to process and store blockchain data.
* **Time-consuming**: Processing millions of blocks and transactions can take an enormous amount of time.
* **Complexity**: Handling edge cases like contract upgrades, proxy contracts, and non-standard implementations adds layers of complexity.
* **Maintenance**: Keeping the indexed data up-to-date necessitates continuous synchronization with new blocks being added to the blockchain.
* **High Costs**: Associated with servers, databases, and network bandwidth.

### The Data API Advantage

The Data API provides a streamlined, efficient, and scalable solution for fetching token balances. Here's why it's the best choice:
With a single API call, you can retrieve all ERC-20 token balances for a user's address:

```javascript
avalancheSDK.data.evm.balances.listErc20Balances({
  address: "0xYourAddress",
});
```

Sample Response:

```json
{
  "erc20TokenBalances": [
    {
      "ercType": "ERC-20",
      "chainId": "43114",
      "address": "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
      "name": "USD Coin",
      "symbol": "USDC",
      "decimals": 6,
      "price": {
        "value": 1.0,
        "currencyCode": "usd"
      },
      "balance": "15000000",
      "balanceValue": {
        "currencyCode": "usd",
        "value": 9.6
      },
      "logoUri": "https://images.ctfassets.net/gcj8jwzm6086/e50058c1-2296-4e7e-91ea-83eb03db95ee/8db2a492ce64564c96de87c05a3756fd/43114-0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E.png"
    }
    // Additional tokens...
  ]
}
```

As you can see with a single call the API returns an array of token balances for all the wallet tokens, including:

* **Token metadata**: Contract address, name, symbol, decimals.
* **Balance information**: Token balance in both hexadecimal and decimal formats, Also retrieves balances of native assets like ETH or AVAX.
* **Price data**: Current value in USD or other supported currencies, saving you the effort of integrating another API.
* **Visual assets**: Token logo URI for better user interface integration.

If you’re building a wallet, DeFi app, or any application that requires displaying balances, transaction history, or smart contract interactions, relying solely on RPC methods can be challenging. Just as there’s no direct RPC method to retrieve token balances, there’s also no simple way to fetch all transactions associated with a wallet, especially for ERC-20, ERC-721, or ERC-1155 token transfers.

However, by using the Data API, you can retrieve all token transfers for a given wallet **with a single API call**, making the process much more efficient. This approach simplifies tracking and displaying wallet activity without the need to manually scan the entire blockchain.

Below are two examples that demonstrate the power of the Data API: in the first, it returns all ERC transfers, including ERC-20, ERC-721, and ERC-1155 tokens, and in the second, it shows all internal transactions, such as when one contract interacts with another.

<Accordions>
  <Accordion title="List ERC transfers">
    [Lists ERC transfers](/data-api/evm-transactions/list-erc-transfers) for an ERC-20, ERC-721, or ERC-1155 contract address.

    ```javascript  theme={null}
    import { Avalanche } from "@avalanche-sdk/chainkit";

    const avalancheSDK = new Avalanche({
      apiKey: "<YOUR_API_KEY_HERE>",
      chainId: "43114",
      network: "mainnet",
    });

    async function run() {
      const result = await avalancheSDK.data.evm.transactions.listTransfers({
        startBlock: 6479329,
        endBlock: 6479330,
        pageSize: 10,
        address: "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
      });

      for await (const page of result) {
        // Handle the page
        console.log(page);
      }
    }

    run();
    ```

    Example response

    ```json  theme={null}
    {
      "nextPageToken": "<string>",
      "transfers": [
        {
          "blockNumber": "339",
          "blockTimestamp": 1648672486,
          "blockHash": "0x17533aeb5193378b9ff441d61728e7a2ebaf10f61fd5310759451627dfca2e7c",
          "txHash": "0x3e9303f81be00b4af28515dab7b914bf3dbff209ea10e7071fa24d4af0a112d4",
          "from": {
            "name": "Wrapped AVAX",
            "symbol": "WAVAX",
            "decimals": 18,
            "logoUri": "https://images.ctfassets.net/gcj8jwzm6086/5VHupNKwnDYJvqMENeV7iJ/fdd6326b7a82c8388e4ee9d4be7062d4/avalanche-avax-logo.svg",
            "address": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F"
          },
          "to": {
            "name": "Wrapped AVAX",
            "symbol": "WAVAX",
            "decimals": 18,
            "logoUri": "https://images.ctfassets.net/gcj8jwzm6086/5VHupNKwnDYJvqMENeV7iJ/fdd6326b7a82c8388e4ee9d4be7062d4/avalanche-avax-logo.svg",
            "address": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F"
          },
          "logIndex": 123,
          "value": "10000000000000000000",
          "erc20Token": {
            "address": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
            "name": "Wrapped AVAX",
            "symbol": "WAVAX",
            "decimals": 18,
            "logoUri": "https://images.ctfassets.net/gcj8jwzm6086/5VHupNKwnDYJvqMENeV7iJ/fdd6326b7a82c8388e4ee9d4be7062d4/avalanche-avax-logo.svg",
            "ercType": "ERC-20",
            "price": {
              "currencyCode": "usd",
              "value": "42.42"
            }
          }
        }
      ]
    }
    ```
  </Accordion>

  <Accordion title="List internal transactions">
    [Returns a list of internal transactions](/data-api/evm-transactions/list-internal-transactions) for an address and chain. Filterable by block range.

    ```javascript  theme={null}
    import { Avalanche } from "@avalanche-sdk/chainkit";

    const avalancheSDK = new Avalanche({
      apiKey: "<YOUR_API_KEY_HERE>",
      chainId: "43114",
      network: "mainnet",
    });

    async function run() {
      const result = await avalancheSDK.data.evm.transactions.listInternalTransactions({
        startBlock: 6479329,
        endBlock: 6479330,
        pageSize: 10,
        address: "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
      });

      for await (const page of result) {
        // Handle the page
        console.log(page);
      }
    }

    run();
    ```

    Example response

    ```json  theme={null}
    {
      "nextPageToken": "<string>",
      "transactions": [
        {
          "blockNumber": "339",
          "blockTimestamp": 1648672486,
          "blockHash": "0x17533aeb5193378b9ff441d61728e7a2ebaf10f61fd5310759451627dfca2e7c",
          "txHash": "0x3e9303f81be00b4af28515dab7b914bf3dbff209ea10e7071fa24d4af0a112d4",
          "from": {
            "name": "Wrapped AVAX",
            "symbol": "WAVAX",
            "decimals": 18,
            "logoUri": "https://images.ctfassets.net/gcj8jwzm6086/5VHupNKwnDYJvqMENeV7iJ/fdd6326b7a82c8388e4ee9d4be7062d4/avalanche-avax-logo.svg",
            "address": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F"
          },
          "to": {
            "name": "Wrapped AVAX",
            "symbol": "WAVAX",
            "decimals": 18,
            "logoUri": "https://images.ctfassets.net/gcj8jwzm6086/5VHupNKwnDYJvqMENeV7iJ/fdd6326b7a82c8388e4ee9d4be7062d4/avalanche-avax-logo.svg",
            "address": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F"
          },
          "internalTxType": "UNKNOWN",
          "value": "10000000000000000000",
          "isReverted": true,
          "gasUsed": "<string>",
          "gasLimit": "<string>"
        }
      ]
    }
    ```
  </Accordion>
</Accordions>

### Conclusion

Using the Data API over traditional RPC methods for fetching token balances offers significant advantages:

* **Efficiency**: Retrieve all necessary information in a single API call.
* **Simplicity**: Eliminates complex data processing and reduces development time.
* **Scalability**: Handles large volumes of data efficiently, suitable for real-time applications.
* **Comprehensive Data**: Provides enriched information, including token prices and logos.
* **Reliability**: Ensures data accuracy and consistency without the need for extensive error handling.
  For developers building Web3 applications, leveraging the Data API is the smarter choice. It not only simplifies your codebase but also enhances the user experience by providing accurate and timely data.

If you’re building cutting-edge Web3 applications, this API is the key to improving your workflow and performance. Whether you’re developing DeFi solutions, wallets, or analytics platforms, take your project to the next level. [Start today with the Data API](/data-api/getting-started) and experience the difference!

# Getting Started (/docs/api-reference/data-api/getting-started)

---
title: Getting Started
description: Getting Started with the Data API
icon: Book
---

<Steps>
  <Step title="Create your account">
    To begin, create your free account by visiting [Builder Hub Console](https://build.avax.network/login?callbackUrl=%2Fconsole%2Futilities%2Fdata-api-keys).

    <img src="https://mintcdn.com/avalabs-47ea3976/8mDGi0vi4sjxkC4H/images/builderhub-console-login.png?fit=max&auto=format&n=8mDGi0vi4sjxkC4H&q=85&s=5927ac95108dfe63037088d4c0a7f896" data-og-width="2674" width="2674" data-og-height="1606" height="1606" data-path="images/builderhub-console-login.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/avalabs-47ea3976/8mDGi0vi4sjxkC4H/images/builderhub-console-login.png?w=280&fit=max&auto=format&n=8mDGi0vi4sjxkC4H&q=85&s=a357dfa731f2e3e5e60dd37b052b2c29 280w, https://mintcdn.com/avalabs-47ea3976/8mDGi0vi4sjxkC4H/images/builderhub-console-login.png?w=560&fit=max&auto=format&n=8mDGi0vi4sjxkC4H&q=85&s=1fa134e801eb1a63aca1ef520878282a 560w, https://mintcdn.com/avalabs-47ea3976/8mDGi0vi4sjxkC4H/images/builderhub-console-login.png?w=840&fit=max&auto=format&n=8mDGi0vi4sjxkC4H&q=85&s=5aa62e6540313a8e9464abd2fd8325e6 840w, https://mintcdn.com/avalabs-47ea3976/8mDGi0vi4sjxkC4H/images/builderhub-console-login.png?w=1100&fit=max&auto=format&n=8mDGi0vi4sjxkC4H&q=85&s=3af03f95a370356f2d86c65067ecaed5 1100w, https://mintcdn.com/avalabs-47ea3976/8mDGi0vi4sjxkC4H/images/builderhub-console-login.png?w=1650&fit=max&auto=format&n=8mDGi0vi4sjxkC4H&q=85&s=457affef8d97909acab3b2c020ae041a 1650w, https://mintcdn.com/avalabs-47ea3976/8mDGi0vi4sjxkC4H/images/builderhub-console-login.png?w=2500&fit=max&auto=format&n=8mDGi0vi4sjxkC4H&q=85&s=a592489d1b4733663cc73500f0f92237 2500w" />
  </Step>

  <Step title="Get an API Key">
    Once the account is created:

    1. Navigating to [**Data API Keys**](https://build.avax.network/console/utilities/data-api-keys)
    2. Click on **Create API Key**
    3. Set an alias and click on **create**
    4. Copy the the value

    <img src="https://mintcdn.com/avalabs-47ea3976/8mDGi0vi4sjxkC4H/images/builderhub-console-api-key.png?fit=max&auto=format&n=8mDGi0vi4sjxkC4H&q=85&s=fbbca0d39686ca625c0db26ffdfb967f" data-og-width="2674" width="2674" data-og-height="1606" height="1606" data-path="images/builderhub-console-api-key.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/avalabs-47ea3976/8mDGi0vi4sjxkC4H/images/builderhub-console-api-key.png?w=280&fit=max&auto=format&n=8mDGi0vi4sjxkC4H&q=85&s=5d16eb786562e13ae4437e048c8836fa 280w, https://mintcdn.com/avalabs-47ea3976/8mDGi0vi4sjxkC4H/images/builderhub-console-api-key.png?w=560&fit=max&auto=format&n=8mDGi0vi4sjxkC4H&q=85&s=0195d9d6e78e965e588c9db2d42c2f19 560w, https://mintcdn.com/avalabs-47ea3976/8mDGi0vi4sjxkC4H/images/builderhub-console-api-key.png?w=840&fit=max&auto=format&n=8mDGi0vi4sjxkC4H&q=85&s=be8d87a620e31f28cf043b51f35515c2 840w, https://mintcdn.com/avalabs-47ea3976/8mDGi0vi4sjxkC4H/images/builderhub-console-api-key.png?w=1100&fit=max&auto=format&n=8mDGi0vi4sjxkC4H&q=85&s=c5dd26df4fcc8f2e9aedad4486f659b2 1100w, https://mintcdn.com/avalabs-47ea3976/8mDGi0vi4sjxkC4H/images/builderhub-console-api-key.png?w=1650&fit=max&auto=format&n=8mDGi0vi4sjxkC4H&q=85&s=13a0d28d662cd6aa612d598782fc7989 1650w, https://mintcdn.com/avalabs-47ea3976/8mDGi0vi4sjxkC4H/images/builderhub-console-api-key.png?w=2500&fit=max&auto=format&n=8mDGi0vi4sjxkC4H&q=85&s=f81f73c4884fdcac589a2465c953c92d 2500w" />

    <Callout>Always keep your API keys in a secure environment. Never expose them in public repositories, such as GitHub, or share them with unauthorized individuals. Compromised API keys can lead to unauthorized access and potential misuse of your account.</Callout>
  </Step>

  <Step title="Make a query">
    With your API Key you can start making queries, for example to get the latest block on the C-chain(43114):

    ```bash  theme={null}
      curl --location 'https://data-api.avax.network/v1/chains/43114/blocks' \
      --header 'accept: application/json' \
      --header 'x-glacier-api-key: <YOUR-API-KEY>' \
    ```

    And you should see something like this:

    ```json  theme={null}
    {
      "blocks": [
        {
          "blockNumber": "49889407",
          "blockTimestamp": 1724990250,
          "blockHash": "0xd34becc82943e3e49048cdd3f75b80a87e44eb3aed6b87cc06867a7c3b9ee213",
          "txCount": 1,
          "baseFee": "25000000000",
          "gasUsed": "53608",
          "gasLimit": "15000000",
          "gasCost": "0",
          "parentHash": "0xf4917efb4628a1d8f4d101b3d15bce9826e62ef2c93c3e16ee898d27cf02f3d4",
          "feesSpent": "1435117553916960",
          "cumulativeTransactions": "500325352"
        },
        {
          "blockNumber": "49889406",
          "blockTimestamp": 1724990248,
          "blockHash": "0xf4917efb4628a1d8f4d101b3d15bce9826e62ef2c93c3e16ee898d27cf02f3d4",
          "txCount": 2,
          "baseFee": "25000000000",
          "gasUsed": "169050",
          "gasLimit": "15000000",
          "gasCost": "0",
          "parentHash": "0x2a54f142fa3acee92a839b071bb6c7cca7abc2a797cf4aac68b07f79406ac0cb",
          "feesSpent": "4226250000000000",
          "cumulativeTransactions": "500325351"
        },
        {
          "blockNumber": "49889405",
          "blockTimestamp": 1724990246,
          "blockHash": "0x2a54f142fa3acee92a839b071bb6c7cca7abc2a797cf4aac68b07f79406ac0cb",
          "txCount": 4,
          "baseFee": "25000000000",
          "gasUsed": "618638",
          "gasLimit": "15000000",
          "gasCost": "0",
          "parentHash": "0x0cda1bb5c86e790976c9330c9fc26e241a705afbad11a4caa44df1c81058451d",
          "feesSpent": "16763932426044724",
          "cumulativeTransactions": "500325349"
        },
        {
          "blockNumber": "49889404",
          "blockTimestamp": 1724990244,
          "blockHash": "0x0cda1bb5c86e790976c9330c9fc26e241a705afbad11a4caa44df1c81058451d",
          "txCount": 3,
          "baseFee": "25000000000",
          "gasUsed": "254544",
          "gasLimit": "15000000",
          "gasCost": "0",
          "parentHash": "0x60e55dd9eacc095c07f50a73e02d81341c406584f7abbf5d10d938776a4c893c",
          "feesSpent": "6984642298020000",
          "cumulativeTransactions": "500325345"
        },
        {
          "blockNumber": "49889403",
          "blockTimestamp": 1724990242,
          "blockHash": "0x60e55dd9eacc095c07f50a73e02d81341c406584f7abbf5d10d938776a4c893c",
          "txCount": 2,
          "baseFee": "25000000000",
          "gasUsed": "65050",
          "gasLimit": "15000000",
          "gasCost": "0",
          "parentHash": "0xa3e9f91f45a85ed00b8ebe8e5e976ed1a1f52612143eddd3de9d2588d05398b8",
          "feesSpent": "1846500000000000",
          "cumulativeTransactions": "500325342"
        },
        {
          "blockNumber": "49889402",
          "blockTimestamp": 1724990240,
          "blockHash": "0xa3e9f91f45a85ed00b8ebe8e5e976ed1a1f52612143eddd3de9d2588d05398b8",
          "txCount": 2,
          "baseFee": "25000000000",
          "gasUsed": "74608",
          "gasLimit": "15000000",
          "gasCost": "0",
          "parentHash": "0x670db772edfc2fdae322d55473ba0670690aed6358a067a718492c819d63356a",
          "feesSpent": "1997299851936960",
          "cumulativeTransactions": "500325340"
        },
        {
          "blockNumber": "49889401",
          "blockTimestamp": 1724990238,
          "blockHash": "0x670db772edfc2fdae322d55473ba0670690aed6358a067a718492c819d63356a",
          "txCount": 1,
          "baseFee": "25000000000",
          "gasUsed": "273992",
          "gasLimit": "15000000",
          "gasCost": "0",
          "parentHash": "0x75742cf45383ce54823690b9dd2e85a743be819281468163d276f145d077902a",
          "feesSpent": "7334926295195040",
          "cumulativeTransactions": "500325338"
        },
        {
          "blockNumber": "49889400",
          "blockTimestamp": 1724990236,
          "blockHash": "0x75742cf45383ce54823690b9dd2e85a743be819281468163d276f145d077902a",
          "txCount": 1,
          "baseFee": "25000000000",
          "gasUsed": "291509",
          "gasLimit": "15000000",
          "gasCost": "0",
          "parentHash": "0xe5055eae3e1fd2df24b61e9c691f756c97e5619cfc66b69cbcb6025117d1bde7",
          "feesSpent": "7724988500000000",
          "cumulativeTransactions": "500325337"
        },
        {
          "blockNumber": "49889399",
          "blockTimestamp": 1724990234,
          "blockHash": "0xe5055eae3e1fd2df24b61e9c691f756c97e5619cfc66b69cbcb6025117d1bde7",
          "txCount": 8,
          "baseFee": "25000000000",
          "gasUsed": "824335",
          "gasLimit": "15000000",
          "gasCost": "0",
          "parentHash": "0xbcacff928f7dd20cc1522155e7c9b9716997914b53ab94034b813c3f207174ef",
          "feesSpent": "21983004380692400",
          "cumulativeTransactions": "500325336"
        },
        {
          "blockNumber": "49889398",
          "blockTimestamp": 1724990229,
          "blockHash": "0xbcacff928f7dd20cc1522155e7c9b9716997914b53ab94034b813c3f207174ef",
          "txCount": 1,
          "baseFee": "25000000000",
          "gasUsed": "21000",
          "gasLimit": "15000000",
          "gasCost": "0",
          "parentHash": "0x0b686812078429d33e4224d2b48bd26b920db8dbb464e7f135d980759ca7e947",
          "feesSpent": "562182298020000",
          "cumulativeTransactions": "500325328"
        }
      ],
      "nextPageToken": "9f9e1d25-14a9-49f4-8742-fd4bf12f7cd8"
    }
    ```
  </Step>
</Steps>

Congratulations! You’ve successfully set up your account and made your first query to the Data API  🚀🚀🚀

# Data API (/docs/api-reference/data-api)

---
title: Data API
description: Access comprehensive blockchain data for Avalanche networks
icon: Database
---

### What is the Data API?

The Data API provides web3 application developers with multi-chain data related to Avalanche's primary network, Avalanche L1s, and Ethereum. With the Data API, you can easily build products that leverage real-time and historical transaction and transfer history, native and token balances, and various types of token metadata.

<img src="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/data-api.png?fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=8de5972a10c0c85d6e54a310c3a8c2cc" alt="Data API" data-og-width="3126" width="3126" data-og-height="2807" height="2807" data-path="images/data-api.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/data-api.png?w=280&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=f26740e5df60f89cb7a2995bb1cf3f69 280w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/data-api.png?w=560&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=2c9319348ada91f26f8b315e4ca479c6 560w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/data-api.png?w=840&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=da79bcd6b56c5bba79bd3df8ec641d94 840w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/data-api.png?w=1100&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=e9bd34bb1bb349e2b3bc59f1805ca2d4 1100w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/data-api.png?w=1650&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=6b235051a376fd4d54720b9ad1ae346e 1650w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/data-api.png?w=2500&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=ce2f4992fd320a6dccf87677b63fb380 2500w" />

The [Data API](/docs/api-reference/data-api), along with the [Metrics API](/docs/api-reference/metrics-api), are the engines behind the [Avalanche Explorer](https://subnets.avax.network/stats/) and the [Core wallet](https://core.app/en/). They are used to display transactions, logs, balances, NFTs, and more. The data and visualizations presented are all powered by these APIs, offering real-time and historical insights that are essential for building sophisticated, data-driven blockchain products.

### Features

* **Extensive L1 Support**: Gain access to data from over 100+ L1s across both mainnet and testnet. If an L1 is listed on the [Avalanche Explorer](https://subnets.avax.network/), you can query its data using the Data API.
* **Transactions and UTXOs**: easily retrieve details related to transactions, UTXOs, and token transfers from Avalanche EVMs, Ethereum, and Avalanche's Primary Network - the P-Chain, X-Chain and C-Chain.
* **Blocks**: retrieve latest blocks and block details
* **Balances**: fetch balances of native, ERC-20, ERC-721, and ERC-1155 tokens along with relevant metadata.
* **Tokens**: augment your user experience with asset details.
* **Staking**: get staking related data for active and historical validations.

### Supported Chains

Avalanche’s architecture supports a diverse ecosystem of interconnected L1 blockchains, each operating independently while retaining the ability to seamlessly communicate with other L1s within the network. Central to this architecture is the Primary Network—Avalanche’s foundational network layer, which all validators are required to validate prior to [ACP-77](/docs/acps/77-reinventing-subnets). The Primary Network runs three essential blockchains:

* The Contract Chain (C-Chain)
* The Platform Chain (P-Chain)
* The Exchange Chain (X-Chain)

However, with the implementation of [ACP-77](/docs/acps/77-reinventing-subnets), this requirement will change. Subnet Validators will be able to operate independently of the Primary Network, allowing for more flexible and affordable Subnet creation and management.

The **Data API** supports a wide range of L1 blockchains (**over 100**) across both **mainnet** and **testnet**, including popular ones like Beam, DFK, Lamina1, Dexalot, Shrapnel, and Pulsar. In fact, every L1 you see on the [Avalanche Explorer](https://explorer.avax.network/) can be queried through the Data API. This list is continually expanding as we keep adding more L1s. For a full list of supported chains, visit [List chains](/docs/api-reference/data-api/evm-chains/list-chains).

#### The Contract Chain (C-Chain)

The C-Chain is an implementation of the Ethereum Virtual Machine (EVM). The primary network endpoints only provide information related to C-Chain atomic memory balances and import/export transactions. For additional data, please reference the [EVM APIs](/docs/rpcs/c-chain/rpc).

#### The Platform Chain (P-Chain)

The P-Chain is responsible for all validator and L1-level operations. The P-Chain supports the creation of new blockchains and L1s, the addition of validators to L1s, staking operations, and other platform-level operations.

#### The Exchange Chain (X-Chain)

The X-Chain is responsible for operations on digital smart assets known as Avalanche Native Tokens. A smart asset is a representation of a real-world resource (for example, equity, or a bond) with sets of rules that govern its behavior, like "can’t be traded until tomorrow." The X-Chain supports the creation and trade of Avalanche Native Tokens.

| Feature          | Description                                                                                                                                                                                                                                                                                                                                                                              |
| :--------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Chains**       | Utilize this endpoint to retrieve the Primary Network chains that an address has transaction history associated with.                                                                                                                                                                                                                                                                    |
| **Blocks**       | Blocks are the container for transactions executed on the Primary Network. Retrieve the latest blocks, a specific block by height or hash, or a list of blocks proposed by a specified NodeID on Primary Network chains.                                                                                                                                                                 |
| **Vertices**     | Prior to Avalanche Cortina (v1.10.0), the X-Chain functioned as a DAG with vertices rather than blocks. These endpoints allow developers to retrieve historical data related to that period of chain history. Retrieve the latest vertices, a specific vertex, or a list of vertices at a specific height from the X-Chain.                                                              |
| **Transactions** | Transactions are a user's primary form of interaction with a chain and provide details around their on-chain activity, including staking-related behavior. Retrieve a list of the latest transactions, a specific transaction, a list of active staking transactions for a specified address, or a list of transactions associated with a provided asset id from Primary Network chains. |
| **UTXOs**        | UTXOs are fundamental elements that denote the funds a user has available. Get a list of UTXOs for provided addresses from the Primary Network chains.                                                                                                                                                                                                                                   |
| **Balances**     | User balances are an essential function of the blockchain. Retrieve balances related to the X and P-Chains, as well as atomic memory balances for the C-Chain.                                                                                                                                                                                                                           |
| **Rewards**      | Staking is the process where users lock up their tokens to support a blockchain network and, in return, receive rewards. It is an essential part of proof-of-stake (PoS) consensus mechanisms used by many blockchain networks, including Avalanche. Using the Data API, you can easily access pending and historical rewards associated with a set of addresses.                        |
| **Assets**       | Get asset details corresponding to the given asset id on the X-Chain.                                                                                                                                                                                                                                                                                                                    |

#### EVM

The C-Chain is an instance of the Coreth Virtual Machine, and many Avalanche L1s are instances of the *Subnet-EVM*, which is a Virtual Machine (VM) that defines the L1 Contract Chains. *Subnet-EVM* is a simplified version of *Coreth VM* (C-Chain).

| Feature          | Description                                                                                                                                                                                                                                                                                                   |
| :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Chains**       | There are a number of chains supported by the Data API. These endpoints can be used to understand which chains are included/indexed as part of the API and retrieve information related to a specific chain.                                                                                                  |
| **Blocks**       | Blocks are the container for transactions executed within the EVM. Retrieve the latest blocks or a specific block by height or hash.                                                                                                                                                                          |
| **Transactions** | Transactions are a user's primary form of interaction with a chain and provide details around their on-chain activity. These endpoints can be used to retrieve information related to specific transaction details, internal transactions, contract deployments, specific token standard transfers, and more! |
| **Balances**     | User balances are an essential function of the blockchain. Easily retrieve native token, collectible, and fungible token balances related to an EVM chain with these endpoints.                                                                                                                               |

#### Operations

The Operations API allows users to easily access their on-chain history by creating transaction exports returned in a CSV format. This API supports EVMs as well as non-EVM Primary Network chains.

# Rate Limits (/docs/api-reference/data-api/rate-limits)

---
title: Rate Limits
description: Rate Limits for the Data API
icon: Clock
---

Rate limiting is managed through a weighted scoring system, known as Compute Units (CUs). Each API request consumes a specified number of CUs, determined by the complexity of the request. This system is designed to accommodate basic requests while efficiently handling more computationally intensive operations.

## Rate Limit Tiers

The maximum CUs (rate-limiting score) for a user depends on their subscription level and is delineated in the following table:

| Subscription Level | Per Minute Limit (CUs) | Per Day Limit (CUs) |
| :----------------- | :--------------------- | :------------------ |
| Unauthenticated    | 6,000                  | 1,200,000           |
| Free               | 8,000                  | 2,000,000           |
| Base               | 10,000                 | 3,750,000           |
| Growth             | 14,000                 | 11,200,000          |
| Pro                | 20,000                 | 25,000,000          |

To update your subscription level use the [AvaCloud Portal](https://app.avacloud.io/)

<Info> Note: Rate limits apply collectively across both Webhooks and Data APIs, with usage from each counting toward your total CU limit. </Info>

## Rate Limit Categories

The CUs for each category are defined in the following table:

| Weight | CU Value |
| :----- | :------- |
| Free   | 1        |
| Small  | 10       |
| Medium | 20       |
| Large  | 50       |
| XL     | 100      |
| XXL    | 200      |

## Rate Limits for Data API Endpoints

The CUs for each route are defined in the table below:

| Endpoint                                                                          | Method | Weight | CU Value |
| :-------------------------------------------------------------------------------- | :----- | :----- | :------- |
| `/v1/health-check`                                                                | GET    | Medium | 20       |
| `/v1/address/{address}/chains`                                                    | GET    | Medium | 20       |
| `/v1/transactions`                                                                | GET    | Medium | 20       |
| `/v1/blocks`                                                                      | GET    | Medium | 20       |
| `/v1/chains/{chainId}/nfts/collections/{address}/tokens/{tokenId}:reindex`        | POST   | Small  | 10       |
| `/v1/chains/{chainId}/nfts/collections/{address}/tokens`                          | GET    | Medium | 20       |
| `/v1/chains/{chainId}/nfts/collections/{address}/tokens/{tokenId}`                | GET    | Medium | 20       |
| `/v1/operations/{operationId}`                                                    | GET    | Small  | 10       |
| `/v1/operations/transactions:export`                                              | POST   | Medium | 20       |
| `/v1/networks/{network}/blockchains/{blockchainId}/transactions/{txHash}`         | GET    | Medium | 20       |
| `/v1/networks/{network}/blockchains/{blockchainId}/transactions`                  | GET    | XL     | 100      |
| `/v1/networks/{network}/blockchains/{blockchainId}/transactions:listStaking`      | GET    | XL     | 100      |
| `/v1/networks/{network}/rewards:listPending`                                      | GET    | XL     | 100      |
| `/v1/networks/{network}/rewards`                                                  | GET    | XL     | 100      |
| `/v1/networks/{network}/blockchains/{blockchainId}/utxos`                         | GET    | XL     | 100      |
| `/v1/networks/{network}/blockchains/{blockchainId}/balances`                      | GET    | XL     | 100      |
| `/v1/networks/{network}/blockchains/{blockchainId}/blocks/{blockId}`              | GET    | XL     | 100      |
| `/v1/networks/{network}/blockchains/{blockchainId}/nodes/{nodeId}/blocks`         | GET    | Medium | 20       |
| `/v1/networks/{network}/blockchains/{blockchainId}/blocks`                        | GET    | Medium | 20       |
| `/v1/networks/{network}/blockchains/{blockchainId}/vertices`                      | GET    | Medium | 20       |
| `/v1/networks/{network}/blockchains/{blockchainId}/vertices/{vertexHash}`         | GET    | Medium | 20       |
| `/v1/networks/{network}/blockchains/{blockchainId}/vertices:listByHeight`         | GET    | Medium | 20       |
| `/v1/networks/{network}/blockchains/{blockchainId}/assets/{assetId}`              | GET    | XL     | 100      |
| `/v1/networks/{network}/blockchains/{blockchainId}/assets/{assetId}/transactions` | GET    | XL     | 100      |
| `/v1/networks/{network}/addresses:listChainIds`                                   | GET    | XL     | 100      |
| `/v1/networks/{network}`                                                          | GET    | XL     | 100      |
| `/v1/networks/{network}/blockchains`                                              | GET    | Medium | 20       |
| `/v1/networks/{network}/subnets`                                                  | GET    | Medium | 20       |
| `/v1/networks/{network}/subnets/{subnetId}`                                       | GET    | Medium | 20       |
| `/v1/networks/{network}/validators`                                               | GET    | Medium | 20       |
| `/v1/networks/{network}/validators/{nodeId}`                                      | GET    | Medium | 20       |
| `/v1/networks/{network}/delegators`                                               | GET    | Medium | 20       |
| `/v1/networks/{network}/l1Validators`                                             | GET    | Medium | 20       |
| `/v1/teleporter/messages/{messageId}`                                             | GET    | Medium | 20       |
| `/v1/teleporter/messages`                                                         | GET    | Medium | 20       |
| `/v1/teleporter/addresses/{address}/messages`                                     | GET    | Medium | 20       |
| `/v1/icm/messages/{messageId}`                                                    | GET    | Medium | 20       |
| `/v1/icm/messages`                                                                | GET    | Medium | 20       |
| `/v1/icm/addresses/{address}/messages`                                            | GET    | Medium | 20       |
| `/v1/apiUsageMetrics`                                                             | GET    | XXL    | 200      |
| `/v1/apiLogs`                                                                     | GET    | XXL    | 200      |
| `/v1/subnetRpcUsageMetrics`                                                       | GET    | XXL    | 200      |
| `/v1/rpcUsageMetrics`                                                             | GET    | XXL    | 200      |
| `/v1/primaryNetworkRpcUsageMetrics`                                               | GET    | XXL    | 200      |
| `/v1/signatureAggregator/{network}/aggregateSignatures`                           | POST   | Medium | 20       |
| `/v1/signatureAggregator/{network}/aggregateSignatures/{txHash}`                  | GET    | Medium | 20       |
| `/v1/chains/{chainId}/addresses/{address}/balances:getNative`                     | GET    | Medium | 20       |
| `/v1/chains/{chainId}/addresses/{address}/balances:listErc20`                     | GET    | Medium | 20       |
| `/v1/chains/{chainId}/addresses/{address}/balances:listErc721`                    | GET    | Medium | 20       |
| `/v1/chains/{chainId}/addresses/{address}/balances:listErc1155`                   | GET    | Medium | 20       |
| `/v1/chains/{chainId}/addresses/{address}/balances:listCollectibles`              | GET    | Medium | 20       |
| `/v1/chains/{chainId}/blocks`                                                     | GET    | Small  | 10       |
| `/v1/chains/{chainId}/blocks/{blockId}`                                           | GET    | Small  | 10       |
| `/v1/chains/{chainId}/contracts/{address}/transactions:getDeployment`             | GET    | Medium | 20       |
| `/v1/chains/{chainId}/contracts/{address}/deployments`                            | GET    | Medium | 20       |
| `/v1/chains/{chainId}/addresses/{address}`                                        | GET    | Medium | 20       |
| `/v1/chains`                                                                      | GET    | Free   | 1        |
| `/v1/chains/{chainId}`                                                            | GET    | Free   | 1        |
| `/v1/chains/address/{address}`                                                    | GET    | Free   | 1        |
| `/v1/chains/allTransactions`                                                      | GET    | Free   | 1        |
| `/v1/chains/allBlocks`                                                            | GET    | Free   | 1        |
| `/v1/chains/{chainId}/tokens/{address}/transfers`                                 | GET    | Medium | 20       |
| `/v1/chains/{chainId}/addresses/{address}/transactions`                           | GET    | Medium | 20       |
| `/v1/chains/{chainId}/addresses/{address}/transactions:listNative`                | GET    | Medium | 20       |
| `/v1/chains/{chainId}/addresses/{address}/transactions:listErc20`                 | GET    | Medium | 20       |
| `/v1/chains/{chainId}/addresses/{address}/transactions:listErc721`                | GET    | Medium | 20       |
| `/v1/chains/{chainId}/addresses/{address}/transactions:listErc1155`               | GET    | Medium | 20       |
| `/v1/chains/{chainId}/addresses/{address}/transactions:listInternals`             | GET    | Medium | 20       |
| `/v1/chains/{chainId}/transactions/{txHash}`                                      | GET    | Medium | 20       |
| `/v1/chains/{chainId}/blocks/{blockId}/transactions`                              | GET    | Medium | 20       |
| `/v1/chains/{chainId}/transactions`                                               | GET    | Medium | 20       |

## Rate Limits for RPC endpoints

The CUs for RPC calls are calculated based on the RPC method(s) within the request. The CUs assigned to each method are defined in the table below:

| Method                                    | Weight | CU Value |
| :---------------------------------------- | :----- | :------- |
| `eth_accounts`                            | Free   | 1        |
| `eth_blockNumber`                         | Small  | 10       |
| `eth_call`                                | Small  | 10       |
| `eth_coinbase`                            | Small  | 10       |
| `eth_chainId`                             | Free   | 1        |
| `eth_gasPrice`                            | Small  | 10       |
| `eth_getBalance`                          | Small  | 10       |
| `eth_getBlockByHash`                      | Small  | 10       |
| `eth_getBlockByNumber`                    | Small  | 10       |
| `eth_getBlockTransactionCountByNumber`    | Medium | 20       |
| `eth_getCode`                             | Medium | 20       |
| `eth_getLogs`                             | XXL    | 200      |
| `eth_getStorageAt`                        | Medium | 20       |
| `eth_getTransactionByBlockNumberAndIndex` | Medium | 20       |
| `eth_getTransactionByHash`                | Small  | 10       |
| `eth_getTransactionCount`                 | Small  | 10       |
| `eth_getTransactionReceipt`               | Small  | 10       |
| `eth_signTransaction`                     | Medium | 20       |
| `eth_sendTransaction`                     | Medium | 20       |
| `eth_sign`                                | Medium | 20       |
| `eth_sendRawTransaction`                  | Small  | 10       |
| `eth_syncing`                             | Free   | 1        |
| `net_listening`                           | Free   | 1        |
| `net_peerCount`                           | Medium | 20       |
| `net_version`                             | Free   | 1        |
| `web3_clientVersion`                      | Small  | 10       |
| `web3_sha3`                               | Small  | 10       |
| `eth_newPendingTransactionFilter`         | Medium | 20       |
| `eth_maxPriorityFeePerGas`                | Small  | 10       |
| `eth_baseFee`                             | Small  | 10       |
| `rpc_modules`                             | Free   | 1        |
| `eth_getChainConfig`                      | Small  | 10       |
| `eth_feeConfig`                           | Small  | 10       |
| `eth_getActivePrecompilesAt`              | Small  | 10       |

<Info> All rate limits, weights, and CU values are subject to change. </Info>

# Snowflake Datashare (/docs/api-reference/data-api/snowflake)

---
title: Snowflake Datashare
description: Snowflake Datashare for Avalanche blockchain data
icon: Snowflake
---

Avalanche Primary Network data (C-chain, P-chain, and X-chain blockchains) can be accessed in a sql-based table format via the [Snowflake Data Marketplace.](https://app.snowflake.com/marketplace)

Explore the blockchain state since the Genesis Block. These tables provide insights on transaction gas fees, DeFi activity, the historical stake of validators on the primary network, AVAX emissions rewarded to past validators/delegators, and fees paid by Avalanche L1 Validators to the primary network.

## Available Blockchain Data

#### Primary Network

* **C-chain:**
  * Blocks
  * Transactions
  * Logs
  * Internal Transactions
  * Receipts
  * Messages
* **P-chain:**
  * Blocks
  * Transactions
  * UTXOs
* **X-chain:**
  * Blocks
  * Transactions
  * Vertices before the [X-chain Linearization](https://www.avax.network/blog/cortina-x-chain-linearization) in the Cortina Upgrade
* **Dictionary:** A data dictionary is provided with the listing with column and table descriptions. Example columns include:
  * `c_blocks.blockchash`
  * `c_transactions.transactionfrom`
  * `c_logs.topichex_0`
  * `p_blocks.block_hash`
  * `p_blocks.block_index`
  * `p_blocks.type`
  * `p_transactions.timestamp`
  * `p_transactions.transaction_hash`
  * `utxos.utxo_id`
  * `utxos.address`
  * `vertices.vertex_hash`
  * `vertices.parent_hash`
  * `x_blocks.timestamp`
  * `x_blocks.proposer_id`
  * `x_transactions.transaction_hash`
  * `x_transactions.type`

#### Available Avalanche L1s

* **Gunzilla**
* **Dexalot**
* **DeFi Kingdoms (DFK)**
* **Henesys (MapleStory Universe)**

#### L1 Data

* Blocks
* Transactions
* Logs
* Internal Transactions (currently unavailable for DFK)
* Receipts
* Messages

## Access

Search for "Ava Labs" on the [Snowflake Data Marketplace](https://app.snowflake.com/marketplace).

# Usage Guide (/docs/api-reference/data-api/usage)

---
title: Usage Guide
description: Usage Guide for the Data API
icon: Code
---

### Setup and Authentication

In order to utilize your accounts rate limits, you will need to make API requests with an API key. You can generate API Keys from the AvaCloud portal. Once you've created and retrieved that, you will be able to make authenticated queries by passing in your API key in the `x-glacier-api-key` header of your HTTP request.

An example curl request can be found below:

```bash
curl -H "Content-Type: Application/json" -H "x-glacier-api-key: your_api_key" \
  "https://glacier-api.avax.network/v1/chains"
```

### Rate Limits

The Data API has rate limits in place to maintain it's stability and protect from bursts of incoming traffic. The rate limits associated with various plans can be found within AvaCloud.

When you hit your rate limit, the server will respond with a 429 http response code, and response headers to help you determine when you should start to make additional requests. The response headers follow the standards set in the RateLimit header fields for HTTP draft from the Internet Engineering Task Force.

With every response with a valid api key, the server will include the following headers:

* `ratelimit-policy` - The rate limit policy tied to your api key.
* `ratelimit-limit` - The number of requests you can send according to your policy.
* `ratelimit-remaining` - How many request remaining you can send in the period for your policy

For any request after the rate limit has been reached, the server will also respond with these headers:

* `ratelimit-reset`
* `retry-after`
  Both of these headers are set to the number of seconds until your period is over and requests will start succeeding again.

If you start receiving rate limit errors with the 429 response code, we recommend you discontinue sending requests to the server. You should wait to retry requests for the duration specified in the response headers. Alternatively, you can implement an exponential backoff algorithm to prevent continuous errors. Failure to discontinue requests may result in being temporarily blocked from accessing the API.

Error Types
The Data API generates standard error responses along with error codes based on provided requests and parameters.

Typically, response codes within the `2XX` range signifies successful requests, while those within the `4XX` range points to errors originating from the client's side. Meanwhile, response codes within the `5XX` range indicates problems on the server's side.

### Error Types

The Glacier API generates standard error responses along with error codes based on provided requests and parameters.

Typically, response codes within the `2XX` range signifies successful requests, while those within the `4XX` range points to errors originating from the client's side. Meanwhile, response codes within the `5XX` range indicates problems on the server's side.

The error response body is formatted like this:

```json
{
  "message": ["Invalid address format"], // route specific error message
  "error": "Bad Request", // error type
  "statusCode": 400 // http response code
}
```

Let's go through every error code that we can respond with:

| Error Code | Error Type            | Description                                                                                                                                                                                                                   |
| :--------- | :-------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **400**    | Bad Request           | Bad requests generally mean the client has passed invalid or malformed parameters. Error messages in the response could help in evaluating the error.                                                                         |
| **401**    | Unauthorized          | When a client attempts to access resources that require authorization credentials but the client lacks proper authentication in the request, the server responds with 401.                                                    |
| **403**    | Forbidden             | When a client attempts to access resources with valid credentials but doesn't have the privilege to perform that action, the server responds with 403.                                                                        |
| **404**    | Not Found             | The 404 error is mostly returned when the client requests with either mistyped URL, or the passed resource is moved or deleted, or the resource doesn't exist.                                                                |
| **500**    | Internal Server Error | The 500 error is a generic server-side error that is returned for any uncaught and unexpected issues on the server side. This should be very rare, and you may reach out to us if the problem persists for a longer duration. |
| **502**    | Bad Gateway           | This is an internal error indicating invalid response received by the client-facing proxy or gateway from the upstream server.                                                                                                |
| **503**    | Service Unavailable   | The 503 error is returned for certain routes on a particular Subnet. This indicates an internal problem with our Subnet node, and may not necessarily mean the Subnet is down or affected.                                    |

The above list is not exhaustive of all the errors that you'll receive, but is categorized on the basis of error codes. You may see route-specific errors along with detailed error messages for better evaluating the response.

<Callout>Reach out to our team when you see an error in the `5XX` range for a longer duration. These errors should be very rare, but we try to fix them as soon as possible once detected.</Callout>

### Pagination

When utilizing pagination for endpoints that return lists of data such as transactions, UTXOs, or blocks, our API uses a straightforward mechanism to manage the navigation through large datasets. We divide data into pages and each page is limited with a `pageSize` number of elements as passed in the request. Users can navigate to subsequent pages using the page token received in the `nextPageToken` field. This method ensures efficient retrieval.

Routes with pagination have a following common response format:

```json
{
  "blocks": ["<blocks>"], // This field name will vary by route
  "nextPageToken": "3d22deea-ea64-4d30-8a1e-c2a353b67e90"
}
```

### Page Token Structure

* If there's more data in the dataset for the request, the API will include a UUID-based page token in the response. This token acts as a pointer to the next page of data.
* The UUID page token is generated randomly and uniquely for each pagination scenario, enhancing security and minimizing predictability.
* It's important to note that the page token is only returned when a next page is present. If there's no further data to retrieve, a page token will not be included in the response.
* The generated page token has an expiration window of 24 hours. Beyond this timeframe, the token will no longer be valid for accessing subsequent pages.

### Integration and Usage:

To make use of the pagination system, simply examine the API response. If a UUID page token is present, it indicates the availability of additional data on the next page. You can extract this token and include it in the subsequent request to access the subsequent page of results.

Please note that you must ensure that the subsequent request is made within the 24-hour timeframe after the original token's generation. Beyond this duration, the token will expire, and you will need to initiate a fresh request from the initial page.

By incorporating UUID page tokens, our API offers a secure, efficient, and user-friendly approach to navigating large datasets, streamlining your data retrieval proces

### Swagger API Reference

You can explore the full API definitions and interact with the endpoints in the Swagger documentation at:

<Cards cols={1}>
  <Card title="Swagger API Reference">
    [https://glacier-api.avax.network/api](https://glacier-api.avax.network/api)
  </Card>
</Cards>

# Chain Components (/docs/builderkit/components/chains)

---
title: Chain Components
description: "Components for displaying and selecting blockchain networks."
---

# Chain Components

Chain components help you manage network selection and display chain information.

## ChainIcon

The ChainIcon component displays chain logos.

```tsx
import { ChainIcon } from '@avalabs/builderkit';

// Basic usage
<ChainIcon chain_id={43114} />
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `chain_id` | `number` | - | Chain ID to display |
| `className` | `string` | - | Additional CSS classes |

## ChainDropdown

The ChainDropdown component provides network selection functionality.

```tsx
import { ChainDropdown } from '@avalabs/builderkit';

// Basic usage
<ChainDropdown
  selected={43114}
  list={[43114, 43113]}
  onSelectionChanged={(chainId) => {
    console.log('Selected chain:', chainId);
  }}
/>
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `selected` | `number` | - | Currently selected chain ID |
| `list` | `number[]` | - | List of available chain IDs |
| `onSelectionChanged` | `(chain_id: number) => void` | - | Selection change callback |
| `className` | `string` | - | Additional CSS classes |

## ChainRow

The ChainRow component displays detailed chain information.

```tsx
import { ChainRow } from '@avalabs/builderkit';

// Basic usage
<ChainRow
  chain_id={43114}
  name="Avalanche C-Chain"
/>
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `chain_id` | `number` | - | Chain ID |
| `name` | `string` | - | Chain name |
| `className` | `string` | - | Additional CSS classes |

# Control Components (/docs/builderkit/components/control)

---
title: Control Components
description: "Interactive control components like buttons and wallet connection interfaces."
---

# Control Components

Control components provide interactive elements for your Web3 application.

## Button

The Button component is a versatile control that supports multiple states and actions.

```tsx
import { Button } from '@avalabs/builderkit';

// Basic usage
<Button 
  label="Click me"
  action={() => console.log('Button clicked')}
/>

// With loading state
<Button 
  label="Processing..."
  action={() => {}}
  status="loading"
/>

// Disabled state
<Button 
  label="Unavailable"
  action={() => {}}
  status="disabled"
/>
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `label` | `string` | - | Text to display on the button |
| `action` | `() => void` | - | Function to execute when button is clicked |
| `status` | `'idle' \| 'loading' \| 'disabled'` | `'idle'` | Current state of the button |
| `className` | `string` | - | Additional CSS classes |

## ConnectButton

The ConnectButton component provides wallet connection functionality.

```tsx
import { ConnectButton } from '@avalabs/builderkit';

// Basic usage
<ConnectButton />

// With wallet display
<ConnectButton 
  showConnectedWallet={true}
  checkWrongNetwork={true}
/>
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `showConnectedWallet` | `boolean` | `false` | Show connected wallet address |
| `checkWrongNetwork` | `boolean` | `false` | Enable network validation |
| `className` | `string` | - | Additional CSS classes |

# Identity Components (/docs/builderkit/components/identity)

---
title: Identity Components
description: "Components for displaying blockchain addresses and domain names."
---

# Identity Components

Identity components help you display blockchain addresses and domain names in your application.

## Address

The Address component displays Ethereum addresses with optional abbreviation.

```tsx
import { Address } from '@avalabs/builderkit';

// Basic usage
<Address address="0x1234567890123456789012345678901234567890" />

// With abbreviation
<Address 
  address="0x1234567890123456789012345678901234567890"
  abbreviate={true}
/>
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `address` | `string` | - | The Ethereum address to display |
| `abbreviate` | `boolean` | `false` | Whether to show shortened address |

## Domain

The Domain component handles the display of ENS and other domain names.

```tsx
import { Domain } from '@avalabs/builderkit';

// Basic usage
<Domain address="0x1234567890123456789012345678901234567890" />

// With fallback to address
<Domain 
  address="0x1234567890123456789012345678901234567890"
  showAddressIfNotAvailable={true}
/>
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `address` | `string` | - | The address to resolve domain for |
| `showAddressIfNotAvailable` | `boolean` | `false` | Show address if no domain is found |
| `className` | `string` | - | Additional CSS classes |

# Token Components (/docs/builderkit/components/tokens)

---
title: Token Components
description: "Components for displaying and interacting with tokens."
---

# Token Components

Token components provide UI elements for displaying and interacting with tokens.

## TokenIcon

The TokenIcon component displays token logos.

```tsx
import { TokenIcon, TokenIconWithChain } from '@avalabs/builderkit';

// Basic usage
<TokenIcon address="0x1234..." />

// With chain information
<TokenIconWithChain 
  address="0x1234..."
  chain_id={43114}
/>
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `address` | `string` | - | Token contract address |
| `className` | `string` | - | Additional CSS classes |

### TokenIconWithChain Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `address` | `string` | - | Token contract address |
| `chain_id` | `number` | - | Chain ID for the token |
| `className` | `string` | - | Additional CSS classes |

## TokenChip

The TokenChip component displays token information in a compact format.

```tsx
import { TokenChip } from '@avalabs/builderkit';

// Basic usage
<TokenChip 
  chain_id={43114}
  address="0x1234..."
  symbol="AVAX"
/>

// With additional options
<TokenChip 
  chain_id={43114}
  address="0x1234..."
  symbol="AVAX"
  name="Avalanche"
  allowCopyToClipboard={true}
  showChainIcon={true}
  showName={true}
/>
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `chain_id` | `number` | - | Chain ID for the token |
| `address` | `string` | - | Token contract address |
| `symbol` | `string` | - | Token symbol |
| `name` | `string` | - | Token name (optional) |
| `allowCopyToClipboard` | `boolean` | `false` | Enable copy address |
| `showChainIcon` | `boolean` | `false` | Show chain icon |
| `showName` | `boolean` | `false` | Show token name |
| `className` | `string` | - | Additional CSS classes |

## TokenRow

The TokenRow component displays detailed token information.

```tsx
import { TokenRow } from '@avalabs/builderkit';
import { BigNumber } from 'bignumber.js';

// Basic usage
<TokenRow 
  chain_id={43114}
  address="0x1234..."
  name="Avalanche"
  symbol="AVAX"
/>

// With balance and click handler
<TokenRow 
  chain_id={43114}
  address="0x1234..."
  name="Avalanche"
  symbol="AVAX"
  balance={new BigNumber(100)}
  onClick={() => handleTokenSelect()}
/>
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `chain_id` | `number` | - | Chain ID for the token |
| `address` | `string` | - | Token contract address |
| `name` | `string` | - | Token name |
| `symbol` | `string` | - | Token symbol |
| `balance` | `BigNumber` | - | Token balance (optional) |
| `onClick` | `() => void` | - | Click handler (optional) |
| `className` | `string` | - | Additional CSS classes |

## TokenBalance

The TokenBalance component displays token balances with automatic formatting and updates.

```tsx
import { TokenBalance } from '@avalabs/builderkit';

// Basic usage
<TokenBalance 
  address="0x1234567890123456789012345678901234567890"
  token="AVAX"
/>

// With custom formatting
<TokenBalance 
  address="0x1234..."
  token="0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E" // USDC
  decimals={6}
  format="currency"
/>

// Auto-updating balance
<TokenBalance 
  address="0x1234..."
  token="AVAX"
  refreshInterval={5000} // Update every 5 seconds
/>
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `address` | `string` | - | Wallet address to check balance for |
| `token` | `string` | - | Token symbol or contract address |
| `decimals` | `number` | - | Token decimals (auto-detected if not provided) |
| `format` | `'standard' \| 'currency' \| 'compact'` | `'standard'` | Display format |
| `refreshInterval` | `number` | `0` | Auto-refresh interval in milliseconds |
| `className` | `string` | - | Additional CSS classes |

## TokenInput

The TokenInput component provides a form input for token amounts with validation and formatting.

```tsx
import { TokenInput } from '@avalabs/builderkit';

// Basic usage
<TokenInput
  value={amount}
  onChange={setAmount}
  token="AVAX"
/>

// With balance validation
<TokenInput
  value={amount}
  onChange={setAmount}
  token="USDC"
  maxAmount={balance}
  showMax
/>

// With price conversion
<TokenInput
  value={amount}
  onChange={setAmount}
  token="AVAX"
  showUsdPrice
  priceOracle={priceOracle}
/>
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `value` | `string` | - | Current input value |
| `onChange` | `(value: string) => void` | - | Change handler |
| `token` | `string` | - | Token symbol or address |
| `maxAmount` | `string` | - | Maximum allowed amount |
| `showMax` | `boolean` | `false` | Show max button |
| `showUsdPrice` | `boolean` | `false` | Show USD conversion |
| `priceOracle` | `(token: string) => Promise<number>` | - | Price oracle function |
| `className` | `string` | - | Additional CSS classes |

# Transaction Components (/docs/builderkit/components/transactions)

---
title: Transaction Components
description: "Components for handling blockchain transactions and transaction management."
---

# Transaction Components

Transaction components help you manage blockchain transactions in your application.

## TransactionButton

The TransactionButton component handles transaction submission with built-in status tracking.

```tsx
import { TransactionButton } from '@avalabs/builderkit';

// Basic usage
<TransactionButton
  chain_id={43114}
  title="Send AVAX"
  description="Sending AVAX to recipient"
  data={{
    to: "0x1234...",
    value: "1000000000000000000" // 1 AVAX
  }}
/>

// With callbacks
<TransactionButton
  chain_id={43114}
  title="Stake Tokens"
  description="Staking tokens in the protocol"
  data={stakeData}
  onTransactionSent={(hash) => {
    console.log('Transaction sent:', hash);
  }}
  onTransactionConfirmed={(receipt) => {
    console.log('Transaction confirmed:', receipt);
  }}
/>
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `chain_id` | `number` | - | Chain ID for the transaction |
| `title` | `string` | - | Transaction title |
| `description` | `string` | - | Transaction description |
| `data` | `any` | - | Transaction data |
| `onTransactionSent` | `(hash: string) => void` | - | Callback when transaction is sent |
| `onTransactionConfirmed` | `(receipt: any) => void` | - | Callback when transaction is confirmed |
| `className` | `string` | - | Additional CSS classes |

## TransactionManager

The TransactionManager component handles multiple transactions with status tracking.

```tsx
import { TransactionManager } from '@avalabs/builderkit';

// Basic usage
<TransactionManager
  chain_id={43114}
  transactions={[
    {
      title: "Approve Token",
      description: "Approving token for transfer",
      data: approveData
    },
    {
      title: "Transfer Token",
      description: "Transferring tokens to recipient",
      data: transferData
    }
  ]}
/>

// With callbacks
<TransactionManager
  chain_id={43114}
  transactions={transactions}
  onTransactionSent={(hash) => {
    console.log('Transaction sent:', hash);
  }}
  onTransactionConfirmed={(receipt) => {
    console.log('Transaction confirmed:', receipt);
  }}
/>
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `chain_id` | `number` | - | Chain ID for the transactions |
| `transactions` | `TransactionProps[]` | - | Array of transactions to process |
| `onTransactionSent` | `(hash: string) => void` | - | Callback when transaction is sent |
| `onTransactionConfirmed` | `(receipt: any) => void` | - | Callback when transaction is confirmed |
| `className` | `string` | - | Additional CSS classes |

## TransactionStatus

The TransactionStatus component displays the current state of a transaction.

```tsx
import { TransactionStatus } from '@avalabs/builderkit';

// Basic usage
<TransactionStatus
  hash="0x123..."
/>

// With auto-refresh
<TransactionStatus
  hash="0x123..."
  refreshInterval={3000}
  onConfirmed={(receipt) => {
    console.log('Transaction confirmed!');
  }}
/>

// Custom display
<TransactionStatus
  hash="0x123..."
  showProgress
  showExplorerLink
/>
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `hash` | `string` | - | Transaction hash |
| `refreshInterval` | `number` | `5000` | Status check interval |
| `showProgress` | `boolean` | `false` | Show progress indicator |
| `showExplorerLink` | `boolean` | `true` | Show block explorer link |
| `onConfirmed` | `(receipt: TransactionReceipt) => void` | - | Confirmation callback |
| `className` | `string` | - | Additional CSS classes |

## TransactionHistory

The TransactionHistory component displays a list of recent transactions.

```tsx
import { TransactionHistory } from '@avalabs/builderkit';

// Basic usage
<TransactionHistory
  address="0x1234..."
/>

// With filtering
<TransactionHistory
  address="0x1234..."
  filter={{
    type: 'transfer',
    token: 'AVAX'
  }}
/>

// Custom display
<TransactionHistory
  address="0x1234..."
  limit={10}
  showAmount
  showDate
/>
```

### Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `address` | `string` | - | Wallet address |
| `filter` | `TransactionFilter` | - | Transaction filter |
| `limit` | `number` | `50` | Maximum transactions to show |
| `showAmount` | `boolean` | `true` | Show transaction amount |
| `showDate` | `boolean` | `true` | Show transaction date |
| `className` | `string` | - | Additional CSS classes |

# Faucet Flow (/docs/builderkit/flows/faucet)

---
title: Faucet Flow
description: "Pre-built and customizable flow for interacting with token faucets on test networks."
---

# Faucet Flow

The Faucet flow provides a complete interface for requesting test tokens from faucets on Avalanche test networks.

## Backend Requirements

The Faucet flow requires a backend API to handle token distribution and rate limiting. You'll need to implement the following endpoints:

```typescript
// Required API Endpoints
POST /api/faucet/request
  body: {
    address: string;    // Recipient address
    token: string;      // Token symbol
    chainId: number;    // Network ID
  }
  response: {
    requestId: string;  // Unique request identifier
  }

GET /api/faucet/status/:requestId
  response: {
    status: 'pending' | 'completed' | 'failed';
    txHash?: string;    // Transaction hash if completed
    error?: string;     // Error message if failed
  }
```

We provide an example implementation using Next.js API routes, but you can use any backend technology. Note that the example implementation uses in-memory storage and is for demonstration purposes only. For production use, you should:

- Implement persistent storage for request tracking
- Add proper rate limiting per address/IP
- Include security measures (API keys, CORS, etc.)
- Handle concurrent requests appropriately
- Manage token distribution limits

## Basic Usage

```tsx
import { Faucet } from '@avalabs/builderkit';

function App() {
  const tokens = [
    // Array of tokens following the BaseToken interface
    // See /docs/builderkit/tokens for configuration details
    ...
  ];

  return (
    <Faucet 
      chainId={43113}  // Fuji Testnet
      tokens={tokens}
    />
  );
}
```

## Configuration

### Required Props

| Prop | Type | Description |
|------|------|-------------|
| `chainId` | `number` | ID of the test network |
| `tokens` | `Token[]` | List of supported tokens |

### Token Configuration

Each token in the `tokens` array should have the following structure:

```typescript
interface Token {
  address: string;      // Contract address or "native" for native token
  name: string;         // Token name
  symbol: string;       // Token symbol
  decimals: number;     // Token decimals
  chain_id: number;     // Chain ID where token exists
}
```

### Optional Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `className` | `string` | - | Additional CSS classes |

## Features

The Faucet flow includes:
- Token selection interface
- Balance display
- Request handling
- Status tracking
- Timeout management

### Building Custom Flows

The Faucet flow exposes individual components that you can use to build your own custom faucet interface:

```tsx
import { 
  FaucetProvider,
  TokenSelector,
  FaucetButton,
  RequestStatus,
  BalanceDisplay
} from '@avalabs/builderkit/faucet/components';

function CustomFaucet() {
  const tokens = [
    // Array of tokens following the BaseToken interface
    // See /docs/builderkit/tokens for configuration details
    ...
  ];

  return (
    <FaucetProvider
      chainId={43113}
      tokens={tokens}
    >
      <div className="space-y-4">
        <TokenSelector onSelect={handleTokenSelect} />
        <BalanceDisplay token={selectedToken} address={userAddress} />
        <FaucetButton token={selectedToken} />
        <RequestStatus requestId={currentRequestId} />
      </div>
    </FaucetProvider>
  );
}
```

# ICTT Flow (/docs/builderkit/flows/ictt)

---
title: ICTT Flow
description: "Pre-built and customizable flow for transferring tokens between Avalanche chains."
---

# Inter-Chain Token Transfer (ICTT)

The ICTT (Inter-Chain Token Transfer) flow provides a complete and customizable interface for transferring tokens between different Avalanche chains.

## Basic Usage

```tsx
import { ICTT } from '@avalabs/builderkit';

function App() {
  const tokens = [
    // Array of tokens following the ICTTToken interface
    // See /docs/builderkit/tokens for configuration details
    [...]
  ];

  return (
    <ICTT 
      tokens={tokens}
      token_in="0x1234..."  // Address of the input token
      source_chain_id={43113}
      destination_chain_id={173750}
    />
  );
}
```

## Configuration

### Required Props

| Prop | Type | Description |
|------|------|-------------|
| `tokens` | `ICTTToken[]` | List of supported tokens with their mirror configurations |
| `source_chain_id` | `number` | ID of the source chain |
| `destination_chain_id` | `number` | ID of the destination chain |
| `token_in` | `string` | Address of the input token |

### Token Configuration

Each token in the `tokens` array should have the following structure:

```typescript
interface ICTTToken {
  // Basic token information
  address: string;          // Token contract address
  name: string;            // Token name
  symbol: string;          // Token symbol
  decimals: number;        // Token decimals
  chain_id: number;        // Chain ID where token exists
  
  // ICTT specific fields
  supports_ictt: boolean;  // Whether token supports ICTT
  transferer?: string;     // Transferer contract address
  is_transferer?: boolean; // Whether token is a transferer
  
  // Mirror tokens on other chains
  mirrors: {
    address: string;       // Mirror token address
    transferer: string;    // Mirror token transferer
    chain_id: number;      // Mirror token chain ID
    decimals: number;      // Mirror token decimals
    home?: boolean;        // Whether this is the home chain
  }[];
}
```

### Optional Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `className` | `string` | - | Additional CSS classes |

## Features

The ICTT flow includes:

- Chain selection for source and destination
- Token selection with balance display
- Amount input with validation
- Gas fee estimation
- Transaction status tracking
- Bridge transaction confirmation

## Advanced Usage

### Building Custom Flows

The ICTT flow exposes individual components that you can use to build your own custom transfer interface:

```tsx
import { 
  ICTTProvider,
  ChainSelector, 
  TokenSelector,
  AmountInput,
  TransferButton,
  TransferStatus 
} from '@avalabs/builderkit/ictt/components';

function CustomICTT() {
  const tokens = [
    // Array of tokens following the ICTTToken interface
    // See /docs/builderkit/tokens for configuration details
    [...]
  ];

  return (
    <ICTTProvider
      tokens={tokens}
      token_in="0x1234..."
      source_chain_id={43113}
      destination_chain_id={173750}
    >
      <div className="space-y-4">
        <ChainSelector label="From Chain" onSelect={handleSourceChainSelect} />
        <TokenSelector chainId={sourceChainId} onSelect={handleTokenSelect} />
        <AmountInput value={amount} onChange={setAmount} token={selectedToken} />
        <ChainSelector label="To Chain" onSelect={handleDestChainSelect} />
        <TransferButton />
        <TransferStatus />
      </div>
    </ICTTProvider>
  );
}
```

# Chain Hooks (/docs/builderkit/hooks/chains)

---
title: Chain Hooks
description: Hooks for interacting with blockchain networks and chain data.
---

# Chain Hooks

BuilderKit provides hooks for interacting with blockchain networks and managing chain-related data.

## useChains

The `useChains` hook provides functions for accessing and managing chain information.

```tsx
import { useChains } from '@avalabs/builderkit';

const { 
  getChains,
  getChain,
  getProvider,
  getBlock
} = useChains();

// Get all configured chains
const chains = getChains();

// Get specific chain info
const chain = getChain(43114); // Avalanche C-Chain

// Get provider for a chain
const provider = getProvider(43114);

// Get block information
const block = await getBlock(43114, 12345);
```

### Available Functions

- `getChains()`: Get list of all configured chains
- `getChain(chain_id: number)`: Get chain information by ID
- `getProvider(chain_id: number)`: Get ethers provider for a chain
- `getBlock(chain_id: number, block_number: number)`: Get block information

### Integration Example

```tsx
function ChainSelector() {
  const { getChains, getChain } = useChains();
  const [selectedChainId, setSelectedChainId] = useState<number>();
  
  const chains = getChains();
  const selectedChain = selectedChainId ? getChain(selectedChainId) : undefined;
  
  return (
    <div>
      <h2>Current Chain: {selectedChain?.name}</h2>
      <select 
        value={selectedChainId} 
        onChange={(e) => setSelectedChainId(Number(e.target.value))}
      >
        {chains.map(chain => (
          <option key={chain.id} value={chain.id}>
            {chain.name}
          </option>
        ))}
      </select>
    </div>
  );
}
```

# Glacier Hooks (/docs/builderkit/hooks/glacier)

---
title: Glacier Hooks
description: Hooks for interacting with Glacier API and blockchain data.
---

# Glacier Hooks

BuilderKit provides hooks for interacting with the Glacier API, which provides blockchain data and token information.

## useGlacier

The `useGlacier` hook provides functions for accessing chain information and token balances through Glacier.

```tsx
import { useGlacier } from '@avalabs/builderkit';

const { 
  getChainInformation,
  listErc20Balances
} = useGlacier();

// Get chain information
const chainInfo = await getChainInformation(43114);

// Get ERC20 token balances
const balances = await listErc20Balances(
  43114,                 // Chain ID
  "0x1234..."           // Wallet address
);
```

### Available Functions

- `getChainInformation(chain_id: number)`: Get detailed information about a chain
- `listErc20Balances(chain_id: number, address: string)`: Get all ERC20 token balances for an address

### Integration Example

```tsx
function TokenBalances({ address }: { address: string }) {
  const { listErc20Balances } = useGlacier();
  const [balances, setBalances] = useState([]);
  
  useEffect(() => {
    const fetchBalances = async () => {
      const tokenBalances = await listErc20Balances(43114, address);
      setBalances(tokenBalances);
    };
    
    fetchBalances();
  }, [address]);
  
  return (
    <div className="space-y-2">
      {balances.map(balance => (
        <div key={balance.token_address} className="flex justify-between">
          <span>{balance.symbol}</span>
          <span>{balance.formatted_amount}</span>
        </div>
      ))}
    </div>
  );
}
```

# ICTT Hooks (/docs/builderkit/hooks/ictt)

---
title: ICTT Hooks
description: Hooks for Inter-Chain Token Transfer functionality.
---

# ICTT Hooks

BuilderKit provides hooks for handling Inter-Chain Token Transfer (ICTT) operations between Avalanche chains.

## useICTT

The `useICTT` hook provides functions for transferring tokens between different Avalanche chains.

```tsx
import { useICTT } from '@avalabs/builderkit';

const { 
  getInterchainMessenger,
  send,
  sendNative,
  getMessageId,
  getReceiveTransaction,
  getHomeHopMessageId
} = useICTT();

// Get messenger contract
const messenger = await getInterchainMessenger(43114);

// Send ERC20 tokens
const sendData = send(
  transferer,           // Transferer contract
  destinationChainHex,  // Destination chain ID in hex
  destTransferer,       // Destination transferer
  receiver,            // Recipient address
  feeTokenAddr,        // Fee token address
  amount,              // Amount to send
  decimals,            // Token decimals
  isMultiHop           // Whether this is a multi-hop transfer
);

// Send native token
const sendNativeData = sendNative(
  transferer,           // Transferer contract
  destinationChainHex,  // Destination chain ID in hex
  destTransferer,       // Destination transferer
  receiver,            // Recipient address
  feeTokenAddr,        // Fee token address
  amount,              // Amount to send
  decimals,            // Token decimals
  isMultiHop           // Whether this is a multi-hop transfer
);

// Get message ID from log
const messageId = getMessageId(txLog);

// Get receive transaction
const receiveData = await getReceiveTransaction(
  43114,              // Chain ID
  messageId           // Message ID
);

// Get home hop message ID
const hopMessageId = await getHomeHopMessageId(
  43114,              // Chain ID
  txHash              // Transaction hash
);
```

### Available Functions

- `getInterchainMessenger(chain_id: number)`: Get messenger contract address
- `send(transferer: string, destination_L1_hex: string, destination_transferer: string, receiver: string, fee_token_addr: string, amount: BigNumber, decimals: number, is_multi_hop: boolean)`: Generate ERC20 transfer transaction
- `sendNative(transferer: string, destination_L1_hex: string, destination_transferer: string, receiver: string, fee_token_addr: string, amount: BigNumber, decimals: number, is_multi_hop: boolean)`: Generate native token transfer transaction
- `getMessageId(log: any)`: Extract message ID from transaction log
- `getReceiveTransaction(chain_id: number, message_id: string)`: Generate receive transaction
- `getHomeHopMessageId(chain_id: number, hash: string)`: Get message ID for home hop

### Integration Example

```tsx
function ICTTTransfer() {
  const { getInterchainMessenger, send, getMessageId } = useICTT();
  
  const handleTransfer = async () => {
    // Get messenger contract
    const messenger = await getInterchainMessenger(43114);
    
    // Generate transfer transaction
    const data = send(
      transfererContract,
      "0x0000000000000000000000000000000000000000000000000000000000002aef", // 43114 in hex
      destinationTransferer,
      receiverAddress,
      "0x0000000000000000000000000000000000000000", // Zero address for native fee
      new BigNumber("1.0"),
      18,
      false
    );
    
    return (
      <TransactionButton
        chain_id={43114}
        title="Transfer Tokens"
        description="Sending tokens cross-chain"
        data={data}
        onTransactionConfirmed={(receipt) => {
          const messageId = getMessageId(receipt.logs[0]);
          console.log('Transfer message ID:', messageId);
        }}
      />
    );
  };
  
  return (
    <div>
      {handleTransfer()}
    </div>
  );
}
```

# Precompiles Hooks (/docs/builderkit/hooks/precompiles)

---
title: Precompiles Hooks
description: Hooks for interacting with Avalanche precompiled contracts.
---

# Precompile Hooks

BuilderKit provides a set of React hooks for interacting with Avalanche's precompiled contracts. These hooks simplify the interaction with L1-level functionality and administrative operations.

## Available Hooks

<Accordions>
<Accordion title="useAllowList">
The `useAllowList` hook provides functions for managing access control lists for various precompiles.

```tsx
import { useAllowList } from '@avalabs/builderkit';

const { setAdmin, setEnabled, setManager, setNone, readAllowList } = useAllowList(precompileAddress);

// Set admin role
const data = setAdmin("0x1234...");

// Read current role
const role = await readAllowList(43114, "0x1234...");
```

**Available Functions:**
- `setAdmin`: Grant admin role to an address
- `setEnabled`: Grant enabled role to an address
- `setManager`: Grant manager role to an address
- `setNone`: Remove all roles from an address
- `readAllowList`: Read current role of an address
</Accordion>

<Accordion title="useNativeMinter">
The `useNativeMinter` hook enables minting of native tokens on the chain.

```tsx
import { useNativeMinter } from '@avalabs/builderkit';

const { mintNativeCoin } = useNativeMinter();

// Mint tokens
const data = mintNativeCoin(
  "0x1234...", // recipient
  "0x1000000000000000" // amount in hex
);
```

**Available Functions:**
- `mintNativeCoin`: Mint native tokens to a specified address
</Accordion>

<Accordion title="useFeeManager">
The `useFeeManager` hook manages chain fee configurations.

```tsx
import { useFeeManager } from '@avalabs/builderkit';

const { 
  setFeeConfig, 
  getFeeConfig, 
  getFeeConfigLastChangedAt 
} = useFeeManager();

// Configure fees
const data = setFeeConfig(
  "0x5F5E100", // gasLimit
  "2",         // targetBlockRate
  "0x5F5E100", // minBaseFee
  "0x5F5E100", // targetGas
  "48",        // baseFeeChangeDenominator
  "0x0",       // minBlockGasCost
  "0x0",       // maxBlockGasCost
  "0x0"        // blockGasCostStep
);

// Get current config
const config = await getFeeConfig(43114);
```

**Available Functions:**
- `setFeeConfig`: Update chain fee configuration
- `getFeeConfig`: Get current fee configuration
- `getFeeConfigLastChangedAt`: Get timestamp of last fee config change
</Accordion>

<Accordion title="useRewardManager">
The `useRewardManager` hook controls reward distribution settings.

```tsx
import { useRewardManager } from '@avalabs/builderkit';

const { 
  setRewardAddress, 
  allowFeeRecipients, 
  disableRewards,
  currentRewardAddress,
  areFeeRecipientsAllowed 
} = useRewardManager();

// Set reward address
const data = await setRewardAddress("0x1234...");

// Check current settings
const address = await currentRewardAddress(43114);
const allowed = await areFeeRecipientsAllowed(43114);
```

**Available Functions:**
- `setRewardAddress`: Set the reward recipient address
- `allowFeeRecipients`: Enable fee recipients
- `disableRewards`: Disable reward distribution
- `currentRewardAddress`: Get current reward address
- `areFeeRecipientsAllowed`: Check if fee recipients are allowed
</Accordion>

<Accordion title="useWarpMessenger">
The `useWarpMessenger` hook enables cross-chain messaging.

```tsx
import { useWarpMessenger } from '@avalabs/builderkit';

const { 
  sendWarpMessage, 
  getVerifiedWarpMessage,
  getVerifiedWarpBlockHash,
  getBlockchainId 
} = useWarpMessenger();

// Send message
const data = await sendWarpMessage("0x1234...");

// Verify message
const message = await getVerifiedWarpMessage(43114, 0);
const blockHash = await getVerifiedWarpBlockHash(43114, 0);
```

**Available Functions:**
- `sendWarpMessage`: Send a message to another L1
- `getVerifiedWarpMessage`: Get a verified message
- `getVerifiedWarpBlockHash`: Get a verified block hash
- `getBlockchainId`: Get the current blockchain ID
</Accordion>

<Accordion title="useTransactionAllowList">
The `useTransactionAllowList` hook manages transaction permissions.

```tsx
import { useTransactionAllowList } from '@avalabs/builderkit';

const { setEnabled, readAllowList } = useTransactionAllowList();

// Enable address for transactions
const data = setEnabled("0x1234...");

// Check address status
const status = await readAllowList(43114, "0x1234...");
```

**Available Functions:**
- `setEnabled`: Enable an address for transactions
- `readAllowList`: Check if an address is enabled
</Accordion>

<Accordion title="useDeployerAllowList">
The `useDeployerAllowList` hook manages contract deployment permissions.

```tsx
import { useDeployerAllowList } from '@avalabs/builderkit';

const { setEnabled, readAllowList } = useDeployerAllowList();

// Enable address for deployments
const data = setEnabled("0x1234...");

// Check address status
const status = await readAllowList(43114, "0x1234...");
```

**Available Functions:**
- `setEnabled`: Enable an address for contract deployments
- `readAllowList`: Check if an address is enabled for deployments
</Accordion>
</Accordions>

## Integration with Transaction Components

All precompile hooks return transaction data that can be used with the TransactionButton or TransactionManager components.

```tsx
function App() {
  const { mintNativeCoin } = useNativeMinter();
  
  const handleMint = () => {
    const data = mintNativeCoin("0x1234...", "0x1000000000000000");
    
    return (
      <TransactionButton
        chain_id={43114}
        title="Mint Tokens"
        description="Minting native tokens"
        data={data}
      />
    );
  };
}
```

## Access Control with useAllowList

Most precompiles in Avalanche use a role-based access control system managed through the `useAllowList` hook. This means that before using precompile functions, you need to ensure the calling address has the appropriate role.

The role system has three levels:
- **None (0)**: No permissions
- **Enabled (1)**: Basic permissions for operations
- **Admin (2)**: Full control over the precompile

Here's how roles work across precompiles:

| Precompile | Required Role | Operations |
|------------|---------------|------------|
| NativeMinter | Admin | - Set roles for other addresses<br/>- Mint native tokens |
| | Enabled | - Mint native tokens |
| FeeManager | Admin | - Set roles for other addresses<br/>- Configure gas fees<br/>- Set minimum block cost<br/>- Set block gas cost step |
| RewardManager | Admin | - Set roles for other addresses<br/>- Configure reward address<br/>- Enable/disable fee recipients<br/>- Set reward address |
| WarpMessenger | Admin | - Set roles for other addresses<br/>- Send cross-chain messages<br/>- Get verified messages |
| | Enabled | - Send cross-chain messages<br/>- Get verified messages |
| TransactionAllowList | Admin | - Set roles for other addresses<br/>- Enable/disable addresses for transactions |
| | Enabled | - Submit transactions (if enabled) |
| DeployerAllowList | Admin | - Set roles for other addresses<br/>- Enable/disable addresses for deployments |
| | Enabled | - Deploy contracts (if enabled) |

Example of checking and setting roles:

```tsx
function AdminPanel() {
  const { readAllowList, setEnabled, setAdmin, setNone } = useAllowList(precompileAddress);
  
  // Check current role
  const checkAccess = async (address) => {
    const role = await readAllowList(43114, address);
    return role; // Returns: 0 (None), 1 (Enabled), 2 (Admin)
  };
  
  // Grant Enabled role
  const grantEnabled = async (address) => {
    const data = setEnabled(address);
    return (
      <TransactionButton
        chain_id={43114}
        title="Grant Access"
        description="Granting enabled role"
        data={data}
      />
    );
  };
  
  // Grant Admin role
  const grantAdmin = async (address) => {
    const data = setAdmin(address);
    return (
      <TransactionButton
        chain_id={43114}
        title="Grant Admin"
        description="Granting admin role"
        data={data}
      />
    );
  };
  
  // Remove all roles
  const removeAccess = async (address) => {
    const data = setNone(address);
    return (
      <TransactionButton
        chain_id={43114}
        title="Remove Access"
        description="Removing all roles"
        data={data}
      />
    );
  };
}
```

## Precompile Addresses

| Precompile | Address | Description |
|------------|---------|-------------|
| NativeMinter | `0x0200000000000000000000000000000000000001` | Mint native tokens |
| TransactionAllowList | `0x0200000000000000000000000000000000000002` | Control transaction permissions |
| FeeManager | `0x0200000000000000000000000000000000000003` | Configure chain fees |
| RewardManager | `0x0200000000000000000000000000000000000004` | Manage reward distribution |
| WarpMessenger | `0x0200000000000000000000000000000000000005` | Cross-chain messaging |
| DeployerAllowList | `0x0200000000000000000000000000000000000000` | Control deployment permissions |


# Token Hooks (/docs/builderkit/hooks/tokens)

---
title: Token Hooks
description: "Hooks for interacting with ERC20 tokens."
---

# Token Hooks

BuilderKit provides hooks for interacting with ERC20 tokens, including balance checking, approvals, and token information.

## useTokens

The `useTokens` hook provides functions for accessing token information and performing token-related operations.

```tsx
import { useTokens } from '@avalabs/builderkit';

const { 
  getCustomToken,
  getBalance,
  getAllowance,
  approve
} = useTokens();

// Get token information
const [name, symbol, decimals] = await getCustomToken(
  43114,                 // Chain ID
  "0x1234..."           // Token address
);

// Get token balance
const balance = await getBalance(
  43114,                 // Chain ID
  "0x1234...",          // Token address
  "0x5678..."           // Wallet address
);

// Check allowance
const allowance = await getAllowance(
  43114,                 // Chain ID
  "0x1234...",          // Token address
  "0x5678...",          // Owner address
  "0x9012..."           // Spender address
);

// Generate approve transaction
const approveData = approve(
  "0x1234...",          // Token address
  "0x5678...",          // Spender address
  new BigNumber("1.0"),  // Amount
  18                     // Decimals
);
```

### Available Functions

- `getCustomToken(chain_id: number, address: string)`: Get token name, symbol, and decimals
- `getBalance(chain_id: number, address: string, wallet: string)`: Get token balance for an address
- `getAllowance(chain_id: number, address: string, owner: string, spender: string)`: Get token allowance
- `approve(address: string, spender: string, amount: BigNumber, decimals: number)`: Generate approve transaction data

### Integration Example

```tsx
function TokenApproval({ token, spender }: { token: string, spender: string }) {
  const { getAllowance, approve } = useTokens();
  const [allowance, setAllowance] = useState("0");
  
  useEffect(() => {
    const checkAllowance = async () => {
      const amount = await getAllowance(43114, token, account, spender);
      setAllowance(amount.toString());
    };
    
    checkAllowance();
  }, [token, spender]);
  
  const handleApprove = () => {
    const data = approve(token, spender, new BigNumber("1000"), 18);
    
    return (
      <TransactionButton
        chain_id={43114}
        title="Approve Token"
        description="Approving token for spending"
        data={data}
      />
    );
  };
  
  return (
    <div>
      <div>Current Allowance: {allowance}</div>
      {handleApprove()}
    </div>
  );
}
```

# Uniswap Hooks (/docs/builderkit/hooks/uniswap)

---
title: Uniswap Hooks
description: "Hooks for interacting with Uniswap V2 protocol on Avalanche."
---

# Uniswap Hooks

BuilderKit provides hooks for interacting with Uniswap V2-compatible DEXs on Avalanche, such as Trader Joe.

## useUniswapV2

The `useUniswapV2` hook provides functions for swapping tokens and managing liquidity using Uniswap V2 protocol.

```tsx
import { useUniswapV2 } from '@avalabs/builderkit';

const { 
  getPair,
  getReserves,
  getAmountOut,
  getQuote,
  getMinAmountOut,
  getSwapTransaction
} = useUniswapV2();

// Get pair address
const pairAddress = await getPair(
  43114,                 // Chain ID
  tokenA,               // Token A info
  tokenB                // Token B info
);

// Get pair reserves
const reserves = await getReserves(
  43114,                // Chain ID
  pairAddress           // Pair address
);

// Calculate output amount
const amountOut = getAmountOut(
  reserves,             // [reserve0, reserve1]
  new BigNumber("1.0"), // Amount in
  tokenA,              // Token in info
  tokenB               // Token out info
);

// Get swap transaction data
const swapData = await getSwapTransaction(
  43114,               // Chain ID
  tokenA,             // Token in info
  tokenB,             // Token out info
  new BigNumber("1.0"), // Amount in
  amountOut,          // Minimum amount out
  "0x1234..."         // Recipient
);
```

### Available Functions

- `getPair(chain_id: number, token_in: any, token_out: any)`: Get pair contract address
- `getReserves(chain_id: number, pair: string)`: Get pair reserves
- `getAmountOut(reserves: [BigNumber, BigNumber], amount_in: BigNumber, token_in: any, token_out: any, fee?: number)`: Calculate output amount
- `getQuote(chain_id: number, token_in: any, token_out: any, amount_in: BigNumber)`: Get quote for swap
- `getMinAmountOut(amount: BigNumber, slippage?: number)`: Calculate minimum output with slippage
- `getSwapTransaction(chain_id: number, token_in: any, token_out: any, amount_in: BigNumber, amount_out: BigNumber, receiver: string)`: Generate swap transaction

### Integration Example

```tsx
function SwapInterface() {
  const { getQuote, getMinAmountOut, getSwapTransaction } = useUniswapV2();
  const [amountIn, setAmountIn] = useState("");
  const [amountOut, setAmountOut] = useState("");
  
  // Calculate output amount when input changes
  useEffect(() => {
    const calculateOutput = async () => {
      if (!amountIn) return;
      
      const output = await getQuote(
        43114,
        tokenA,
        tokenB,
        new BigNumber(amountIn)
      );
      setAmountOut(output.toString());
    };
    
    calculateOutput();
  }, [amountIn]);
  
  // Execute swap
  const handleSwap = async () => {
    const minOut = getMinAmountOut(new BigNumber(amountOut), 0.5); // 0.5% slippage
    
    const data = await getSwapTransaction(
      43114,
      tokenA,
      tokenB,
      new BigNumber(amountIn),
      minOut,
      account
    );
    
    return (
      <TransactionButton
        chain_id={43114}
        title="Swap Tokens"
        description="Swapping tokens on Trader Joe"
        data={data}
      />
    );
  };
  
  return (
    <div>
      <input
        type="text"
        value={amountIn}
        onChange={(e) => setAmountIn(e.target.value)}
        placeholder="Amount in"
      />
      <div>Output: {amountOut}</div>
      {handleSwap()}
    </div>
  );
}
```

# Deploy a Smart Contract (/docs/avalanche-l1s/add-utility/deploy-smart-contract)

---
title: Deploy a Smart Contract
description: Deploy a smart contract on your Avalanche L1.
---

This tutorial assumes that:

- [an Avalanche L1 and EVM blockchain](/docs/avalanche-l1s/deploy-a-avalanche-l1/fuji-testnet) has been created
- Your Node is currently validating your target Avalanche L1
- Your wallet has a balance of the Avalanche L1 Native Token(Specified under _alloc_ in your [Genesis File](/docs/avalanche-l1s/upgrade/customize-avalanche-l1#genesis)).

Step 1: Setting up Core[​](#step-1-setting-up-core "Direct link to heading")
----------------------------------------------------------------------------

### **EVM Avalanche L1 Settings**: [(EVM Core Tutorial)](/docs/avalanche-l1s/deploy-a-avalanche-l1/fuji-testnet#connect-with-core)[​](#evm-avalanche-l1-settings-evm-core-tutorial "Direct link to heading")

- **`Network Name`**: Custom Subnet-EVM
- **`New RPC URL`**: http://NodeIPAddress:9650/ext/bc/BlockchainID/rpc (Note: the port number should match your local setting which can be different from 9650.)
- **`ChainID`**: Subnet-EVM ChainID
- **`Symbol`**: Subnet-EVM Token Symbol
- **`Explorer`**: N/A

You should see a balance of your Avalanche L1's Native Token in Core.

![balance](/images/smart-contract1.png)

Step 2: Connect Core and Deploy a Smart Contract[​](#step-2-connect-core-and-deploy-a-smart-contract "Direct link to heading")
------------------------------------------------------------------------------------------------------------------------------

### Using Remix[​](#using-remix "Direct link to heading")

Open [Remix](https://remix.ethereum.org/) -> Select Solidity.

![remix Avalanche L1 evm sc home](/images/smart-contract2.png)

Create the smart contracts that we want to compile and deploy using Remix file explorer

### Using GitHub[​](#using-github "Direct link to heading")

In Remix Home _Click_ the GitHub button.

![remix Avalanche L1 evm sc load panel](/images/smart-contract3.png)

Paste the [link to the Smart Contract](https://github.com/ava-labs/avalanche-smart-contract-quickstart/blob/main/contracts/NFT.sol) into the popup and _Click_ import.

![remix Avalanche L1 evm sc import](/images/smart-contract4.png)

For this example, we will deploy an ERC721 contract from the [Avalanche Smart Contract Quickstart Repository](https://github.com/ava-labs/avalanche-smart-contract-quickstart).

![remix Avalanche L1 evm sc file explorer](/images/smart-contract5.png)

Navigate to Deploy Tab -> Open the "ENVIRONMENT" drop-down and select Injected Web3 (make sure Core is loaded).

![remix Avalanche L1 evm sc web3](/images/smart-contract6.png)

Once we injected the web3-> Go back to the compiler, and compile the selected contract -> Navigate to Deploy Tab.

![remix Avalanche L1 evm sc compile](/images/smart-contract7.png)

Now, the smart contract is compiled, Core is injected, and we are ready to deploy our ERC721. Click "Deploy."

![remix Avalanche L1 evm sc deploy](/images/smart-contract8.png)

Confirm the transaction on the Core pop up.

![balance](/images/smart-contract9.png)

Our contract is successfully deployed!

![remix Avalanche L1 evm sc deployed](/images/smart-contract10.png)

Now, we can expand it by selecting it from the "Deployed Contracts" tab and test it out.

![remix Avalanche L1 evm sc end](/images/smart-contract11.png)

The contract ABI and Bytecode are available on the compiler tab.

![remix Avalanche L1 evm sc ABI](/images/smart-contract12.png)

If you had any difficulties following this tutorial or simply want to discuss Avalanche with us, you can join our community at [Discord](https://chat.avalabs.org/)!

You can use Subnet-EVM just like you use C-Chain and EVM tools. Only differences are `chainID` and RPC URL. For example you can deploy your contracts with [hardhat quick start guide](/docs/dapps/toolchains/hardhat) by changing `url` and `chainId` in the `hardhat.config.ts`.


# Add a Testnet Faucet (/docs/avalanche-l1s/add-utility/testnet-faucet)

---
title: Add a Testnet Faucet
description: This guide will help you add a testnet faucet to your Avalanche L1.
---
There are thousands of networks and chains in the blockchain space, each with its capabilities and use-cases. Each network requires native coins to do any transaction on them, which can have a monetary value as well. These coins can be collected through centralized exchanges, token sales, etc in exchange for some monetary assets like USD.

But we cannot risk our funds on the network or on any applications hosted on that network, without testing them first. So, these networks often have test networks or testnets, where the native coins do not have any monetary value, and thus can be obtained freely through faucets.

These testnets are often the testbeds for any new native feature of the network itself, or any dapp or [Avalanche L1](/docs/quick-start/avalanche-l1s) that is going live on the main network (Mainnet). For example, [Fuji](/docs/quick-start/networks/fuji-testnet) network is the Testnet for Avalanche's Mainnet.

Besides Fuji Testnet, the [Avalanche Faucet](https://core.app/tools/testnet-faucet/?avalanche-l1=c&token=c) can be used to get free test tokens on testnet Avalanche L1s like:

- [WAGMI Testnet](https://core.app/tools/testnet-faucet/?avalanche-l1=wagmi)
- [DeFI Kingdoms Testnet](https://core.app/tools/testnet-faucet/?avalanche-l1=dfk)
- [Beam Testnet](https://core.app/tools/testnet-faucet/?avalanche-l1=beam&token=beam) and many more.

You can use this [repository](https://github.com/ava-labs/avalanche-faucet) to deploy your faucet or just make a PR with the [configurations](https://github.com/ava-labs/avalanche-faucet/blob/main/config.json) of the Avalanche L1. This faucet comes with many features like multiple chain support, custom rate-limiting per Avalanche L1, CAPTCHA verification, and concurrent transaction handling.

Summary[​](#summary "Direct link to heading")
---------------------------------------------

A [Faucet](https://core.app/tools/testnet-faucet/) powered by Avalanche for Fuji Network and other Avalanche L1s. You can -

- Request test coins for the supported Avalanche L1s
- Integrate your EVM Avalanche L1 with the faucet by making a PR with the [chain configurations](https://github.com/ava-labs/avalanche-faucet/blob/main/config.json)
- Fork the [repository](https://github.com/ava-labs/avalanche-faucet) to deploy your faucet for any EVM chain

Adding a New Avalanche L1[​](#adding-a-new-avalanche-l1 "Direct link to heading")
---------------------------------------------------------------------

You can also integrate a new Avalanche L1 on the live [faucet](https://core.app/tools/testnet-faucet/) with just a few lines of configuration parameters. All you have to do is make a PR on the [Avalanche Faucet](https://github.com/ava-labs/avalanche-faucet) git repository with the Avalanche L1's information. The following parameters are required.

```json
{
    "ID": string,
    "NAME": string,
    "TOKEN": string,
    "RPC": string,
    "CHAINID": number,
    "EXPLORER": string,
    "IMAGE": string,
    "MAX_PRIORITY_FEE": string,
    "MAX_FEE": string,
    "DRIP_AMOUNT": number,
    "RATELIMIT": {
        "MAX_LIMIT": number,
        "WINDOW_SIZE": number
    }
}
```

- `ID` - Each Avalanche L1 chain should have a unique and relatable ID.
- `NAME` - Name of the Avalanche L1 chain that will appear on the site.
- `RPC` - A valid RPC URL for accessing the chain.
- `CHAINID` - ChainID of the chain
- `EXPLORER` - Base URL of standard explorer's site.
- `IMAGE` - URL of the icon of the chain that will be shown in the dropdown.
- `MAX_PRIORITY_FEE` - Maximum tip per faucet drop in **wei** or **10\-18** unit (for EIP1559 supported chains)
- `MAX_FEE` - Maximum fee that can be paid for a faucet drop in **wei** or **10\-18** unit
- `DRIP_AMOUNT` - Amount of coins to send per request in **gwei** or **10\-9** unit
- `RECALIBRATE` _(optional)_ - Number of seconds after which the nonce and balance will recalibrate
- `RATELIMIT` - Number of times (MAX\_LIMIT) to allow per user within the WINDOW\_SIZE (in minutes)

Add the configuration in the array of `evmchains` inside the [config.json](https://github.com/ava-labs/avalanche-faucet/blob/main/config.json) file and make a PR.

Building and Deploying a Faucet[​](#building-and-deploying-a-faucet "Direct link to heading")
---------------------------------------------------------------------------------------------

You can also deploy and build your faucet by using the [Avalanche Faucet](https://github.com/ava-labs/avalanche-faucet) repository.

### Requirements[​](#requirements "Direct link to heading")

- [Node](https://nodejs.org/en) >= 17.0 and [npm](https://www.npmjs.com/) >= 8.0
- [Google's reCAPTCHA](https://www.google.com/recaptcha/intro/v3.html) v3 keys
- [Docker](https://www.docker.com/get-started/)

### Installation[​](#installation "Direct link to heading")

Clone this repository at your preferred location.

```bash
git clone https://github.com/ava-labs/avalanche-faucet
```

<Callout title="Note">
The repository cloning method used is HTTPS, but SSH can be used too:

`git clone git@github.com:ava-labs/avalanche-faucet.git`

You can find more about SSH and how to use it [here](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/about-ssh).
</Callout>

### Client-Side Configurations[​](#client-side-configurations "Direct link to heading")

We need to configure our application with the server API endpoints and CAPTCHA site keys. All the client-side configurations are there in the `client/src/config.json` file. Since there are no secrets on the client-side, we do not need any environment variables. Update the config files according to your need.

```json
{
  "banner": "/banner.png",
  "apiBaseEndpointProduction": "/api/",
  "apiBaseEndpointDevelopment": "http://localhost:8000/api/",
  "apiTimeout": 10000,
  "CAPTCHA": {
    "siteKey": "6LcNScYfAAAAAJH8fauA-okTZrmAxYqfF9gOmujf",
    "action": "faucetdrip"
  }
}
```

Put the Google's reCAPTCHA site-key without which the faucet client can't send the necessary CAPTCHA response to the server. This key is not a secret and could be public.

In the above file, there are 2 base endpoints for the faucet server `apiBaseEndpointProduction` and `apiBaseEndpointDevelopment`.

In production mode, the client-side will be served as static content over the server's endpoint, and hence we do not have to provide the server's IP address or domain.

The URL path should be valid, where the server's APIs are hosted. If the endpoints for API have a leading `/v1/api` and the server is running on localhost at port 3000, then you should use `http://localhost:3000/v1/api` or `/v1/api/` depending on whether it is production or development.

### Server-Side Configurations[​](#server-side-configurations "Direct link to heading")

On the server-side, we need to configure 2 files - `.env` for secret keys and `config.json` for chain and API rate limiting configurations.

#### Setup Environment Variables[​](#setup-environment-variables "Direct link to heading")

Setup the environment variable with your private key and reCAPTCHA secret. Make a `.env` file in your preferred location with the following credentials, as this file will not be committed to the repository. The faucet server can handle multiple EVM chains, and therefore requires private keys for addresses with funds on each of the chains.

If you have funds on the same address on every chain, then you can specify them with the single variable`PK`. But if you have funds on different addresses on different chains, then you can provide each of the private keys against the ID of the chain, as shown below.

```bash
C="C chain private key"
WAGMI="Wagmi chain private key"
PK="Sender Private Key with Funds in it"
CAPTCHA_SECRET="Google reCAPTCHA Secret"
```

`PK` will act as a fallback private key, in case, the key for any chain is not provided.

#### Setup EVM Chain Configurations[​](#setup-evm-chain-configurations "Direct link to heading")

You can create a faucet server for any EVM chain by making changes in the `config.json` file. Add your chain configuration as shown below in the `evmchains` object. Configuration for Fuji's C-Chain and WAGMI chain is shown below for example.

```json
"evmchains": [
    {
        "ID": "C",
        "NAME": "Fuji (C-Chain)",
        "TOKEN": "AVAX",
        "RPC": "https://api.avax-test.network/ext/C/rpc",
        "CHAINID": 43113,
        "EXPLORER": "https://testnet.snowtrace.io",
        "IMAGE": "/avaxred.png",
        "MAX_PRIORITY_FEE": "2000000000",
        "MAX_FEE": "100000000000",
        "DRIP_AMOUNT": 2000000000,
        "RECALIBRATE": 30,
        "RATELIMIT": {
            "MAX_LIMIT": 1,
            "WINDOW_SIZE": 1440
        }
    },
    {
        "ID": "WAGMI",
        "NAME": "WAGMI Testnet",
        "TOKEN": "WGM",
        "RPC": "https://subnets.avax.network/wagmi/wagmi-chain-testnet/rpc",
        "CHAINID": 11111,
        "EXPLORER": "https://subnets.avax.network/wagmi/wagmi-chain-testnet/explorer",
        "IMAGE": "/wagmi.png",
        "MAX_PRIORITY_FEE": "2000000000",
        "MAX_FEE": "100000000000",
        "DRIP_AMOUNT": 2000000000,
        "RATELIMIT": {
            "MAX_LIMIT": 1,
            "WINDOW_SIZE": 1440
        }
    }
]
```

In the above configuration drip amount is in `nAVAX` or `gwei`, whereas fees are in `wei`. For example, with the above configurations, the faucet will send `1 AVAX` with maximum fees per gas being `100 nAVAX` and priority fee as `2 nAVAX`.

The rate limiter for C-Chain will only accept 1 request in 60 minutes for a particular API and 2 requests in 60 minutes for the WAGMI chain. Though it will skip any failed requests so that users can request tokens again, even if there is some internal error in the application. On the other hand, the global rate limiter will allow 15 requests per minute on every API. This time failed requests will also get counted so that no one can abuse the APIs.

### API Endpoints[​](#api-endpoints "Direct link to heading")

This server will expose the following APIs

#### Health API[​](#health-api "Direct link to heading")

The `/health` API will always return a response with a `200` status code. This endpoint can be used to know the health of the server.

```bash
curl http://localhost:8000/health
```

Response

#### Get Faucet Address[​](#get-faucet-address "Direct link to heading")

This API will be used for fetching the faucet address.

```bash
curl http://localhost:8000/api/faucetAddress?chain=C
```

It will give the following response:

```bash
0x3EA53fA26b41885cB9149B62f0b7c0BAf76C78D4
```

#### Get Faucet Balance[​](#get-faucet-balance "Direct link to heading")

This API will be used for fetching the faucet address.

```bash
curl http://localhost:8000/api/getBalance?chain=C
```

#### Send Token[​](#send-token "Direct link to heading")

This API endpoint will handle token requests from users. It will return the transaction hash as a receipt of the faucet drip.

```bash
curl -d '{
    "address": "0x3EA53fA26b41885cB9149B62f0b7c0BAf76C78D4"
    "chain": "C"
}' -H 'Content-Type: application/json' http://localhost:8000/api/sendToken
```

Send token API requires a CAPTCHA response token that is generated using the CAPTCHA site key on the client-side.

Since we can't generate and pass this token while making a curl request, we have to disable the CAPTCHA verification for testing purposes. You can find the steps to disable it in the next sections. The response is shown below

```json
{
    "message": "Transaction successful on Avalanche C Chain!",
    "txHash": "0x3d1f1c3facf59c5cd7d6937b3b727d047a1e664f52834daf20b0555e89fc8317"
}
```

### Rate Limiters[​](#rate-limiters-important "Direct link to heading")

The rate limiters are applied on the global (all endpoints) as well as on the `/api/sendToken` API. These can be configured from the `config.json` file. Rate limiting parameters for chains are passed in the chain configuration as shown above.

```json
"GLOBAL_RL": {
    "ID": "GLOBAL",
    "RATELIMIT": {
        "REVERSE_PROXIES": 4,
        "MAX_LIMIT": 40,
        "WINDOW_SIZE": 1,
        "PATH": "/",
        "SKIP_FAILED_REQUESTS": false
    }
}
```

There could be multiple proxies between the server and the client. The server will see the IP address of the adjacent proxy connected with the server, and this may not be the client's actual IP.

The IPs of all the proxies that the request has hopped through are stuffed inside the header **x-forwarded-for** array. But the proxies in between can easily manipulate these headers to bypass rate limiters. So, we cannot trust all the proxies and hence all the IPs inside the header.

The proxies that are set up by the owner of the server (reverse-proxies) are the trusted proxies on which we can rely and know that they have stuffed the actual IP of the callers in between. Any proxy that is not set up by the server, should be considered an untrusted proxy. So, we can jump to the IP address added by the last proxy that we trust. The number of jumps that we want can be configured in the `config.json` file inside the `GLOBAL_RL` object.

![faucet 5](/images/faucet1.png)

#### Clients Behind Same Proxy[​](#clients-behind-same-proxy "Direct link to heading")

Consider the below diagram. The server is set up with 2 reverse proxies. If the client is behind proxies, then we cannot get the client's actual IP, and instead will consider the proxy's IP as the client's IP. And if some other client is behind the same proxy, then those clients will be considered as a single entity and might get rate-limited faster.

![faucet 6](/images/faucet2.png)

Therefore it is advised to the users, to avoid using any proxy for accessing applications that have critical rate limits, like this faucet.

#### Wrong Number of Reverse Proxies[​](#wrong-number-of-reverse-proxies "Direct link to heading")

So, if you want to deploy this faucet, and have some reverse proxies in between, then you should configure this inside the `GLOBAL_RL` key of the `config.json` file. If this is not configured properly, then the users might get rate-limited very frequently, since the server-side proxy's IP addresses are being viewed as the client's IP. You can verify this in the code [here](https://github.com/ava-labs/avalanche-faucet/blob/23eb300635b64130bc9ce10d9e894f0a0b3d81ea/middlewares/rateLimiter.ts#L25).

```json
"GLOBAL_RL": {
    "ID": "GLOBAL",
    "RATELIMIT": {
        "REVERSE_PROXIES": 4,
        ...
    }
}
```

![faucet 7](/images/faucet3.png)

It is also quite common to have Cloudflare as the last reverse proxy or the exposed server. Cloudflare provides a header **cf-connecting-ip** which is the IP of the client that requested the faucet and hence Cloudflare. We are using this as default.

### CAPTCHA Verification[​](#captcha-verification "Direct link to heading")

CAPTCHA is required to prove the user is a human and not a bot. For this purpose, we will use [Google's reCAPTCHA](https://www.google.com/recaptcha/intro/v3.html). The server-side will require `CAPTCHA_SECRET` that should not be exposed. You can set the threshold score to pass the CAPTCHA test by the users [here](https://github.com/ava-labs/avalanche-faucet/blob/23eb300635b64130bc9ce10d9e894f0a0b3d81ea/middlewares/verifyCaptcha.ts#L20).

You can disable these CAPTCHA verifications and rate limiters for testing the purpose, by tweaking in the `server.ts` file.

### Disabling Rate Limiters[​](#disabling-rate-limiters "Direct link to heading")

Comment or remove these two lines from the `server.ts` file

```ts title="server.ts"
new RateLimiter(app, [GLOBAL_RL]);
new RateLimiter(app, evmchains);
```

### Disabling CAPTCHA Verification[​](#disabling-captcha-verification "Direct link to heading")

Remove the `captcha.middleware` from `sendToken` API.

### Starting the Faucet[​](#starting-the-faucet "Direct link to heading")

Follow the below commands to start your local faucet.

#### Installing Dependencies[​](#installing-dependencies "Direct link to heading")

This will concurrently install dependencies for both client and server.

If ports have a default configuration, then the client will start at port 3000 and the server will start at port 8000 while in development mode.

#### Starting in Development Mode[​](#starting-in-development-mode "Direct link to heading")

This will concurrently start the server and client in development mode.

#### Building for Production[​](#building-for-production "Direct link to heading")

The following command will build server and client at `build/` and `build/client` directories.

#### Starting in Production Mode[​](#starting-in-production-mode "Direct link to heading")

This command should only be run after successfully building the client and server-side code.

### Setting up with Docker[​](#setting-up-with-docker "Direct link to heading")

Follow the steps to run this application in a Docker container.

#### Build Docker Image[​](#build-docker-image "Direct link to heading")

Docker images can be served as the built versions of our application, that can be used to deploy on Docker container.

```bash
docker build . -t faucet-image
```

#### Starting Application inside Docker Container[​](#starting-application-inside-docker-container "Direct link to heading")

Now we can create any number of containers using the above `faucet` image. We also have to supply the `.env` file or the environment variables with the secret keys to create the container. Once the container is created, these variables and configurations will be persisted and can be easily started or stopped with a single command.

```bash
docker run -p 3000:8000 --name faucet-container --env-file ../.env faucet-image
```

The server will run on port 8000, and our Docker will also expose this port for the outer world to interact. We have exposed this port in the `Dockerfile`. But we cannot directly interact with the container port, so we had to bind this container port to our host port. For the host port, we have chosen 3000. This flag `-p 3000:8000` achieves the same.

This will start our faucet application in a Docker container at port 3000 (port 8000 on the container). You can interact with the application by visiting \[http://localhost:3000\] in your browser.

#### Stopping the Container[​](#stopping-the-container "Direct link to heading")

You can easily stop the container using the following command

```bash
docker stop faucet-container
```

#### Restarting the Container[​](#restarting-the-container "Direct link to heading")

To restart the container, use the following command

```bash
docker start faucet-container
```

Using the Faucet[​](#using-the-faucet "Direct link to heading")
---------------------------------------------------------------

Using the faucet is quite straightforward, but for the sake of completeness, let's go through the steps, to collect your first test coins.

### Visit Avalanche Faucet Site[​](#visit-avalanche-faucet-site "Direct link to heading")

Go to [https://core.app/tools/testnet-faucet/](https://core.app/tools/testnet-faucet/). You will see various network parameters like network name, faucet balance, drop amount, drop limit, faucet address, etc.

![faucet 1](/images/faucet4.png)

### Select Network[​](#select-network "Direct link to heading")

You can use the dropdown to select the network of your choice and get some free coins (each network may have a different drop amount).

![faucet 2](/images/faucet5.png)

### Put Address and Request Coins[​](#put-address-and-request-coins "Direct link to heading")

If you already have an AVAX balance greater than zero on Mainnet, paste your C-Chain address there, and request test tokens. Otherwise, please request a faucet coupon on [Guild](https://guild.xyz/avalanche). Admins and mods on the official [Discord](https://discord.com/invite/RwXY7P6) can provide testnet AVAX if developers are unable to obtain it from the other two options.

Within a second, you will get a **transaction hash** for the processed transaction. The hash would be a hyperlink to Avalanche L1's explorer. You can see the transaction status, by clicking on that hyperlink.

![faucet 3](/images/faucet6.png)

### More Interactions[​](#more-interactions "Direct link to heading")

This is not just it. Using the buttons shown below, you can go to the Avalanche L1 explorer or add the Avalanche L1 to your browser wallet extensions like Core or MetaMask with a single click.

![faucet 4](/images/faucet7.png)

### Probable Errors and Troubleshooting[​](#probable-errors-and-troubleshooting "Direct link to heading")

Errors are not expected, but if you are facing some of the errors shown, then you could try troubleshooting as shown below. If none of the troubleshooting works, reach us through [Discord](https://discord.com/channels/578992315641626624/).

1. **Too many requests. Please try again after X minutes**: This is a rate-limiting message. Every Avalanche L1 can set its drop limits. The above message suggests that you have reached your drop limit, that is the number of times you could request coins within the window of X minutes. You should try requesting after X minutes. If you are facing this problem, even when you are requesting for the first time in the window, you may be behind some proxy, Wi-Fi, or VPN service that is also being used by some other user.  
2. **CAPTCHA verification failed! Try refreshing**: We are using v3 of [Google's reCAPTCHA](https://developers.google.com/recaptcha/docs/v3). This version uses scores between 0 and 1 to rate the interaction of humans with the site, with 0 being the most suspicious one. You do not have to solve any puzzle or mark the **I am not a Robot** checkbox. The score will be automatically calculated. We want our users to score at least 0.3 to use the faucet. This is configurable, and we will update the threshold after having broader data. But if you are facing this issue, then you can try refreshing your page, disabling ad-blockers, or switching off any VPN. You can follow this [guide](https://2captcha.com/blog/google-doesnt-accept-recaptcha-answers) to get rid of this issue.   
3. **Internal RPC error! Please try after sometime**: This is an internal error in the Avalanche L1's node, on which we are making an RPC for sending transactions. A regular check will update the RPC's health status every 30 seconds (default) or whatever is set in the configuration. This may happen only in rare scenarios and you cannot do much about it, rather than waiting.  
4. **Timeout of 10000ms exceeded**: There could be many reasons for this message. It could be an internal server error, or the request didn't receive by the server, slow internet, etc. You could try again after some time, and if the problem persists, then you should raise this issue on our [Discord](https://discord.com/channels/578992315641626624/) server.
5. **Couldn't see any transaction status on explorer**: The transaction hash that you get for each drop is pre-computed using the expected nonce, amount, and receiver's address. Though transactions on Avalanche are near-instant, the explorer may take time to index those transactions. You should wait for a few more seconds, before raising any issue or reaching out to us.


# cli info (/docs/avalanche-l1s/deploy-a-avalanche-l1/cli_structure)

---
title: cli info
description: cli flags and stuff
---
<a id="avalanche-blockchain"></a>
## avalanche blockchain

The blockchain command suite provides a collection of tools for developing
and deploying Blockchains.

To get started, use the blockchain create command wizard to walk through the
configuration of your very first Blockchain. Then, go ahead and deploy it
with the blockchain deploy command. You can use the rest of the commands to
manage your Blockchain configurations and live deployments.

**Usage:**
```bash
avalanche blockchain [subcommand] [flags]
```

**Subcommands:**

- [`addValidator`](#avalanche-blockchain-addvalidator): The blockchain addValidator command adds a node as a validator to
an L1 of the user provided deployed network. If the network is proof of 
authority, the owner of the validator manager contract must sign the 
transaction. If the network is proof of stake, the node must stake the L1's
staking token. Both processes will issue a RegisterL1ValidatorTx on the P-Chain.

This command currently only works on Blockchains deployed to either the Fuji
Testnet or Mainnet.
- [`changeOwner`](#avalanche-blockchain-changeowner): The blockchain changeOwner changes the owner of the subnet of the deployed Blockchain.
- [`changeWeight`](#avalanche-blockchain-changeweight): The blockchain changeWeight command changes the weight of a Subnet Validator.

The Subnet has to be a Proof of Authority Subnet-Only Validator Subnet.
- [`configure`](#avalanche-blockchain-configure): AvalancheGo nodes support several different configuration files. Subnets have their own
Subnet config which applies to all chains/VMs in the Subnet. Each chain within the Subnet
can have its own chain config. A chain can also have special requirements for the AvalancheGo node 
configuration itself. This command allows you to set all those files.
- [`create`](#avalanche-blockchain-create): The blockchain create command builds a new genesis file to configure your Blockchain.
By default, the command runs an interactive wizard. It walks you through
all the steps you need to create your first Blockchain.

The tool supports deploying Subnet-EVM, and custom VMs. You
can create a custom, user-generated genesis with a custom VM by providing
the path to your genesis and VM binaries with the --genesis and --vm flags.

By default, running the command with a blockchainName that already exists
causes the command to fail. If you'd like to overwrite an existing
configuration, pass the -f flag.
- [`delete`](#avalanche-blockchain-delete): The blockchain delete command deletes an existing blockchain configuration.
- [`deploy`](#avalanche-blockchain-deploy): The blockchain deploy command deploys your Blockchain configuration locally, to Fuji Testnet, or to Mainnet.

At the end of the call, the command prints the RPC URL you can use to interact with the Subnet.

Avalanche-CLI only supports deploying an individual Blockchain once per network. Subsequent
attempts to deploy the same Blockchain to the same network (local, Fuji, Mainnet) aren't
allowed. If you'd like to redeploy a Blockchain locally for testing, you must first call
avalanche network clean to reset all deployed chain state. Subsequent local deploys
redeploy the chain with fresh state. You can deploy the same Blockchain to multiple networks,
so you can take your locally tested Subnet and deploy it on Fuji or Mainnet.
- [`describe`](#avalanche-blockchain-describe): The blockchain describe command prints the details of a Blockchain configuration to the console.
By default, the command prints a summary of the configuration. By providing the --genesis
flag, the command instead prints out the raw genesis file.
- [`export`](#avalanche-blockchain-export): The blockchain export command write the details of an existing Blockchain deploy to a file.

The command prompts for an output path. You can also provide one with
the --output flag.
- [`import`](#avalanche-blockchain-import): Import blockchain configurations into avalanche-cli.

This command suite supports importing from a file created on another computer,
or importing from blockchains running public networks
(e.g. created manually or with the deprecated subnet-cli)
- [`join`](#avalanche-blockchain-join): The subnet join command configures your validator node to begin validating a new Blockchain.

To complete this process, you must have access to the machine running your validator. If the
CLI is running on the same machine as your validator, it can generate or update your node's
config file automatically. Alternatively, the command can print the necessary instructions
to update your node manually. To complete the validation process, the Subnet's admins must add
the NodeID of your validator to the Subnet's allow list by calling addValidator with your
NodeID.

After you update your validator's config, you need to restart your validator manually. If
you provide the --avalanchego-config flag, this command attempts to edit the config file
at that path.

This command currently only supports Blockchains deployed on the Fuji Testnet and Mainnet.
- [`list`](#avalanche-blockchain-list): The blockchain list command prints the names of all created Blockchain configurations. Without any flags,
it prints some general, static information about the Blockchain. With the --deployed flag, the command
shows additional information including the VMID, BlockchainID and SubnetID.
- [`publish`](#avalanche-blockchain-publish): The blockchain publish command publishes the Blockchain's VM to a repository.
- [`removeValidator`](#avalanche-blockchain-removevalidator): The blockchain removeValidator command stops a whitelisted, subnet network validator from
validating your deployed Blockchain.

To remove the validator from the Subnet's allow list, provide the validator's unique NodeID. You can bypass
these prompts by providing the values with flags.
- [`stats`](#avalanche-blockchain-stats): The blockchain stats command prints validator statistics for the given Blockchain.
- [`upgrade`](#avalanche-blockchain-upgrade): The blockchain upgrade command suite provides a collection of tools for
updating your developmental and deployed Blockchains.
- [`validators`](#avalanche-blockchain-validators): The blockchain validators command lists the validators of a blockchain's subnet and provides
several statistics about them.
- [`vmid`](#avalanche-blockchain-vmid): The blockchain vmid command prints the virtual machine ID (VMID) for the given Blockchain.

**Flags:**

```bash
-h, --help help             for blockchain
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-blockchain-addvalidator"></a>
### addValidator

The blockchain addValidator command adds a node as a validator to
an L1 of the user provided deployed network. If the network is proof of 
authority, the owner of the validator manager contract must sign the 
transaction. If the network is proof of stake, the node must stake the L1's
staking token. Both processes will issue a RegisterL1ValidatorTx on the P-Chain.

This command currently only works on Blockchains deployed to either the Fuji
Testnet or Mainnet.

**Usage:**
```bash
avalanche blockchain addValidator [subcommand] [flags]
```

**Flags:**

```bash
--aggregator-allow-private-peers allow    the signature aggregator to connect to peers with private IP (default true)
--aggregator-extra-endpoints strings      endpoints for extra nodes that are needed in signature aggregation
--aggregator-log-level string             log level to use with signature aggregator (default "Off")
--balance uint                            set the AVAX balance of the validator that will be used for continuous fee on P-Chain
--blockchain-genesis-key use              genesis allocated key to pay fees for completing the validator's registration (blockchain gas token)
--blockchain-key string                   CLI stored key to use to pay fees for completing the validator's registration (blockchain gas token)
--blockchain-private-key string           private key to use to pay fees for completing the validator's registration (blockchain gas token)
--bls-proof-of-possession string          set the BLS proof of possession of the validator to add
--bls-public-key string                   set the BLS public key of the validator to add
--cluster string                          operate on the given cluster
--create-local-validator create           additional local validator and add it to existing running local node
--default-duration                        (for Subnets, not L1s) set duration so as to validate until primary validator ends its period
--default-start-time                      (for Subnets, not L1s) use default start time for subnet validator (5 minutes later for fuji & mainnet, 30 seconds later for devnet)
--default-validator-params                (for Subnets, not L1s) use default weight/start/duration params for subnet validator
--delegation-fee uint16                   (PoS only) delegation fee (in bips) (default 100)
--devnet operate                          on a devnet network
--disable-owner string                    P-Chain address that will able to disable the validator with a P-Chain transaction
--endpoint string                         use the given endpoint for network operations
-e, --ewoq use                            ewoq key [fuji/devnet only]
-f, --fuji testnet                        operate on fuji (alias to testnet
-h, --help help                           for addValidator
-k, --key string                          select the key to use [fuji/devnet only]
-g, --ledger use                          ledger instead of key (always true on mainnet, defaults to false on fuji/devnet)
--ledger-addrs strings                    use the given ledger addresses
-l, --local operate                       on a local network
-m, --mainnet operate                     on mainnet
--node-endpoint string                    gather node id/bls from publicly available avalanchego apis on the given endpoint
--node-id string                          node-id of the validator to add
--output-tx-path string                   (for Subnets, not L1s) file path of the add validator tx
--partial-sync set                        primary network partial sync for new validators (default true)
--remaining-balance-owner string          P-Chain address that will receive any leftover AVAX from the validator when it is removed from Subnet
--rpc string                              connect to validator manager at the given rpc endpoint
--stake-amount uint                       (PoS only) amount of tokens to stake
--staking-period duration                 how long this validator will be staking
--start-time string                       (for Subnets, not L1s) UTC start time when this validator starts validating, in 'YYYY-MM-DD HH:MM:SS' format
--subnet-auth-keys strings                (for Subnets, not L1s) control keys that will be used to authenticate add validator tx
-t, --testnet fuji                        operate on testnet (alias to fuji)
--wait-for-tx-acceptance                  (for Subnets, not L1s) just issue the add validator tx, without waiting for its acceptance (default true)
--weight uint                             set the staking weight of the validator to add (default 20)
--config string                           config file (default is $HOME/.avalanche-cli/config.json)
--log-level string                        log level for the application (default "ERROR")
--skip-update-check skip                  check for new versions
```

<a id="avalanche-blockchain-changeowner"></a>
### changeOwner

The blockchain changeOwner changes the owner of the subnet of the deployed Blockchain.

**Usage:**
```bash
avalanche blockchain changeOwner [subcommand] [flags]
```

**Flags:**

```bash
--cluster string              operate on the given cluster
--control-keys strings        addresses that may make subnet changes
--devnet operate              on a devnet network
--endpoint string             use the given endpoint for network operations
-e, --ewoq use                ewoq key [fuji/devnet]
-f, --fuji testnet            operate on fuji (alias to testnet
-h, --help help               for changeOwner
-k, --key string              select the key to use [fuji/devnet]
-g, --ledger use              ledger instead of key (always true on mainnet, defaults to false on fuji/devnet)
--ledger-addrs strings        use the given ledger addresses
-l, --local operate           on a local network
-m, --mainnet operate         on mainnet
--output-tx-path string       file path of the transfer subnet ownership tx
-s, --same-control-key use    the fee-paying key as control key
--subnet-auth-keys strings    control keys that will be used to authenticate transfer subnet ownership tx
-t, --testnet fuji            operate on testnet (alias to fuji)
--threshold uint32            required number of control key signatures to make subnet changes
--config string               config file (default is $HOME/.avalanche-cli/config.json)
--log-level string            log level for the application (default "ERROR")
--skip-update-check skip      check for new versions
```

<a id="avalanche-blockchain-changeweight"></a>
### changeWeight

The blockchain changeWeight command changes the weight of a Subnet Validator.

The Subnet has to be a Proof of Authority Subnet-Only Validator Subnet.

**Usage:**
```bash
avalanche blockchain changeWeight [subcommand] [flags]
```

**Flags:**

```bash
--cluster string            operate on the given cluster
--devnet operate            on a devnet network
--endpoint string           use the given endpoint for network operations
-e, --ewoq use              ewoq key [fuji/devnet only]
-f, --fuji testnet          operate on fuji (alias to testnet
-h, --help help             for changeWeight
-k, --key string            select the key to use [fuji/devnet only]
-g, --ledger use            ledger instead of key (always true on mainnet, defaults to false on fuji/devnet)
--ledger-addrs strings      use the given ledger addresses
-l, --local operate         on a local network
-m, --mainnet operate       on mainnet
--node-id string            node-id of the validator
-t, --testnet fuji          operate on testnet (alias to fuji)
--weight uint               set the new staking weight of the validator (default 20)
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-blockchain-configure"></a>
### configure

AvalancheGo nodes support several different configuration files. Subnets have their own
Subnet config which applies to all chains/VMs in the Subnet. Each chain within the Subnet
can have its own chain config. A chain can also have special requirements for the AvalancheGo node 
configuration itself. This command allows you to set all those files.

**Usage:**
```bash
avalanche blockchain configure [subcommand] [flags]
```

**Flags:**

```bash
--chain-config string             path to the chain configuration
-h, --help help                   for configure
--node-config string              path to avalanchego node configuration
--per-node-chain-config string    path to per node chain configuration for local network
--subnet-config string            path to the subnet configuration
--config string                   config file (default is $HOME/.avalanche-cli/config.json)
--log-level string                log level for the application (default "ERROR")
--skip-update-check skip          check for new versions
```

<a id="avalanche-blockchain-create"></a>
### create

The blockchain create command builds a new genesis file to configure your Blockchain.
By default, the command runs an interactive wizard. It walks you through
all the steps you need to create your first Blockchain.

The tool supports deploying Subnet-EVM, and custom VMs. You
can create a custom, user-generated genesis with a custom VM by providing
the path to your genesis and VM binaries with the --genesis and --vm flags.

By default, running the command with a blockchainName that already exists
causes the command to fail. If you'd like to overwrite an existing
configuration, pass the -f flag.

**Usage:**
```bash
avalanche blockchain create [subcommand] [flags]
```

**Flags:**

```bash
--custom use                        a custom VM template
--custom-vm-branch string           custom vm branch or commit
--custom-vm-build-script string     custom vm build-script
--custom-vm-path string             file path of custom vm to use
--custom-vm-repo-url string         custom vm repository url
--debug enable                      blockchain debugging (default true)
--evm use                           the Subnet-EVM as the base template
--evm-chain-id uint                 chain ID to use with Subnet-EVM
--evm-defaults deprecation          notice: use '--production-defaults'
--evm-token string                  token symbol to use with Subnet-EVM
--external-gas-token use            a gas token from another blockchain
-f, --force overwrite               the existing configuration if one exists
--from-github-repo generate         custom VM binary from github repository
--genesis string                    file path of genesis to use
-h, --help help                     for create
--icm interoperate                  with other blockchains using ICM
--icm-registry-at-genesis setup     ICM registry smart contract on genesis [experimental]
--latest use                        latest Subnet-EVM released version, takes precedence over --vm-version
--pre-release use                   latest Subnet-EVM pre-released version, takes precedence over --vm-version
--production-defaults use           default production settings for your blockchain
--proof-of-authority use            proof of authority(PoA) for validator management
--proof-of-stake use                proof of stake(PoS) for validator management
--proxy-contract-owner string       EVM address that controls ProxyAdmin for TransparentProxy of ValidatorManager contract
--reward-basis-points uint          (PoS only) reward basis points for PoS Reward Calculator (default 100)
--sovereign set                     to false if creating non-sovereign blockchain (default true)
--teleporter interoperate           with other blockchains using ICM
--test-defaults use                 default test settings for your blockchain
--validator-manager-owner string    EVM address that controls Validator Manager Owner
--vm string                         file path of custom vm to use. alias to custom-vm-path
--vm-version string                 version of Subnet-EVM template to use
--warp generate                     a vm with warp support (needed for ICM) (default true)
--config string                     config file (default is $HOME/.avalanche-cli/config.json)
--log-level string                  log level for the application (default "ERROR")
--skip-update-check skip            check for new versions
```

<a id="avalanche-blockchain-delete"></a>
### delete

The blockchain delete command deletes an existing blockchain configuration.

**Usage:**
```bash
avalanche blockchain delete [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help             for delete
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-blockchain-deploy"></a>
### deploy

The blockchain deploy command deploys your Blockchain configuration locally, to Fuji Testnet, or to Mainnet.

At the end of the call, the command prints the RPC URL you can use to interact with the Subnet.

Avalanche-CLI only supports deploying an individual Blockchain once per network. Subsequent
attempts to deploy the same Blockchain to the same network (local, Fuji, Mainnet) aren't
allowed. If you'd like to redeploy a Blockchain locally for testing, you must first call
avalanche network clean to reset all deployed chain state. Subsequent local deploys
redeploy the chain with fresh state. You can deploy the same Blockchain to multiple networks,
so you can take your locally tested Subnet and deploy it on Fuji or Mainnet.

**Usage:**
```bash
avalanche blockchain deploy [subcommand] [flags]
```

**Flags:**

```bash
--aggregator-allow-private-peers allow                 the signature aggregator to connect to peers with private IP (default true)
--aggregator-extra-endpoints strings                   endpoints for extra nodes that are needed in signature aggregation
--aggregator-log-level string                          log level to use with signature aggregator (default "Off")
--avalanchego-path string                              use this avalanchego binary path
--avalanchego-version string                           use this version of avalanchego (ex: v1.17.12) (default "latest-prerelease")
--balance float                                        set the AVAX balance of each bootstrap validator that will be used for continuous fee on P-Chain (default 0.1)
--blockchain-genesis-key use                           genesis allocated key to fund validator manager initialization
--blockchain-key string                                CLI stored key to use to fund validator manager initialization
--blockchain-private-key string                        private key to use to fund validator manager initialization
--bootstrap-endpoints strings                          take validator node info from the given endpoints
--bootstrap-filepath string                            JSON file path that provides details about bootstrap validators, leave Node-ID and BLS values empty if using --generate-node-id=true
--cchain-funding-key string                            key to be used to fund relayer account on cchain
--cchain-icm-key string                                key to be used to pay for ICM deploys on C-Chain
--change-owner-address string                          address that will receive change if node is no longer L1 validator
--cluster string                                       operate on the given cluster
--control-keys strings                                 addresses that may make subnet changes
--convert-only avoid                                   node track, restart and poa manager setup
--devnet operate                                       on a devnet network
--endpoint string                                      use the given endpoint for network operations
-e, --ewoq use                                         ewoq key [fuji/devnet deploy only]
-f, --fuji testnet                                     operate on fuji (alias to testnet
--generate-node-id whether                             to create new node id for bootstrap validators (Node-ID and BLS values in bootstrap JSON file will be overridden if --bootstrap-filepath flag is used)
-h, --help help                                        for deploy
--icm-key string                                       key to be used to pay for ICM deploys (default "cli-teleporter-deployer")
--icm-version string                                   ICM version to deploy (default "latest")
-k, --key string                                       select the key to use [fuji/devnet deploy only]
-g, --ledger use                                       ledger instead of key (always true on mainnet, defaults to false on fuji/devnet)
--ledger-addrs strings                                 use the given ledger addresses
-l, --local operate                                    on a local network
-m, --mainnet operate                                  on mainnet
--mainnet-chain-id uint32                              use different ChainID for mainnet deployment
--noicm skip                                           automatic ICM deploy
--num-bootstrap-validators int                         (only if --generate-node-id is true) number of bootstrap validators to set up in sovereign L1 validator)
--num-local-nodes int                                  number of nodes to be created on local machine
--num-nodes uint32                                     number of nodes to be created on local network deploy (default 2)
--output-tx-path string                                file path of the blockchain creation tx
--partial-sync set                                     primary network partial sync for new validators (default true)
--pos-maximum-stake-amount uint                        maximum stake amount (default 1000)
--pos-maximum-stake-multiplier uint8                   maximum stake multiplier (default 1)
--pos-minimum-delegation-fee uint16                    minimum delegation fee (default 1)
--pos-minimum-stake-amount uint                        minimum stake amount (default 1)
--pos-minimum-stake-duration uint                      minimum stake duration (default 100)
--pos-weight-to-value-factor uint                      weight to value factor (default 1)
--relay-cchain relay                                   C-Chain as source and destination (default true)
--relayer-allow-private-ips allow                      relayer to connec to private ips (default true)
--relayer-amount float                                 automatically fund relayer fee payments with the given amount
--relayer-key string                                   key to be used by default both for rewards and to pay fees
--relayer-log-level string                             log level to be used for relayer logs (default "info")
--relayer-path string                                  relayer binary to use
--relayer-version string                               relayer version to deploy (default "latest-prerelease")
-s, --same-control-key use                             the fee-paying key as control key
--skip-icm-deploy skip                                 automatic ICM deploy
--skip-local-teleporter skip                           automatic ICM deploy on local networks [to be deprecated]
--skip-relayer skip                                    relayer deploy
--skip-teleporter-deploy skip                          automatic ICM deploy
--subnet-auth-keys strings                             control keys that will be used to authenticate chain creation
-u, --subnet-id string                                 do not create a subnet, deploy the blockchain into the given subnet id
--subnet-only only                                     create a subnet
--teleporter-messenger-contract-address-path string    path to an ICM Messenger contract address file
--teleporter-messenger-deployer-address-path string    path to an ICM Messenger deployer address file
--teleporter-messenger-deployer-tx-path string         path to an ICM Messenger deployer tx file
--teleporter-registry-bytecode-path string             path to an ICM Registry bytecode file
--teleporter-version string                            ICM version to deploy (default "latest")
-t, --testnet fuji                                     operate on testnet (alias to fuji)
--threshold uint32                                     required number of control key signatures to make subnet changes
--use-local-machine use                                local machine as a blockchain validator
--config string                                        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string                                     log level for the application (default "ERROR")
--skip-update-check skip                               check for new versions
```

<a id="avalanche-blockchain-describe"></a>
### describe

The blockchain describe command prints the details of a Blockchain configuration to the console.
By default, the command prints a summary of the configuration. By providing the --genesis
flag, the command instead prints out the raw genesis file.

**Usage:**
```bash
avalanche blockchain describe [subcommand] [flags]
```

**Flags:**

```bash
-g, --genesis Print         the genesis to the console directly instead of the summary
-h, --help help             for describe
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-blockchain-export"></a>
### export

The blockchain export command write the details of an existing Blockchain deploy to a file.

The command prompts for an output path. You can also provide one with
the --output flag.

**Usage:**
```bash
avalanche blockchain export [subcommand] [flags]
```

**Flags:**

```bash
--custom-vm-branch string          custom vm branch
--custom-vm-build-script string    custom vm build-script
--custom-vm-repo-url string        custom vm repository url
-h, --help help                    for export
-o, --output string                write the export data to the provided file path
--config string                    config file (default is $HOME/.avalanche-cli/config.json)
--log-level string                 log level for the application (default "ERROR")
--skip-update-check skip           check for new versions
```

<a id="avalanche-blockchain-import"></a>
### import

Import blockchain configurations into avalanche-cli.

This command suite supports importing from a file created on another computer,
or importing from blockchains running public networks
(e.g. created manually or with the deprecated subnet-cli)

**Usage:**
```bash
avalanche blockchain import [subcommand] [flags]
```

**Subcommands:**

- [`file`](#avalanche-blockchain-import-file): The blockchain import command will import a blockchain configuration from a file or a git repository.

To import from a file, you can optionally provide the path as a command-line argument.
Alternatively, running the command without any arguments triggers an interactive wizard.
To import from a repository, go through the wizard. By default, an imported Blockchain doesn't 
overwrite an existing Blockchain with the same name. To allow overwrites, provide the --force
flag.
- [`public`](#avalanche-blockchain-import-public): The blockchain import public command imports a Blockchain configuration from a running network.

By default, an imported Blockchain
doesn't overwrite an existing Blockchain with the same name. To allow overwrites, provide the --force
flag.

**Flags:**

```bash
-h, --help help             for import
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-blockchain-import-file"></a>
#### import file

The blockchain import command will import a blockchain configuration from a file or a git repository.

To import from a file, you can optionally provide the path as a command-line argument.
Alternatively, running the command without any arguments triggers an interactive wizard.
To import from a repository, go through the wizard. By default, an imported Blockchain doesn't 
overwrite an existing Blockchain with the same name. To allow overwrites, provide the --force
flag.

**Usage:**
```bash
avalanche blockchain import file [subcommand] [flags]
```

**Flags:**

```bash
--branch string             the repo branch to use if downloading a new repo
-f, --force overwrite       the existing configuration if one exists
-h, --help help             for file
--repo string               the repo to import (ex: ava-labs/avalanche-plugins-core) or url to download the repo from
--subnet string             the subnet configuration to import from the provided repo
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-blockchain-import-public"></a>
#### import public

The blockchain import public command imports a Blockchain configuration from a running network.

By default, an imported Blockchain
doesn't overwrite an existing Blockchain with the same name. To allow overwrites, provide the --force
flag.

**Usage:**
```bash
avalanche blockchain import public [subcommand] [flags]
```

**Flags:**

```bash
--blockchain-id string      the blockchain ID
--cluster string            operate on the given cluster
--custom use                a custom VM template
--devnet operate            on a devnet network
--endpoint string           use the given endpoint for network operations
--evm import                a subnet-evm
--force overwrite           the existing configuration if one exists
-f, --fuji testnet          operate on fuji (alias to testnet
-h, --help help             for public
-l, --local operate         on a local network
-m, --mainnet operate       on mainnet
--node-url string           [optional] URL of an already running subnet validator
-t, --testnet fuji          operate on testnet (alias to fuji)
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-blockchain-join"></a>
### join

The subnet join command configures your validator node to begin validating a new Blockchain.

To complete this process, you must have access to the machine running your validator. If the
CLI is running on the same machine as your validator, it can generate or update your node's
config file automatically. Alternatively, the command can print the necessary instructions
to update your node manually. To complete the validation process, the Subnet's admins must add
the NodeID of your validator to the Subnet's allow list by calling addValidator with your
NodeID.

After you update your validator's config, you need to restart your validator manually. If
you provide the --avalanchego-config flag, this command attempts to edit the config file
at that path.

This command currently only supports Blockchains deployed on the Fuji Testnet and Mainnet.

**Usage:**
```bash
avalanche blockchain join [subcommand] [flags]
```

**Flags:**

```bash
--avalanchego-config string    file path of the avalanchego config file
--cluster string               operate on the given cluster
--data-dir string              path of avalanchego's data dir directory
--devnet operate               on a devnet network
--endpoint string              use the given endpoint for network operations
--force-write if               true, skip to prompt to overwrite the config file
-f, --fuji testnet             operate on fuji (alias to testnet
-h, --help help                for join
-k, --key string               select the key to use [fuji only]
-g, --ledger use               ledger instead of key (always true on mainnet, defaults to false on fuji)
--ledger-addrs strings         use the given ledger addresses
-l, --local operate            on a local network
-m, --mainnet operate          on mainnet
--node-id string               set the NodeID of the validator to check
--plugin-dir string            file path of avalanchego's plugin directory
--print if                     true, print the manual config without prompting
--stake-amount uint            amount of tokens to stake on validator
--staking-period duration      how long validator validates for after start time
--start-time string            start time that validator starts validating
-t, --testnet fuji             operate on testnet (alias to fuji)
--config string                config file (default is $HOME/.avalanche-cli/config.json)
--log-level string             log level for the application (default "ERROR")
--skip-update-check skip       check for new versions
```

<a id="avalanche-blockchain-list"></a>
### list

The blockchain list command prints the names of all created Blockchain configurations. Without any flags,
it prints some general, static information about the Blockchain. With the --deployed flag, the command
shows additional information including the VMID, BlockchainID and SubnetID.

**Usage:**
```bash
avalanche blockchain list [subcommand] [flags]
```

**Flags:**

```bash
--deployed show             additional deploy information
-h, --help help             for list
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-blockchain-publish"></a>
### publish

The blockchain publish command publishes the Blockchain's VM to a repository.

**Usage:**
```bash
avalanche blockchain publish [subcommand] [flags]
```

**Flags:**

```bash
--alias string               We publish to a remote repo, but identify the repo locally under a user-provided alias (e.g. myrepo).
--force If                   true, ignores if the subnet has been published in the past, and attempts a forced publish.
-h, --help help              for publish
--no-repo-path string        Do not let the tool manage file publishing, but have it only generate the files and put them in the location given by this flag.
--repo-url string            The URL of the repo where we are publishing
--subnet-file-path string    Path to the Subnet description file. If not given, a prompting sequence will be initiated.
--vm-file-path string        Path to the VM description file. If not given, a prompting sequence will be initiated.
--config string              config file (default is $HOME/.avalanche-cli/config.json)
--log-level string           log level for the application (default "ERROR")
--skip-update-check skip     check for new versions
```

<a id="avalanche-blockchain-removevalidator"></a>
### removeValidator

The blockchain removeValidator command stops a whitelisted, subnet network validator from
validating your deployed Blockchain.

To remove the validator from the Subnet's allow list, provide the validator's unique NodeID. You can bypass
these prompts by providing the values with flags.

**Usage:**
```bash
avalanche blockchain removeValidator [subcommand] [flags]
```

**Flags:**

```bash
--aggregator-allow-private-peers allow    the signature aggregator to connect to peers with private IP (default true)
--aggregator-extra-endpoints strings      endpoints for extra nodes that are needed in signature aggregation
--aggregator-log-level string             log level to use with signature aggregator (default "Off")
--blockchain-genesis-key use              genesis allocated key to pay fees for completing the validator's removal (blockchain gas token)
--blockchain-key string                   CLI stored key to use to pay fees for completing the validator's removal (blockchain gas token)
--blockchain-private-key string           private key to use to pay fees for completing the validator's removal (blockchain gas token)
--cluster string                          operate on the given cluster
--devnet operate                          on a devnet network
--endpoint string                         use the given endpoint for network operations
--force force                             validator removal even if it's not getting rewarded
-f, --fuji testnet                        operate on fuji (alias to testnet
-h, --help help                           for removeValidator
-k, --key string                          select the key to use [fuji deploy only]
-g, --ledger use                          ledger instead of key (always true on mainnet, defaults to false on fuji)
--ledger-addrs strings                    use the given ledger addresses
-l, --local operate                       on a local network
-m, --mainnet operate                     on mainnet
--node-endpoint string                    remove validator that responds to the given endpoint
--node-id string                          node-id of the validator
--output-tx-path string                   (for non-SOV blockchain only) file path of the removeValidator tx
--rpc string                              connect to validator manager at the given rpc endpoint
--subnet-auth-keys strings                (for non-SOV blockchain only) control keys that will be used to authenticate the removeValidator tx
-t, --testnet fuji                        operate on testnet (alias to fuji)
--uptime uint                             validator's uptime in seconds. If not provided, it will be automatically calculated
--config string                           config file (default is $HOME/.avalanche-cli/config.json)
--log-level string                        log level for the application (default "ERROR")
--skip-update-check skip                  check for new versions
```

<a id="avalanche-blockchain-stats"></a>
### stats

The blockchain stats command prints validator statistics for the given Blockchain.

**Usage:**
```bash
avalanche blockchain stats [subcommand] [flags]
```

**Flags:**

```bash
--cluster string            operate on the given cluster
--devnet operate            on a devnet network
--endpoint string           use the given endpoint for network operations
-f, --fuji testnet          operate on fuji (alias to testnet
-h, --help help             for stats
-l, --local operate         on a local network
-m, --mainnet operate       on mainnet
-t, --testnet fuji          operate on testnet (alias to fuji)
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-blockchain-upgrade"></a>
### upgrade

The blockchain upgrade command suite provides a collection of tools for
updating your developmental and deployed Blockchains.

**Usage:**
```bash
avalanche blockchain upgrade [subcommand] [flags]
```

**Subcommands:**

- [`apply`](#avalanche-blockchain-upgrade-apply): Apply generated upgrade bytes to running Blockchain nodes to trigger a network upgrade.

For public networks (Fuji Testnet or Mainnet), to complete this process,
you must have access to the machine running your validator.
If the CLI is running on the same machine as your validator, it can manipulate your node's
configuration automatically. Alternatively, the command can print the necessary instructions
to upgrade your node manually.

After you update your validator's configuration, you need to restart your validator manually.
If you provide the --avalanchego-chain-config-dir flag, this command attempts to write the upgrade file at that path.
Refer to https://docs.avax.network/nodes/maintain/chain-config-flags#subnet-chain-configs for related documentation.
- [`export`](#avalanche-blockchain-upgrade-export): Export the upgrade bytes file to a location of choice on disk
- [`generate`](#avalanche-blockchain-upgrade-generate): The blockchain upgrade generate command builds a new upgrade.json file to customize your Blockchain. It
guides the user through the process using an interactive wizard.
- [`import`](#avalanche-blockchain-upgrade-import): Import the upgrade bytes file into the local environment
- [`print`](#avalanche-blockchain-upgrade-print): Print the upgrade.json file content
- [`vm`](#avalanche-blockchain-upgrade-vm): The blockchain upgrade vm command enables the user to upgrade their Blockchain's VM binary. The command
can upgrade both local Blockchains and publicly deployed Blockchains on Fuji and Mainnet.

The command walks the user through an interactive wizard. The user can skip the wizard by providing
command line flags.

**Flags:**

```bash
-h, --help help             for upgrade
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-blockchain-upgrade-apply"></a>
#### upgrade apply

Apply generated upgrade bytes to running Blockchain nodes to trigger a network upgrade.

For public networks (Fuji Testnet or Mainnet), to complete this process,
you must have access to the machine running your validator.
If the CLI is running on the same machine as your validator, it can manipulate your node's
configuration automatically. Alternatively, the command can print the necessary instructions
to upgrade your node manually.

After you update your validator's configuration, you need to restart your validator manually.
If you provide the --avalanchego-chain-config-dir flag, this command attempts to write the upgrade file at that path.
Refer to https://docs.avax.network/nodes/maintain/chain-config-flags#subnet-chain-configs for related documentation.

**Usage:**
```bash
avalanche blockchain upgrade apply [subcommand] [flags]
```

**Flags:**

```bash
--avalanchego-chain-config-dir string    avalanchego's chain config file directory (default "/Users/owen.wahlgren/.avalanchego/chains")
--config create                          upgrade config for future subnet deployments (same as generate)
--force If                               true, don't prompt for confirmation of timestamps in the past
--fuji fuji                              apply upgrade existing fuji deployment (alias for `testnet`)
-h, --help help                          for apply
--local local                            apply upgrade existing local deployment
--mainnet mainnet                        apply upgrade existing mainnet deployment
--print if                               true, print the manual config without prompting (for public networks only)
--testnet testnet                        apply upgrade existing testnet deployment (alias for `fuji`)
--log-level string                       log level for the application (default "ERROR")
--skip-update-check skip                 check for new versions
```

<a id="avalanche-blockchain-upgrade-export"></a>
#### upgrade export

Export the upgrade bytes file to a location of choice on disk

**Usage:**
```bash
avalanche blockchain upgrade export [subcommand] [flags]
```

**Flags:**

```bash
--force If                   true, overwrite a possibly existing file without prompting
-h, --help help              for export
--upgrade-filepath string    Export upgrade bytes file to location of choice on disk
--config string              config file (default is $HOME/.avalanche-cli/config.json)
--log-level string           log level for the application (default "ERROR")
--skip-update-check skip     check for new versions
```

<a id="avalanche-blockchain-upgrade-generate"></a>
#### upgrade generate

The blockchain upgrade generate command builds a new upgrade.json file to customize your Blockchain. It
guides the user through the process using an interactive wizard.

**Usage:**
```bash
avalanche blockchain upgrade generate [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help             for generate
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-blockchain-upgrade-import"></a>
#### upgrade import

Import the upgrade bytes file into the local environment

**Usage:**
```bash
avalanche blockchain upgrade import [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help              for import
--upgrade-filepath string    Import upgrade bytes file into local environment
--config string              config file (default is $HOME/.avalanche-cli/config.json)
--log-level string           log level for the application (default "ERROR")
--skip-update-check skip     check for new versions
```

<a id="avalanche-blockchain-upgrade-print"></a>
#### upgrade print

Print the upgrade.json file content

**Usage:**
```bash
avalanche blockchain upgrade print [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help             for print
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-blockchain-upgrade-vm"></a>
#### upgrade vm

The blockchain upgrade vm command enables the user to upgrade their Blockchain's VM binary. The command
can upgrade both local Blockchains and publicly deployed Blockchains on Fuji and Mainnet.

The command walks the user through an interactive wizard. The user can skip the wizard by providing
command line flags.

**Usage:**
```bash
avalanche blockchain upgrade vm [subcommand] [flags]
```

**Flags:**

```bash
--binary string             Upgrade to custom binary
--config upgrade            config for future subnet deployments
--fuji fuji                 upgrade existing fuji deployment (alias for `testnet`)
-h, --help help             for vm
--latest upgrade            to latest version
--local local               upgrade existing local deployment
--mainnet mainnet           upgrade existing mainnet deployment
--plugin-dir string         plugin directory to automatically upgrade VM
--print print               instructions for upgrading
--testnet testnet           upgrade existing testnet deployment (alias for `fuji`)
--version string            Upgrade to custom version
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-blockchain-validators"></a>
### validators

The blockchain validators command lists the validators of a blockchain's subnet and provides
several statistics about them.

**Usage:**
```bash
avalanche blockchain validators [subcommand] [flags]
```

**Flags:**

```bash
--cluster string            operate on the given cluster
--devnet operate            on a devnet network
--endpoint string           use the given endpoint for network operations
-f, --fuji testnet          operate on fuji (alias to testnet
-h, --help help             for validators
-l, --local operate         on a local network
-m, --mainnet operate       on mainnet
-t, --testnet fuji          operate on testnet (alias to fuji)
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-blockchain-vmid"></a>
### vmid

The blockchain vmid command prints the virtual machine ID (VMID) for the given Blockchain.

**Usage:**
```bash
avalanche blockchain vmid [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help             for vmid
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-config"></a>
## avalanche config

Customize configuration for Avalanche-CLI

**Usage:**
```bash
avalanche config [subcommand] [flags]
```

**Subcommands:**

- [`authorize-cloud-access`](#avalanche-config-authorize-cloud-access): set preferences to authorize access to cloud resources
- [`metrics`](#avalanche-config-metrics): set user metrics collection preferences
- [`migrate`](#avalanche-config-migrate): migrate command migrates old ~/.avalanche-cli.json and ~/.avalanche-cli/config to /.avalanche-cli/config.json..
- [`snapshotsAutoSave`](#avalanche-config-snapshotsautosave): set user preference between auto saving local network snapshots or not
- [`update`](#avalanche-config-update): set user preference between update check or not

**Flags:**

```bash
-h, --help help             for config
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-config-authorize-cloud-access"></a>
### authorize-cloud-access

set preferences to authorize access to cloud resources

**Usage:**
```bash
avalanche config authorize-cloud-access [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help             for authorize-cloud-access
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-config-metrics"></a>
### metrics

set user metrics collection preferences

**Usage:**
```bash
avalanche config metrics [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help             for metrics
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-config-migrate"></a>
### migrate

migrate command migrates old ~/.avalanche-cli.json and ~/.avalanche-cli/config to /.avalanche-cli/config.json..

**Usage:**
```bash
avalanche config migrate [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help             for migrate
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-config-snapshotsautosave"></a>
### snapshotsAutoSave

set user preference between auto saving local network snapshots or not

**Usage:**
```bash
avalanche config snapshotsAutoSave [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help             for snapshotsAutoSave
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-config-update"></a>
### update

set user preference between update check or not

**Usage:**
```bash
avalanche config update [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help             for update
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-contract"></a>
## avalanche contract

The contract command suite provides a collection of tools for deploying
and interacting with smart contracts.

**Usage:**
```bash
avalanche contract [subcommand] [flags]
```

**Subcommands:**

- [`deploy`](#avalanche-contract-deploy): The contract command suite provides a collection of tools for deploying
smart contracts.
- [`initValidatorManager`](#avalanche-contract-initvalidatormanager): Initializes Proof of Authority(PoA) or Proof of Stake(PoS)Validator Manager contract on a Blockchain and sets up initial validator set on the Blockchain. For more info on Validator Manager, please head to https://github.com/ava-labs/icm-contracts/tree/main/contracts/validator-manager

**Flags:**

```bash
-h, --help help             for contract
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-contract-deploy"></a>
### deploy

The contract command suite provides a collection of tools for deploying
smart contracts.

**Usage:**
```bash
avalanche contract deploy [subcommand] [flags]
```

**Subcommands:**

- [`erc20`](#avalanche-contract-deploy-erc20): Deploy an ERC20 token into a given Network and Blockchain

**Flags:**

```bash
-h, --help help             for deploy
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-contract-deploy-erc20"></a>
#### deploy erc20

Deploy an ERC20 token into a given Network and Blockchain

**Usage:**
```bash
avalanche contract deploy erc20 [subcommand] [flags]
```

**Flags:**

```bash
--blockchain string         deploy the ERC20 contract into the given CLI blockchain
--blockchain-id string      deploy the ERC20 contract into the given blockchain ID/Alias
--c-chain deploy            the ERC20 contract into C-Chain
--cluster string            operate on the given cluster
--devnet operate            on a devnet network
--endpoint string           use the given endpoint for network operations
-f, --fuji testnet          operate on fuji (alias to testnet
--funded string             set the funded address
--genesis-key use           genesis allocated key as contract deployer
-h, --help help             for erc20
--key string                CLI stored key to use as contract deployer
-l, --local operate         on a local network
--private-key string        private key to use as contract deployer
--rpc string                deploy the contract into the given rpc endpoint
--supply uint               set the token supply
--symbol string             set the token symbol
-t, --testnet fuji          operate on testnet (alias to fuji)
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-contract-initvalidatormanager"></a>
### initValidatorManager

Initializes Proof of Authority(PoA) or Proof of Stake(PoS)Validator Manager contract on a Blockchain and sets up initial validator set on the Blockchain. For more info on Validator Manager, please head to https://github.com/ava-labs/icm-contracts/tree/main/contracts/validator-manager

**Usage:**
```bash
avalanche contract initValidatorManager [subcommand] [flags]
```

**Flags:**

```bash
--aggregator-allow-private-peers allow    the signature aggregator to connect to peers with private IP (default true)
--aggregator-extra-endpoints strings      endpoints for extra nodes that are needed in signature aggregation
--aggregator-log-level string             log level to use with signature aggregator (default "Off")
--cluster string                          operate on the given cluster
--devnet operate                          on a devnet network
--endpoint string                         use the given endpoint for network operations
-f, --fuji testnet                        operate on fuji (alias to testnet
--genesis-key use                         genesis allocated key as contract deployer
-h, --help help                           for initValidatorManager
--key string                              CLI stored key to use as contract deployer
-l, --local operate                       on a local network
-m, --mainnet operate                     on mainnet
--pos-maximum-stake-amount uint           (PoS only) maximum stake amount (default 1000)
--pos-maximum-stake-multiplier uint8      (PoS only )maximum stake multiplier (default 1)
--pos-minimum-delegation-fee uint16       (PoS only) minimum delegation fee (default 1)
--pos-minimum-stake-amount uint           (PoS only) minimum stake amount (default 1)
--pos-minimum-stake-duration uint         (PoS only) minimum stake duration (default 100)
--pos-reward-calculator-address string    (PoS only) initialize the ValidatorManager with reward calculator address
--pos-weight-to-value-factor uint         (PoS only) weight to value factor (default 1)
--private-key string                      private key to use as contract deployer
--rpc string                              deploy the contract into the given rpc endpoint
-t, --testnet fuji                        operate on testnet (alias to fuji)
--config string                           config file (default is $HOME/.avalanche-cli/config.json)
--log-level string                        log level for the application (default "ERROR")
--skip-update-check skip                  check for new versions
```

<a id="avalanche-help"></a>
## avalanche help

Help provides help for any command in the application.
Simply type avalanche help [path to command] for full details.

**Usage:**
```bash
avalanche help [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help             for help
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-icm"></a>
## avalanche icm

The messenger command suite provides a collection of tools for interacting
with ICM messenger contracts.

**Usage:**
```bash
avalanche icm [subcommand] [flags]
```

**Subcommands:**

- [`deploy`](#avalanche-icm-deploy): Deploys ICM Messenger and Registry into a given L1.
- [`sendMsg`](#avalanche-icm-sendmsg): Sends and wait reception for a ICM msg between two subnets.

**Flags:**

```bash
-h, --help help             for icm
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-icm-deploy"></a>
### deploy

Deploys ICM Messenger and Registry into a given L1.

**Usage:**
```bash
avalanche icm deploy [subcommand] [flags]
```

**Flags:**

```bash
--blockchain string                         deploy ICM into the given CLI blockchain
--blockchain-id string                      deploy ICM into the given blockchain ID/Alias
--c-chain deploy                            ICM into C-Chain
--cchain-key string                         key to be used to pay fees to deploy ICM to C-Chain
--cluster string                            operate on the given cluster
--deploy-messenger deploy                   ICM Messenger (default true)
--deploy-registry deploy                    ICM Registry (default true)
--devnet operate                            on a devnet network
--endpoint string                           use the given endpoint for network operations
--force-registry-deploy deploy              ICM Registry even if Messenger has already been deployed
-f, --fuji testnet                          operate on fuji (alias to testnet
--genesis-key use                           genesis allocated key to fund ICM deploy
-h, --help help                             for deploy
--include-cchain deploy                     ICM also to C-Chain
--key string                                CLI stored key to use to fund ICM deploy
-l, --local operate                         on a local network
--messenger-contract-address-path string    path to a messenger contract address file
--messenger-deployer-address-path string    path to a messenger deployer address file
--messenger-deployer-tx-path string         path to a messenger deployer tx file
--private-key string                        private key to use to fund ICM deploy
--registry-bytecode-path string             path to a registry bytecode file
--rpc-url string                            use the given RPC URL to connect to the subnet
-t, --testnet fuji                          operate on testnet (alias to fuji)
--version string                            version to deploy (default "latest")
--config string                             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string                          log level for the application (default "ERROR")
--skip-update-check skip                    check for new versions
```

<a id="avalanche-icm-sendmsg"></a>
### sendMsg

Sends and wait reception for a ICM msg between two subnets.

**Usage:**
```bash
avalanche icm sendMsg [subcommand] [flags]
```

**Flags:**

```bash
--cluster string                operate on the given cluster
--dest-rpc string               use the given destination blockchain rpc endpoint
--destination-address string    deliver the message to the given contract destination address
--devnet operate                on a devnet network
--endpoint string               use the given endpoint for network operations
-f, --fuji testnet              operate on fuji (alias to testnet
--genesis-key use               genesis allocated key as message originator and to pay source blockchain fees
-h, --help help                 for sendMsg
--hex-encoded given             message is hex encoded
--key string                    CLI stored key to use as message originator and to pay source blockchain fees
-l, --local operate             on a local network
--private-key string            private key to use as message originator and to pay source blockchain fees
--source-rpc string             use the given source blockchain rpc endpoint
-t, --testnet fuji              operate on testnet (alias to fuji)
--config string                 config file (default is $HOME/.avalanche-cli/config.json)
--log-level string              log level for the application (default "ERROR")
--skip-update-check skip        check for new versions
```

<a id="avalanche-ictt"></a>
## avalanche ictt

The ictt command suite provides tools to deploy and manage Interchain Token Transferrers.

**Usage:**
```bash
avalanche ictt [subcommand] [flags]
```

**Subcommands:**

- [`deploy`](#avalanche-ictt-deploy): Deploys a Token Transferrer into a given Network and Subnets

**Flags:**

```bash
-h, --help help             for ictt
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-ictt-deploy"></a>
### deploy

Deploys a Token Transferrer into a given Network and Subnets

**Usage:**
```bash
avalanche ictt deploy [subcommand] [flags]
```

**Flags:**

```bash
--c-chain-home set               the Transferrer's Home Chain into C-Chain
--c-chain-remote set             the Transferrer's Remote Chain into C-Chain
--cluster string                 operate on the given cluster
--deploy-erc20-home string       deploy a Transferrer Home for the given Chain's ERC20 Token
--deploy-native-home deploy      a Transferrer Home for the Chain's Native Token
--deploy-native-remote deploy    a Transferrer Remote for the Chain's Native Token
--devnet operate                 on a devnet network
--endpoint string                use the given endpoint for network operations
-f, --fuji testnet               operate on fuji (alias to testnet
-h, --help help                  for deploy
--home-blockchain string         set the Transferrer's Home Chain into the given CLI blockchain
--home-genesis-key use           genesis allocated key to deploy Transferrer Home
--home-key string                CLI stored key to use to deploy Transferrer Home
--home-private-key string        private key to use to deploy Transferrer Home
--home-rpc string                use the given RPC URL to connect to the home blockchain
-l, --local operate              on a local network
--remote-blockchain string       set the Transferrer's Remote Chain into the given CLI blockchain
--remote-genesis-key use         genesis allocated key to deploy Transferrer Remote
--remote-key string              CLI stored key to use to deploy Transferrer Remote
--remote-private-key string      private key to use to deploy Transferrer Remote
--remote-rpc string              use the given RPC URL to connect to the remote blockchain
--remote-token-decimals uint8    use the given number of token decimals for the Transferrer Remote [defaults to token home's decimals (18 for a new wrapped native home token)]
--remove-minter-admin remove     the native minter precompile admin found on remote blockchain genesis
-t, --testnet fuji               operate on testnet (alias to fuji)
--use-home string                use the given Transferrer's Home Address
--version string                 tag/branch/commit of Avalanche Interchain Token Transfer (ICTT) to be used (defaults to main branch)
--config string                  config file (default is $HOME/.avalanche-cli/config.json)
--log-level string               log level for the application (default "ERROR")
--skip-update-check skip         check for new versions
```

<a id="avalanche-interchain"></a>
## avalanche interchain

The interchain command suite provides a collection of tools to
set and manage interoperability between blockchains.

**Usage:**
```bash
avalanche interchain [subcommand] [flags]
```

**Subcommands:**

- [`messenger`](#avalanche-interchain-messenger): The messenger command suite provides a collection of tools for interacting
with ICM messenger contracts.
- [`relayer`](#avalanche-interchain-relayer): The relayer command suite provides a collection of tools for deploying
and configuring an ICM relayers.
- [`tokenTransferrer`](#avalanche-interchain-tokentransferrer): The tokenTransfer command suite provides tools to deploy and manage Token Transferrers.

**Flags:**

```bash
-h, --help help             for interchain
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-interchain-messenger"></a>
### messenger

The messenger command suite provides a collection of tools for interacting
with ICM messenger contracts.

**Usage:**
```bash
avalanche interchain messenger [subcommand] [flags]
```

**Subcommands:**

- [`deploy`](#avalanche-interchain-messenger-deploy): Deploys ICM Messenger and Registry into a given L1.
- [`sendMsg`](#avalanche-interchain-messenger-sendmsg): Sends and wait reception for a ICM msg between two subnets.

**Flags:**

```bash
-h, --help help             for messenger
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-interchain-messenger-deploy"></a>
#### messenger deploy

Deploys ICM Messenger and Registry into a given L1.

**Usage:**
```bash
avalanche interchain messenger deploy [subcommand] [flags]
```

**Flags:**

```bash
--blockchain string                         deploy ICM into the given CLI blockchain
--blockchain-id string                      deploy ICM into the given blockchain ID/Alias
--c-chain deploy                            ICM into C-Chain
--cchain-key string                         key to be used to pay fees to deploy ICM to C-Chain
--cluster string                            operate on the given cluster
--deploy-messenger deploy                   ICM Messenger (default true)
--deploy-registry deploy                    ICM Registry (default true)
--devnet operate                            on a devnet network
--endpoint string                           use the given endpoint for network operations
--force-registry-deploy deploy              ICM Registry even if Messenger has already been deployed
-f, --fuji testnet                          operate on fuji (alias to testnet
--genesis-key use                           genesis allocated key to fund ICM deploy
-h, --help help                             for deploy
--include-cchain deploy                     ICM also to C-Chain
--key string                                CLI stored key to use to fund ICM deploy
-l, --local operate                         on a local network
--messenger-contract-address-path string    path to a messenger contract address file
--messenger-deployer-address-path string    path to a messenger deployer address file
--messenger-deployer-tx-path string         path to a messenger deployer tx file
--private-key string                        private key to use to fund ICM deploy
--registry-bytecode-path string             path to a registry bytecode file
--rpc-url string                            use the given RPC URL to connect to the subnet
-t, --testnet fuji                          operate on testnet (alias to fuji)
--version string                            version to deploy (default "latest")
--config string                             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string                          log level for the application (default "ERROR")
--skip-update-check skip                    check for new versions
```

<a id="avalanche-interchain-messenger-sendmsg"></a>
#### messenger sendMsg

Sends and wait reception for a ICM msg between two subnets.

**Usage:**
```bash
avalanche interchain messenger sendMsg [subcommand] [flags]
```

**Flags:**

```bash
--cluster string                operate on the given cluster
--dest-rpc string               use the given destination blockchain rpc endpoint
--destination-address string    deliver the message to the given contract destination address
--devnet operate                on a devnet network
--endpoint string               use the given endpoint for network operations
-f, --fuji testnet              operate on fuji (alias to testnet
--genesis-key use               genesis allocated key as message originator and to pay source blockchain fees
-h, --help help                 for sendMsg
--hex-encoded given             message is hex encoded
--key string                    CLI stored key to use as message originator and to pay source blockchain fees
-l, --local operate             on a local network
--private-key string            private key to use as message originator and to pay source blockchain fees
--source-rpc string             use the given source blockchain rpc endpoint
-t, --testnet fuji              operate on testnet (alias to fuji)
--config string                 config file (default is $HOME/.avalanche-cli/config.json)
--log-level string              log level for the application (default "ERROR")
--skip-update-check skip        check for new versions
```

<a id="avalanche-interchain-relayer"></a>
### relayer

The relayer command suite provides a collection of tools for deploying
and configuring an ICM relayers.

**Usage:**
```bash
avalanche interchain relayer [subcommand] [flags]
```

**Subcommands:**

- [`deploy`](#avalanche-interchain-relayer-deploy): Deploys an ICM Relayer for the given Network.
- [`logs`](#avalanche-interchain-relayer-logs): Shows pretty formatted AWM relayer logs
- [`start`](#avalanche-interchain-relayer-start): Starts AWM relayer on the specified network (Currently only for local network).
- [`stop`](#avalanche-interchain-relayer-stop): Stops AWM relayer on the specified network (Currently only for local network, cluster).

**Flags:**

```bash
-h, --help help             for relayer
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-interchain-relayer-deploy"></a>
#### relayer deploy

Deploys an ICM Relayer for the given Network.

**Usage:**
```bash
avalanche interchain relayer deploy [subcommand] [flags]
```

**Flags:**

```bash
--allow-private-ips allow          relayer to connec to private ips (default true)
--amount float                     automatically fund l1s fee payments with the given amount
--bin-path string                  use the given relayer binary
--blockchain-funding-key string    key to be used to fund relayer account on all l1s
--blockchains strings              blockchains to relay as source and destination
--cchain relay                     C-Chain as source and destination
--cchain-amount float              automatically fund cchain fee payments with the given amount
--cchain-funding-key string        key to be used to fund relayer account on cchain
--cluster string                   operate on the given cluster
--devnet operate                   on a devnet network
--endpoint string                  use the given endpoint for network operations
-f, --fuji testnet                 operate on fuji (alias to testnet
-h, --help help                    for deploy
--key string                       key to be used by default both for rewards and to pay fees
-l, --local operate                on a local network
--log-level string                 log level to use for relayer logs
-t, --testnet fuji                 operate on testnet (alias to fuji)
--version string                   version to deploy (default "latest-prerelease")
--config string                    config file (default is $HOME/.avalanche-cli/config.json)
--skip-update-check skip           check for new versions
```

<a id="avalanche-interchain-relayer-logs"></a>
#### relayer logs

Shows pretty formatted AWM relayer logs

**Usage:**
```bash
avalanche interchain relayer logs [subcommand] [flags]
```

**Flags:**

```bash
--endpoint string           use the given endpoint for network operations
--first uint                output first N log lines
-f, --fuji testnet          operate on fuji (alias to testnet
-h, --help help             for logs
--last uint                 output last N log lines
-l, --local operate         on a local network
--raw raw                   logs output
-t, --testnet fuji          operate on testnet (alias to fuji)
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-interchain-relayer-start"></a>
#### relayer start

Starts AWM relayer on the specified network (Currently only for local network).

**Usage:**
```bash
avalanche interchain relayer start [subcommand] [flags]
```

**Flags:**

```bash
--bin-path string           use the given relayer binary
--cluster string            operate on the given cluster
--endpoint string           use the given endpoint for network operations
-f, --fuji testnet          operate on fuji (alias to testnet
-h, --help help             for start
-l, --local operate         on a local network
-t, --testnet fuji          operate on testnet (alias to fuji)
--version string            version to use (default "latest-prerelease")
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-interchain-relayer-stop"></a>
#### relayer stop

Stops AWM relayer on the specified network (Currently only for local network, cluster).

**Usage:**
```bash
avalanche interchain relayer stop [subcommand] [flags]
```

**Flags:**

```bash
--cluster string            operate on the given cluster
--endpoint string           use the given endpoint for network operations
-f, --fuji testnet          operate on fuji (alias to testnet
-h, --help help             for stop
-l, --local operate         on a local network
-t, --testnet fuji          operate on testnet (alias to fuji)
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-interchain-tokentransferrer"></a>
### tokenTransferrer

The tokenTransfer command suite provides tools to deploy and manage Token Transferrers.

**Usage:**
```bash
avalanche interchain tokenTransferrer [subcommand] [flags]
```

**Subcommands:**

- [`deploy`](#avalanche-interchain-tokentransferrer-deploy): Deploys a Token Transferrer into a given Network and Subnets

**Flags:**

```bash
-h, --help help             for tokenTransferrer
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-interchain-tokentransferrer-deploy"></a>
#### tokenTransferrer deploy

Deploys a Token Transferrer into a given Network and Subnets

**Usage:**
```bash
avalanche interchain tokenTransferrer deploy [subcommand] [flags]
```

**Flags:**

```bash
--c-chain-home set               the Transferrer's Home Chain into C-Chain
--c-chain-remote set             the Transferrer's Remote Chain into C-Chain
--cluster string                 operate on the given cluster
--deploy-erc20-home string       deploy a Transferrer Home for the given Chain's ERC20 Token
--deploy-native-home deploy      a Transferrer Home for the Chain's Native Token
--deploy-native-remote deploy    a Transferrer Remote for the Chain's Native Token
--devnet operate                 on a devnet network
--endpoint string                use the given endpoint for network operations
-f, --fuji testnet               operate on fuji (alias to testnet
-h, --help help                  for deploy
--home-blockchain string         set the Transferrer's Home Chain into the given CLI blockchain
--home-genesis-key use           genesis allocated key to deploy Transferrer Home
--home-key string                CLI stored key to use to deploy Transferrer Home
--home-private-key string        private key to use to deploy Transferrer Home
--home-rpc string                use the given RPC URL to connect to the home blockchain
-l, --local operate              on a local network
--remote-blockchain string       set the Transferrer's Remote Chain into the given CLI blockchain
--remote-genesis-key use         genesis allocated key to deploy Transferrer Remote
--remote-key string              CLI stored key to use to deploy Transferrer Remote
--remote-private-key string      private key to use to deploy Transferrer Remote
--remote-rpc string              use the given RPC URL to connect to the remote blockchain
--remote-token-decimals uint8    use the given number of token decimals for the Transferrer Remote [defaults to token home's decimals (18 for a new wrapped native home token)]
--remove-minter-admin remove     the native minter precompile admin found on remote blockchain genesis
-t, --testnet fuji               operate on testnet (alias to fuji)
--use-home string                use the given Transferrer's Home Address
--version string                 tag/branch/commit of Avalanche Interchain Token Transfer (ICTT) to be used (defaults to main branch)
--config string                  config file (default is $HOME/.avalanche-cli/config.json)
--log-level string               log level for the application (default "ERROR")
--skip-update-check skip         check for new versions
```

<a id="avalanche-key"></a>
## avalanche key

The key command suite provides a collection of tools for creating and managing
signing keys. You can use these keys to deploy Subnets to the Fuji Testnet,
but these keys are NOT suitable to use in production environments. DO NOT use
these keys on Mainnet.

To get started, use the key create command.

**Usage:**
```bash
avalanche key [subcommand] [flags]
```

**Subcommands:**

- [`create`](#avalanche-key-create): The key create command generates a new private key to use for creating and controlling
test Subnets. Keys generated by this command are NOT cryptographically secure enough to
use in production environments. DO NOT use these keys on Mainnet.

The command works by generating a secp256 key and storing it with the provided keyName. You
can use this key in other commands by providing this keyName.

If you'd like to import an existing key instead of generating one from scratch, provide the
--file flag.
- [`delete`](#avalanche-key-delete): The key delete command deletes an existing signing key.

To delete a key, provide the keyName. The command prompts for confirmation
before deleting the key. To skip the confirmation, provide the --force flag.
- [`export`](#avalanche-key-export): The key export command exports a created signing key. You can use an exported key in other
applications or import it into another instance of Avalanche-CLI.

By default, the tool writes the hex encoded key to stdout. If you provide the --output
flag, the command writes the key to a file of your choosing.
- [`list`](#avalanche-key-list): The key list command prints information for all stored signing
keys or for the ledger addresses associated to certain indices.
- [`transfer`](#avalanche-key-transfer): The key transfer command allows to transfer funds between stored keys or ledger addresses.

**Flags:**

```bash
-h, --help help             for key
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-key-create"></a>
### create

The key create command generates a new private key to use for creating and controlling
test Subnets. Keys generated by this command are NOT cryptographically secure enough to
use in production environments. DO NOT use these keys on Mainnet.

The command works by generating a secp256 key and storing it with the provided keyName. You
can use this key in other commands by providing this keyName.

If you'd like to import an existing key instead of generating one from scratch, provide the
--file flag.

**Usage:**
```bash
avalanche key create [subcommand] [flags]
```

**Flags:**

```bash
--file string               import the key from an existing key file
-f, --force overwrite       an existing key with the same name
-h, --help help             for create
--skip-balances do          not query public network balances for an imported key
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-key-delete"></a>
### delete

The key delete command deletes an existing signing key.

To delete a key, provide the keyName. The command prompts for confirmation
before deleting the key. To skip the confirmation, provide the --force flag.

**Usage:**
```bash
avalanche key delete [subcommand] [flags]
```

**Flags:**

```bash
-f, --force delete          the key without confirmation
-h, --help help             for delete
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-key-export"></a>
### export

The key export command exports a created signing key. You can use an exported key in other
applications or import it into another instance of Avalanche-CLI.

By default, the tool writes the hex encoded key to stdout. If you provide the --output
flag, the command writes the key to a file of your choosing.

**Usage:**
```bash
avalanche key export [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help             for export
-o, --output string         write the key to the provided file path
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-key-list"></a>
### list

The key list command prints information for all stored signing
keys or for the ledger addresses associated to certain indices.

**Usage:**
```bash
avalanche key list [subcommand] [flags]
```

**Flags:**

```bash
-a, --all-networks list     all network addresses
--blockchains strings       blockchains to show information about (p=p-chain, x=x-chain, c=c-chain, and blockchain names) (default p,x,c)
-c, --cchain list           C-Chain addresses (default true)
--cluster string            operate on the given cluster
--devnet operate            on a devnet network
--endpoint string           use the given endpoint for network operations
-f, --fuji testnet          operate on fuji (alias to testnet
-h, --help help             for list
--keys strings              list addresses for the given keys
-g, --ledger uints          list ledger addresses for the given indices (default [])
-l, --local operate         on a local network
-m, --mainnet operate       on mainnet
--pchain list               P-Chain addresses (default true)
--subnets strings           subnets to show information about (p=p-chain, x=x-chain, c=c-chain, and subnet names) (default p,x,c)
-t, --testnet fuji          operate on testnet (alias to fuji)
--tokens strings            provide balance information for the given token contract addresses (Evm only) (default [Native])
--use-gwei use              gwei for EVM balances
-n, --use-nano-avax use     nano Avax for balances
--xchain list               X-Chain addresses (default true)
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-key-transfer"></a>
### transfer

The key transfer command allows to transfer funds between stored keys or ledger addresses.

**Usage:**
```bash
avalanche key transfer [subcommand] [flags]
```

**Flags:**

```bash
-o, --amount float                          amount to send or receive (AVAX or TOKEN units)
--c-chain-receiver receive                  at C-Chain
--c-chain-sender send                       from C-Chain
--cluster string                            operate on the given cluster
-a, --destination-addr string               destination address
--destination-key string                    key associated to a destination address
--destination-subnet string                 subnet where the funds will be sent (token transferrer experimental)
--destination-transferrer-address string    token transferrer address at the destination subnet (token transferrer experimental)
--devnet operate                            on a devnet network
--endpoint string                           use the given endpoint for network operations
-f, --fuji testnet                          operate on fuji (alias to testnet
-h, --help help                             for transfer
-k, --key string                            key associated to the sender or receiver address
-i, --ledger uint32                         ledger index associated to the sender or receiver address (default 32768)
-l, --local operate                         on a local network
-m, --mainnet operate                       on mainnet
--origin-subnet string                      subnet where the funds belong (token transferrer experimental)
--origin-transferrer-address string         token transferrer address at the origin subnet (token transferrer experimental)
--p-chain-receiver receive                  at P-Chain
--p-chain-sender send                       from P-Chain
--receiver-blockchain string                receive at the given CLI blockchain
--receiver-blockchain-id string             receive at the given blockchain ID/Alias
--sender-blockchain string                  send from the given CLI blockchain
--sender-blockchain-id string               send from the given blockchain ID/Alias
-t, --testnet fuji                          operate on testnet (alias to fuji)
--x-chain-receiver receive                  at X-Chain
--x-chain-sender send                       from X-Chain
--config string                             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string                          log level for the application (default "ERROR")
--skip-update-check skip                    check for new versions
```

<a id="avalanche-network"></a>
## avalanche network

The network command suite provides a collection of tools for managing local Subnet
deployments.

When you deploy a Subnet locally, it runs on a local, multi-node Avalanche network. The
subnet deploy command starts this network in the background. This command suite allows you
to shutdown, restart, and clear that network.

This network currently supports multiple, concurrently deployed Subnets.

**Usage:**
```bash
avalanche network [subcommand] [flags]
```

**Subcommands:**

- [`clean`](#avalanche-network-clean): The network clean command shuts down your local, multi-node network. All deployed Subnets
shutdown and delete their state. You can restart the network by deploying a new Subnet
configuration.
- [`start`](#avalanche-network-start): The network start command starts a local, multi-node Avalanche network on your machine.

By default, the command loads the default snapshot. If you provide the --snapshot-name
flag, the network loads that snapshot instead. The command fails if the local network is
already running.
- [`status`](#avalanche-network-status): The network status command prints whether or not a local Avalanche
network is running and some basic stats about the network.
- [`stop`](#avalanche-network-stop): The network stop command shuts down your local, multi-node network.

All deployed Subnets shutdown gracefully and save their state. If you provide the
--snapshot-name flag, the network saves its state under this named snapshot. You can
reload this snapshot with network start --snapshot-name `snapshotName`. Otherwise, the
network saves to the default snapshot, overwriting any existing state. You can reload the
default snapshot with network start.

**Flags:**

```bash
-h, --help help             for network
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-network-clean"></a>
### clean

The network clean command shuts down your local, multi-node network. All deployed Subnets
shutdown and delete their state. You can restart the network by deploying a new Subnet
configuration.

**Usage:**
```bash
avalanche network clean [subcommand] [flags]
```

**Flags:**

```bash
--hard Also                 clean downloaded avalanchego and plugin binaries
-h, --help help             for clean
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-network-start"></a>
### start

The network start command starts a local, multi-node Avalanche network on your machine.

By default, the command loads the default snapshot. If you provide the --snapshot-name
flag, the network loads that snapshot instead. The command fails if the local network is
already running.

**Usage:**
```bash
avalanche network start [subcommand] [flags]
```

**Flags:**

```bash
--avalanchego-path string       use this avalanchego binary path
--avalanchego-version string    use this version of avalanchego (ex: v1.17.12) (default "latest-prerelease")
-h, --help help                 for start
--num-nodes uint32              number of nodes to be created on local network (default 2)
--relayer-path string           use this relayer binary path
--relayer-version string        use this relayer version (default "latest-prerelease")
--snapshot-name string          name of snapshot to use to start the network from (default "default-1654102509")
--config string                 config file (default is $HOME/.avalanche-cli/config.json)
--log-level string              log level for the application (default "ERROR")
--skip-update-check skip        check for new versions
```

<a id="avalanche-network-status"></a>
### status

The network status command prints whether or not a local Avalanche
network is running and some basic stats about the network.

**Usage:**
```bash
avalanche network status [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help             for status
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-network-stop"></a>
### stop

The network stop command shuts down your local, multi-node network.

All deployed Subnets shutdown gracefully and save their state. If you provide the
--snapshot-name flag, the network saves its state under this named snapshot. You can
reload this snapshot with network start --snapshot-name `snapshotName`. Otherwise, the
network saves to the default snapshot, overwriting any existing state. You can reload the
default snapshot with network start.

**Usage:**
```bash
avalanche network stop [subcommand] [flags]
```

**Flags:**

```bash
--dont-save do              not save snapshot, just stop the network
-h, --help help             for stop
--snapshot-name string      name of snapshot to use to save network state into (default "default-1654102509")
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-node"></a>
## avalanche node

The node command suite provides a collection of tools for creating and maintaining 
validators on Avalanche Network.

To get started, use the node create command wizard to walk through the
configuration to make your node a primary validator on Avalanche public network. You can use the 
rest of the commands to maintain your node and make your node a Subnet Validator.

**Usage:**
```bash
avalanche node [subcommand] [flags]
```

**Subcommands:**

- [`addDashboard`](#avalanche-node-adddashboard): (ALPHA Warning) This command is currently in experimental mode. 

The node addDashboard command adds custom dashboard to the Grafana monitoring dashboard for the 
cluster.
- [`create`](#avalanche-node-create): (ALPHA Warning) This command is currently in experimental mode. 

The node create command sets up a validator on a cloud server of your choice. 
The validator will be validating the Avalanche Primary Network and Subnet 
of your choice. By default, the command runs an interactive wizard. It 
walks you through all the steps you need to set up a validator.
Once this command is completed, you will have to wait for the validator
to finish bootstrapping on the primary network before running further
commands on it, e.g. validating a Subnet. You can check the bootstrapping
status by running avalanche node status 

The created node will be part of group of validators called `clusterName` 
and users can call node commands with `clusterName` so that the command
will apply to all nodes in the cluster
- [`destroy`](#avalanche-node-destroy): (ALPHA Warning) This command is currently in experimental mode.

The node destroy command terminates all running nodes in cloud server and deletes all storage disks.

If there is a static IP address attached, it will be released.
- [`devnet`](#avalanche-node-devnet): (ALPHA Warning) This command is currently in experimental mode.

The node devnet command suite provides a collection of commands related to devnets.
You can check the updated status by calling avalanche node status `clusterName`
- [`export`](#avalanche-node-export): (ALPHA Warning) This command is currently in experimental mode.

The node export command exports cluster configuration and its nodes config to a text file.

If no file is specified, the configuration is printed to the stdout.

Use --include-secrets to include keys in the export. In this case please keep the file secure as it contains sensitive information.

Exported cluster configuration without secrets can be imported by another user using node import command.
- [`import`](#avalanche-node-import): (ALPHA Warning) This command is currently in experimental mode.

The node import command imports cluster configuration and its nodes configuration from a text file
created from the node export command.

Prior to calling this command, call node whitelist command to have your SSH public key and IP whitelisted by
the cluster owner. This will enable you to use avalanche-cli commands to manage the imported cluster.

Please note, that this imported cluster will be considered as EXTERNAL by avalanche-cli, so some commands
affecting cloud nodes like node create or node destroy will be not applicable to it.
- [`list`](#avalanche-node-list): (ALPHA Warning) This command is currently in experimental mode.

The node list command lists all clusters together with their nodes.
- [`loadtest`](#avalanche-node-loadtest): (ALPHA Warning) This command is currently in experimental mode. 

The node loadtest command suite starts and stops a load test for an existing devnet cluster.
- [`local`](#avalanche-node-local): (ALPHA Warning) This command is currently in experimental mode.

The node local command suite provides a collection of commands related to local nodes
- [`refresh-ips`](#avalanche-node-refresh-ips): (ALPHA Warning) This command is currently in experimental mode.

The node refresh-ips command obtains the current IP for all nodes with dynamic IPs in the cluster,
and updates the local node information used by CLI commands.
- [`resize`](#avalanche-node-resize): (ALPHA Warning) This command is currently in experimental mode.

The node resize command can change the amount of CPU, memory and disk space available for the cluster nodes.
- [`scp`](#avalanche-node-scp): (ALPHA Warning) This command is currently in experimental mode.

The node scp command securely copies files to and from nodes. Remote source or destionation can be specified using the following format:
[clusterName|nodeID|instanceID|IP]:/path/to/file. Regular expressions are supported for the source files like /tmp/*.txt.
File transfer to the nodes are parallelized. IF source or destination is cluster, the other should be a local file path. 
If both destinations are remote, they must be nodes for the same cluster and not clusters themselves.
For example:
$ avalanche node scp [cluster1|node1]:/tmp/file.txt /tmp/file.txt
$ avalanche node scp /tmp/file.txt [cluster1|NodeID-XXXX]:/tmp/file.txt
$ avalanche node scp node1:/tmp/file.txt NodeID-XXXX:/tmp/file.txt
- [`ssh`](#avalanche-node-ssh): (ALPHA Warning) This command is currently in experimental mode.

The node ssh command execute a given command [cmd] using ssh on all nodes in the cluster if ClusterName is given.
If no command is given, just prints the ssh command to be used to connect to each node in the cluster.
For provided NodeID or InstanceID or IP, the command [cmd] will be executed on that node.
If no [cmd] is provided for the node, it will open ssh shell there.
- [`status`](#avalanche-node-status): (ALPHA Warning) This command is currently in experimental mode.

The node status command gets the bootstrap status of all nodes in a cluster with the Primary Network. 
If no cluster is given, defaults to node list behaviour.

To get the bootstrap status of a node with a Blockchain, use --blockchain flag
- [`sync`](#avalanche-node-sync): (ALPHA Warning) This command is currently in experimental mode.

The node sync command enables all nodes in a cluster to be bootstrapped to a Blockchain.
You can check the blockchain bootstrap status by calling avalanche node status `clusterName` --blockchain `blockchainName`
- [`update`](#avalanche-node-update): (ALPHA Warning) This command is currently in experimental mode.

The node update command suite provides a collection of commands for nodes to update
their avalanchego or VM config.

You can check the status after update by calling avalanche node status
- [`upgrade`](#avalanche-node-upgrade): (ALPHA Warning) This command is currently in experimental mode.

The node update command suite provides a collection of commands for nodes to update
their avalanchego or VM version.

You can check the status after upgrade by calling avalanche node status
- [`validate`](#avalanche-node-validate): (ALPHA Warning) This command is currently in experimental mode.

The node validate command suite provides a collection of commands for nodes to join
the Primary Network and Subnets as validators.
If any of the commands is run before the nodes are bootstrapped on the Primary Network, the command 
will fail. You can check the bootstrap status by calling avalanche node status `clusterName`
- [`whitelist`](#avalanche-node-whitelist): (ALPHA Warning) The whitelist command suite provides a collection of tools for granting access to the cluster.

	Command adds IP if --ip params provided to cloud security access rules allowing it to access all nodes in the cluster via ssh or http.
	It also command adds SSH public key to all nodes in the cluster if --ssh params is there.
	If no params provided it detects current user IP automaticaly and whitelists it

**Flags:**

```bash
-h, --help help             for node
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-node-adddashboard"></a>
### addDashboard

(ALPHA Warning) This command is currently in experimental mode. 

The node addDashboard command adds custom dashboard to the Grafana monitoring dashboard for the 
cluster.

**Usage:**
```bash
avalanche node addDashboard [subcommand] [flags]
```

**Flags:**

```bash
--add-grafana-dashboard string    path to additional grafana dashboard json file
-h, --help help                   for addDashboard
--subnet string                   subnet that the dasbhoard is intended for (if any)
--config string                   config file (default is $HOME/.avalanche-cli/config.json)
--log-level string                log level for the application (default "ERROR")
--skip-update-check skip          check for new versions
```

<a id="avalanche-node-create"></a>
### create

(ALPHA Warning) This command is currently in experimental mode. 

The node create command sets up a validator on a cloud server of your choice. 
The validator will be validating the Avalanche Primary Network and Subnet 
of your choice. By default, the command runs an interactive wizard. It 
walks you through all the steps you need to set up a validator.
Once this command is completed, you will have to wait for the validator
to finish bootstrapping on the primary network before running further
commands on it, e.g. validating a Subnet. You can check the bootstrapping
status by running avalanche node status 

The created node will be part of group of validators called `clusterName` 
and users can call node commands with `clusterName` so that the command
will apply to all nodes in the cluster

**Usage:**
```bash
avalanche node create [subcommand] [flags]
```

**Flags:**

```bash
--add-grafana-dashboard string                      path to additional grafana dashboard json file
--alternative-key-pair-name string                  key pair name to use if default one generates conflicts
--authorize-access authorize                        CLI to create cloud resources
--auto-replace-keypair automatically                replaces key pair to access node if previous key pair is not found
--avalanchego-version-from-subnet string            install latest avalanchego version, that is compatible with the given subnet, on node/s
--aws create                                        node/s in AWS cloud
--aws-profile string                                aws profile to use (default "default")
--aws-volume-iops int                               AWS iops (for gp3, io1, and io2 volume types only) (default 3000)
--aws-volume-size int                               AWS volume size in GB (default 1000)
--aws-volume-throughput int                         AWS throughput in MiB/s (for gp3 volume type only) (default 125)
--aws-volume-type string                            AWS volume type (default "gp3")
--bootstrap-ids stringArray                         nodeIDs of bootstrap nodes
--bootstrap-ips stringArray                         IP:port pairs of bootstrap nodes
--cluster string                                    operate on the given cluster
--custom-avalanchego-version string                 install given avalanchego version on node/s
--devnet operate                                    on a devnet network
--enable-monitoring set                             up Prometheus monitoring for created nodes. This option creates a separate monitoring cloud instance and incures additional cost
--endpoint string                                   use the given endpoint for network operations
-f, --fuji testnet                                  operate on fuji (alias to testnet
--gcp create                                        node/s in GCP cloud
--gcp-credentials string                            use given GCP credentials
--gcp-project string                                use given GCP project
--genesis string                                    path to genesis file
--grafana-pkg string                                use grafana pkg instead of apt repo(by default), for example https://dl.grafana.com/oss/release/grafana_10.4.1_amd64.deb
-h, --help help                                     for create
--latest-avalanchego-pre-release-version install    latest avalanchego pre-release version on node/s
--latest-avalanchego-version install                latest avalanchego release version on node/s
-m, --mainnet operate                               on mainnet
--node-type string                                  cloud instance type. Use 'default' to use recommended default instance type
--num-apis ints                                     number of API nodes(nodes without stake) to create in the new Devnet
--num-validators ints                               number of nodes to create per region(s). Use comma to separate multiple numbers for each region in the same order as --region flag
--partial-sync primary                              network partial sync (default true)
--public-http-port allow                            public access to avalanchego HTTP port
--region strings                                    create node(s) in given region(s). Use comma to separate multiple regions
--ssh-agent-identity string                         use given ssh identity(only for ssh agent). If not set, default will be used
-t, --testnet fuji                                  operate on testnet (alias to fuji)
--upgrade string                                    path to upgrade file
--use-ssh-agent use                                 ssh agent(ex: Yubikey) for ssh auth
--use-static-ip attach                              static Public IP on cloud servers (default true)
--config string                                     config file (default is $HOME/.avalanche-cli/config.json)
--log-level string                                  log level for the application (default "ERROR")
--skip-update-check skip                            check for new versions
```

<a id="avalanche-node-destroy"></a>
### destroy

(ALPHA Warning) This command is currently in experimental mode.

The node destroy command terminates all running nodes in cloud server and deletes all storage disks.

If there is a static IP address attached, it will be released.

**Usage:**
```bash
avalanche node destroy [subcommand] [flags]
```

**Flags:**

```bash
--all destroy                    all existing clusters created by Avalanche CLI
--authorize-access authorize     CLI to release cloud resources
-y, --authorize-all authorize    all CLI requests
--authorize-remove authorize     CLI to remove all local files related to cloud nodes
--aws-profile string             aws profile to use (default "default")
-h, --help help                  for destroy
--config string                  config file (default is $HOME/.avalanche-cli/config.json)
--log-level string               log level for the application (default "ERROR")
--skip-update-check skip         check for new versions
```

<a id="avalanche-node-devnet"></a>
### devnet

(ALPHA Warning) This command is currently in experimental mode.

The node devnet command suite provides a collection of commands related to devnets.
You can check the updated status by calling avalanche node status `clusterName`

**Usage:**
```bash
avalanche node devnet [subcommand] [flags]
```

**Subcommands:**

- [`deploy`](#avalanche-node-devnet-deploy): (ALPHA Warning) This command is currently in experimental mode.

The node devnet deploy command deploys a subnet into a devnet cluster, creating subnet and blockchain txs for it.
It saves the deploy info both locally and remotely.
- [`wiz`](#avalanche-node-devnet-wiz): (ALPHA Warning) This command is currently in experimental mode.

The node wiz command creates a devnet and deploys, sync and validate a subnet into it. It creates the subnet if so needed.

**Flags:**

```bash
-h, --help help             for devnet
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-node-devnet-deploy"></a>
#### devnet deploy

(ALPHA Warning) This command is currently in experimental mode.

The node devnet deploy command deploys a subnet into a devnet cluster, creating subnet and blockchain txs for it.
It saves the deploy info both locally and remotely.

**Usage:**
```bash
avalanche node devnet deploy [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help             for deploy
--no-checks do              not check for healthy status or rpc compatibility of nodes against subnet
--subnet-aliases strings    additional subnet aliases to be used for RPC calls in addition to subnet blockchain name
--subnet-only only          create a subnet
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-node-devnet-wiz"></a>
#### devnet wiz

(ALPHA Warning) This command is currently in experimental mode.

The node wiz command creates a devnet and deploys, sync and validate a subnet into it. It creates the subnet if so needed.

**Usage:**
```bash
avalanche node devnet wiz [subcommand] [flags]
```

**Flags:**

```bash
--add-grafana-dashboard string                         path to additional grafana dashboard json file
--alternative-key-pair-name string                     key pair name to use if default one generates conflicts
--authorize-access authorize                           CLI to create cloud resources
--auto-replace-keypair automatically                   replaces key pair to access node if previous key pair is not found
--aws create                                           node/s in AWS cloud
--aws-profile string                                   aws profile to use (default "default")
--aws-volume-iops int                                  AWS iops (for gp3, io1, and io2 volume types only) (default 3000)
--aws-volume-size int                                  AWS volume size in GB (default 1000)
--aws-volume-throughput int                            AWS throughput in MiB/s (for gp3 volume type only) (default 125)
--aws-volume-type string                               AWS volume type (default "gp3")
--chain-config string                                  path to the chain configuration for subnet
--custom-avalanchego-version string                    install given avalanchego version on node/s
--custom-subnet use                                    a custom VM as the subnet virtual machine
--custom-vm-branch string                              custom vm branch or commit
--custom-vm-build-script string                        custom vm build-script
--custom-vm-repo-url string                            custom vm repository url
--default-validator-params use                         default weight/start/duration params for subnet validator
--deploy-icm-messenger deploy                          Interchain Messenger (default true)
--deploy-icm-registry deploy                           Interchain Registry (default true)
--deploy-teleporter-messenger deploy                   Interchain Messenger (default true)
--deploy-teleporter-registry deploy                    Interchain Registry (default true)
--enable-monitoring set                                up Prometheus monitoring for created nodes. Please note that this option creates a separate monitoring instance and incures additional cost
--evm-chain-id uint                                    chain ID to use with Subnet-EVM
--evm-defaults use                                     default production settings with Subnet-EVM
--evm-production-defaults use                          default production settings for your blockchain
--evm-subnet use                                       Subnet-EVM as the subnet virtual machine
--evm-test-defaults use                                default test settings for your blockchain
--evm-token string                                     token name to use with Subnet-EVM
--evm-version string                                   version of Subnet-EVM to use
--force-subnet-create overwrite                        the existing subnet configuration if one exists
--gcp create                                           node/s in GCP cloud
--gcp-credentials string                               use given GCP credentials
--gcp-project string                                   use given GCP project
--grafana-pkg string                                   use grafana pkg instead of apt repo(by default), for example https://dl.grafana.com/oss/release/grafana_10.4.1_amd64.deb
-h, --help help                                        for wiz
--icm generate                                         an icm-ready vm
--icm-messenger-contract-address-path string           path to an icm messenger contract address file
--icm-messenger-deployer-address-path string           path to an icm messenger deployer address file
--icm-messenger-deployer-tx-path string                path to an icm messenger deployer tx file
--icm-registry-bytecode-path string                    path to an icm registry bytecode file
--icm-version string                                   icm version to deploy (default "latest")
--latest-avalanchego-pre-release-version install       latest avalanchego pre-release version on node/s
--latest-avalanchego-version install                   latest avalanchego release version on node/s
--latest-evm-version use                               latest Subnet-EVM released version
--latest-pre-released-evm-version use                  latest Subnet-EVM pre-released version
--node-config string                                   path to avalanchego node configuration for subnet
--node-type string                                     cloud instance type. Use 'default' to use recommended default instance type
--num-apis ints                                        number of API nodes(nodes without stake) to create in the new Devnet
--num-validators ints                                  number of nodes to create per region(s). Use comma to separate multiple numbers for each region in the same order as --region flag
--public-http-port allow                               public access to avalanchego HTTP port
--region strings                                       create node/s in given region(s). Use comma to separate multiple regions
--relayer run                                          AWM relayer when deploying the vm
--ssh-agent-identity string                            use given ssh identity(only for ssh agent). If not set, default will be used.
--subnet-aliases strings                               additional subnet aliases to be used for RPC calls in addition to subnet blockchain name
--subnet-config string                                 path to the subnet configuration for subnet
--subnet-genesis string                                file path of the subnet genesis
--teleporter generate                                  an icm-ready vm
--teleporter-messenger-contract-address-path string    path to an icm messenger contract address file
--teleporter-messenger-deployer-address-path string    path to an icm messenger deployer address file
--teleporter-messenger-deployer-tx-path string         path to an icm messenger deployer tx file
--teleporter-registry-bytecode-path string             path to an icm registry bytecode file
--teleporter-version string                            icm version to deploy (default "latest")
--use-ssh-agent use                                    ssh agent for ssh
--use-static-ip attach                                 static Public IP on cloud servers (default true)
--validators strings                                   deploy subnet into given comma separated list of validators. defaults to all cluster nodes
--config string                                        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string                                     log level for the application (default "ERROR")
--skip-update-check skip                               check for new versions
```

<a id="avalanche-node-export"></a>
### export

(ALPHA Warning) This command is currently in experimental mode.

The node export command exports cluster configuration and its nodes config to a text file.

If no file is specified, the configuration is printed to the stdout.

Use --include-secrets to include keys in the export. In this case please keep the file secure as it contains sensitive information.

Exported cluster configuration without secrets can be imported by another user using node import command.

**Usage:**
```bash
avalanche node export [subcommand] [flags]
```

**Flags:**

```bash
--file string                specify the file to export the cluster configuration to
--force overwrite            the file if it exists
-h, --help help              for export
--include-secrets include    keys in the export
--config string              config file (default is $HOME/.avalanche-cli/config.json)
--log-level string           log level for the application (default "ERROR")
--skip-update-check skip     check for new versions
```

<a id="avalanche-node-import"></a>
### import

(ALPHA Warning) This command is currently in experimental mode.

The node import command imports cluster configuration and its nodes configuration from a text file
created from the node export command.

Prior to calling this command, call node whitelist command to have your SSH public key and IP whitelisted by
the cluster owner. This will enable you to use avalanche-cli commands to manage the imported cluster.

Please note, that this imported cluster will be considered as EXTERNAL by avalanche-cli, so some commands
affecting cloud nodes like node create or node destroy will be not applicable to it.

**Usage:**
```bash
avalanche node import [subcommand] [flags]
```

**Flags:**

```bash
--file string               specify the file to export the cluster configuration to
-h, --help help             for import
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-node-list"></a>
### list

(ALPHA Warning) This command is currently in experimental mode.

The node list command lists all clusters together with their nodes.

**Usage:**
```bash
avalanche node list [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help             for list
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-node-loadtest"></a>
### loadtest

(ALPHA Warning) This command is currently in experimental mode. 

The node loadtest command suite starts and stops a load test for an existing devnet cluster.

**Usage:**
```bash
avalanche node loadtest [subcommand] [flags]
```

**Subcommands:**

- [`start`](#avalanche-node-loadtest-start): (ALPHA Warning) This command is currently in experimental mode. 

The node loadtest command starts load testing for an existing devnet cluster. If the cluster does 
not have an existing load test host, the command creates a separate cloud server and builds the load 
test binary based on the provided load test Git Repo URL and load test binary build command. 

The command will then run the load test binary based on the provided load test run command.
- [`stop`](#avalanche-node-loadtest-stop): (ALPHA Warning) This command is currently in experimental mode. 

The node loadtest stop command stops load testing for an existing devnet cluster and terminates the 
separate cloud server created to host the load test.

**Flags:**

```bash
-h, --help help             for loadtest
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-node-loadtest-start"></a>
#### loadtest start

(ALPHA Warning) This command is currently in experimental mode. 

The node loadtest command starts load testing for an existing devnet cluster. If the cluster does 
not have an existing load test host, the command creates a separate cloud server and builds the load 
test binary based on the provided load test Git Repo URL and load test binary build command. 

The command will then run the load test binary based on the provided load test run command.

**Usage:**
```bash
avalanche node loadtest start [subcommand] [flags]
```

**Flags:**

```bash
--authorize-access authorize    CLI to create cloud resources
--aws create                    loadtest node in AWS cloud
--aws-profile string            aws profile to use (default "default")
--gcp create                    loadtest in GCP cloud
-h, --help help                 for start
--load-test-branch string       load test branch or commit
--load-test-build-cmd string    command to build load test binary
--load-test-cmd string          command to run load test
--load-test-repo string         load test repo url to use
--node-type string              cloud instance type for loadtest script
--region string                 create load test node in a given region
--ssh-agent-identity string     use given ssh identity(only for ssh agent). If not set, default will be used
--use-ssh-agent use             ssh agent(ex: Yubikey) for ssh auth
--config string                 config file (default is $HOME/.avalanche-cli/config.json)
--log-level string              log level for the application (default "ERROR")
--skip-update-check skip        check for new versions
```

<a id="avalanche-node-loadtest-stop"></a>
#### loadtest stop

(ALPHA Warning) This command is currently in experimental mode. 

The node loadtest stop command stops load testing for an existing devnet cluster and terminates the 
separate cloud server created to host the load test.

**Usage:**
```bash
avalanche node loadtest stop [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help             for stop
--load-test strings         stop specified load test node(s). Use comma to separate multiple load test instance names
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-node-local"></a>
### local

(ALPHA Warning) This command is currently in experimental mode.

The node local command suite provides a collection of commands related to local nodes

**Usage:**
```bash
avalanche node local [subcommand] [flags]
```

**Subcommands:**

- [`destroy`](#avalanche-node-local-destroy): Cleanup local node.
- [`start`](#avalanche-node-local-start): (ALPHA Warning) This command is currently in experimental mode. 

The node local start command sets up a validator on a local server. 
The validator will be validating the Avalanche Primary Network and Subnet 
of your choice. By default, the command runs an interactive wizard. It 
walks you through all the steps you need to set up a validator.
Once this command is completed, you will have to wait for the validator
to finish bootstrapping on the primary network before running further
commands on it, e.g. validating a Subnet. You can check the bootstrapping
status by running avalanche node status local
- [`status`](#avalanche-node-local-status): Get status of local node.
- [`stop`](#avalanche-node-local-stop): Stop local node.
- [`track`](#avalanche-node-local-track): (ALPHA Warning) make the local node at the cluster to track given blockchain

**Flags:**

```bash
-h, --help help             for local
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-node-local-destroy"></a>
#### local destroy

Cleanup local node.

**Usage:**
```bash
avalanche node local destroy [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help             for destroy
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-node-local-start"></a>
#### local start

(ALPHA Warning) This command is currently in experimental mode. 

The node local start command sets up a validator on a local server. 
The validator will be validating the Avalanche Primary Network and Subnet 
of your choice. By default, the command runs an interactive wizard. It 
walks you through all the steps you need to set up a validator.
Once this command is completed, you will have to wait for the validator
to finish bootstrapping on the primary network before running further
commands on it, e.g. validating a Subnet. You can check the bootstrapping
status by running avalanche node status local

**Usage:**
```bash
avalanche node local start [subcommand] [flags]
```

**Flags:**

```bash
--avalanchego-path string                           use this avalanchego binary path
--bootstrap-id stringArray                          nodeIDs of bootstrap nodes
--bootstrap-ip stringArray                          IP:port pairs of bootstrap nodes
--cluster string                                    operate on the given cluster
--custom-avalanchego-version string                 install given avalanchego version on node/s
--devnet operate                                    on a devnet network
--endpoint string                                   use the given endpoint for network operations
-f, --fuji testnet                                  operate on fuji (alias to testnet
--genesis string                                    path to genesis file
-h, --help help                                     for start
--latest-avalanchego-pre-release-version install    latest avalanchego pre-release version on node/s (default true)
--latest-avalanchego-version install                latest avalanchego release version on node/s
-l, --local operate                                 on a local network
-m, --mainnet operate                               on mainnet
--node-config string                                path to common avalanchego config settings for all nodes
--num-nodes uint32                                  number of nodes to start (default 1)
--partial-sync primary                              network partial sync (default true)
--staking-cert-key-path string                      path to provided staking cert key for node
--staking-signer-key-path string                    path to provided staking signer key for node
--staking-tls-key-path string                       path to provided staking tls key for node
-t, --testnet fuji                                  operate on testnet (alias to fuji)
--upgrade string                                    path to upgrade file
--config string                                     config file (default is $HOME/.avalanche-cli/config.json)
--log-level string                                  log level for the application (default "ERROR")
--skip-update-check skip                            check for new versions
```

<a id="avalanche-node-local-status"></a>
#### local status

Get status of local node.

**Usage:**
```bash
avalanche node local status [subcommand] [flags]
```

**Flags:**

```bash
--blockchain string         specify the blockchain the node is syncing with
-h, --help help             for status
--subnet string             specify the blockchain the node is syncing with
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-node-local-stop"></a>
#### local stop

Stop local node.

**Usage:**
```bash
avalanche node local stop [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help             for stop
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-node-local-track"></a>
#### local track

(ALPHA Warning) make the local node at the cluster to track given blockchain

**Usage:**
```bash
avalanche node local track [subcommand] [flags]
```

**Flags:**

```bash
--avalanchego-path string                           use this avalanchego binary path
--custom-avalanchego-version string                 install given avalanchego version on node/s
-h, --help help                                     for track
--latest-avalanchego-pre-release-version install    latest avalanchego pre-release version on node/s (default true)
--latest-avalanchego-version install                latest avalanchego release version on node/s
--config string                                     config file (default is $HOME/.avalanche-cli/config.json)
--log-level string                                  log level for the application (default "ERROR")
--skip-update-check skip                            check for new versions
```

<a id="avalanche-node-refresh-ips"></a>
### refresh-ips

(ALPHA Warning) This command is currently in experimental mode.

The node refresh-ips command obtains the current IP for all nodes with dynamic IPs in the cluster,
and updates the local node information used by CLI commands.

**Usage:**
```bash
avalanche node refresh-ips [subcommand] [flags]
```

**Flags:**

```bash
--aws-profile string        aws profile to use (default "default")
-h, --help help             for refresh-ips
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-node-resize"></a>
### resize

(ALPHA Warning) This command is currently in experimental mode.

The node resize command can change the amount of CPU, memory and disk space available for the cluster nodes.

**Usage:**
```bash
avalanche node resize [subcommand] [flags]
```

**Flags:**

```bash
--aws-profile string        aws profile to use (default "default")
--disk-size string          Disk size to resize in Gb (e.g. 1000Gb)
-h, --help help             for resize
--node-type string          Node type to resize (e.g. t3.2xlarge)
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-node-scp"></a>
### scp

(ALPHA Warning) This command is currently in experimental mode.

The node scp command securely copies files to and from nodes. Remote source or destionation can be specified using the following format:
[clusterName|nodeID|instanceID|IP]:/path/to/file. Regular expressions are supported for the source files like /tmp/*.txt.
File transfer to the nodes are parallelized. IF source or destination is cluster, the other should be a local file path. 
If both destinations are remote, they must be nodes for the same cluster and not clusters themselves.
For example:
$ avalanche node scp [cluster1|node1]:/tmp/file.txt /tmp/file.txt
$ avalanche node scp /tmp/file.txt [cluster1|NodeID-XXXX]:/tmp/file.txt
$ avalanche node scp node1:/tmp/file.txt NodeID-XXXX:/tmp/file.txt

**Usage:**
```bash
avalanche node scp [subcommand] [flags]
```

**Flags:**

```bash
--compress use              compression for ssh
-h, --help help             for scp
--recursive copy            directories recursively
--with-loadtest include     loadtest node for scp cluster operations
--with-monitor include      monitoring node for scp cluster operations
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-node-ssh"></a>
### ssh

(ALPHA Warning) This command is currently in experimental mode.

The node ssh command execute a given command [cmd] using ssh on all nodes in the cluster if ClusterName is given.
If no command is given, just prints the ssh command to be used to connect to each node in the cluster.
For provided NodeID or InstanceID or IP, the command [cmd] will be executed on that node.
If no [cmd] is provided for the node, it will open ssh shell there.

**Usage:**
```bash
avalanche node ssh [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help             for ssh
--parallel run              ssh command on all nodes in parallel
--with-loadtest include     loadtest node for ssh cluster operations
--with-monitor include      monitoring node for ssh cluster operations
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-node-status"></a>
### status

(ALPHA Warning) This command is currently in experimental mode.

The node status command gets the bootstrap status of all nodes in a cluster with the Primary Network. 
If no cluster is given, defaults to node list behaviour.

To get the bootstrap status of a node with a Blockchain, use --blockchain flag

**Usage:**
```bash
avalanche node status [subcommand] [flags]
```

**Flags:**

```bash
--blockchain string         specify the blockchain the node is syncing with
-h, --help help             for status
--subnet string             specify the blockchain the node is syncing with
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-node-sync"></a>
### sync

(ALPHA Warning) This command is currently in experimental mode.

The node sync command enables all nodes in a cluster to be bootstrapped to a Blockchain.
You can check the blockchain bootstrap status by calling avalanche node status `clusterName` --blockchain `blockchainName`

**Usage:**
```bash
avalanche node sync [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help             for sync
--no-checks do              not check for bootstrapped/healthy status or rpc compatibility of nodes against subnet
--subnet-aliases strings    subnet alias to be used for RPC calls. defaults to subnet blockchain ID
--validators strings        sync subnet into given comma separated list of validators. defaults to all cluster nodes
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-node-update"></a>
### update

(ALPHA Warning) This command is currently in experimental mode.

The node update command suite provides a collection of commands for nodes to update
their avalanchego or VM config.

You can check the status after update by calling avalanche node status

**Usage:**
```bash
avalanche node update [subcommand] [flags]
```

**Subcommands:**

- [`subnet`](#avalanche-node-update-subnet): (ALPHA Warning) This command is currently in experimental mode.

The node update subnet command updates all nodes in a cluster with latest Subnet configuration and VM for custom VM.
You can check the updated subnet bootstrap status by calling avalanche node status `clusterName` --subnet `subnetName`

**Flags:**

```bash
-h, --help help             for update
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-node-update-subnet"></a>
#### update subnet

(ALPHA Warning) This command is currently in experimental mode.

The node update subnet command updates all nodes in a cluster with latest Subnet configuration and VM for custom VM.
You can check the updated subnet bootstrap status by calling avalanche node status `clusterName` --subnet `subnetName`

**Usage:**
```bash
avalanche node update subnet [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help             for subnet
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-node-upgrade"></a>
### upgrade

(ALPHA Warning) This command is currently in experimental mode.

The node update command suite provides a collection of commands for nodes to update
their avalanchego or VM version.

You can check the status after upgrade by calling avalanche node status

**Usage:**
```bash
avalanche node upgrade [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help             for upgrade
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-node-validate"></a>
### validate

(ALPHA Warning) This command is currently in experimental mode.

The node validate command suite provides a collection of commands for nodes to join
the Primary Network and Subnets as validators.
If any of the commands is run before the nodes are bootstrapped on the Primary Network, the command 
will fail. You can check the bootstrap status by calling avalanche node status `clusterName`

**Usage:**
```bash
avalanche node validate [subcommand] [flags]
```

**Subcommands:**

- [`primary`](#avalanche-node-validate-primary): (ALPHA Warning) This command is currently in experimental mode.

The node validate primary command enables all nodes in a cluster to be validators of Primary
Network.
- [`subnet`](#avalanche-node-validate-subnet): (ALPHA Warning) This command is currently in experimental mode.

The node validate subnet command enables all nodes in a cluster to be validators of a Subnet.
If the command is run before the nodes are Primary Network validators, the command will first
make the nodes Primary Network validators before making them Subnet validators. 
If The command is run before the nodes are bootstrapped on the Primary Network, the command will fail. 
You can check the bootstrap status by calling avalanche node status `clusterName`
If The command is run before the nodes are synced to the subnet, the command will fail.
You can check the subnet sync status by calling avalanche node status `clusterName` --subnet `subnetName`

**Flags:**

```bash
-h, --help help             for validate
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-node-validate-primary"></a>
#### validate primary

(ALPHA Warning) This command is currently in experimental mode.

The node validate primary command enables all nodes in a cluster to be validators of Primary
Network.

**Usage:**
```bash
avalanche node validate primary [subcommand] [flags]
```

**Flags:**

```bash
-e, --ewoq use               ewoq key [fuji/devnet only]
-h, --help help              for primary
-k, --key string             select the key to use [fuji only]
-g, --ledger use             ledger instead of key (always true on mainnet, defaults to false on fuji/devnet)
--ledger-addrs strings       use the given ledger addresses
--stake-amount uint          how many AVAX to stake in the validator
--staking-period duration    how long validator validates for after start time
--start-time string          UTC start time when this validator starts validating, in 'YYYY-MM-DD HH:MM:SS' format
--config string              config file (default is $HOME/.avalanche-cli/config.json)
--log-level string           log level for the application (default "ERROR")
--skip-update-check skip     check for new versions
```

<a id="avalanche-node-validate-subnet"></a>
#### validate subnet

(ALPHA Warning) This command is currently in experimental mode.

The node validate subnet command enables all nodes in a cluster to be validators of a Subnet.
If the command is run before the nodes are Primary Network validators, the command will first
make the nodes Primary Network validators before making them Subnet validators. 
If The command is run before the nodes are bootstrapped on the Primary Network, the command will fail. 
You can check the bootstrap status by calling avalanche node status `clusterName`
If The command is run before the nodes are synced to the subnet, the command will fail.
You can check the subnet sync status by calling avalanche node status `clusterName` --subnet `subnetName`

**Usage:**
```bash
avalanche node validate subnet [subcommand] [flags]
```

**Flags:**

```bash
--default-validator-params use    default weight/start/duration params for subnet validator
-e, --ewoq use                    ewoq key [fuji/devnet only]
-h, --help help                   for subnet
-k, --key string                  select the key to use [fuji/devnet only]
-g, --ledger use                  ledger instead of key (always true on mainnet, defaults to false on fuji/devnet)
--ledger-addrs strings            use the given ledger addresses
--no-checks do                    not check for bootstrapped status or healthy status
--no-validation-checks do         not check if subnet is already synced or validated (default true)
--stake-amount uint               how many AVAX to stake in the validator
--staking-period duration         how long validator validates for after start time
--start-time string               UTC start time when this validator starts validating, in 'YYYY-MM-DD HH:MM:SS' format
--validators strings              validate subnet for the given comma separated list of validators. defaults to all cluster nodes
--config string                   config file (default is $HOME/.avalanche-cli/config.json)
--log-level string                log level for the application (default "ERROR")
--skip-update-check skip          check for new versions
```

<a id="avalanche-node-whitelist"></a>
### whitelist

(ALPHA Warning) The whitelist command suite provides a collection of tools for granting access to the cluster.

	Command adds IP if --ip params provided to cloud security access rules allowing it to access all nodes in the cluster via ssh or http.
	It also command adds SSH public key to all nodes in the cluster if --ssh params is there.
	If no params provided it detects current user IP automaticaly and whitelists it

**Usage:**
```bash
avalanche node whitelist [subcommand] [flags]
```

**Flags:**

```bash
-y, --current-ip whitelist    current host ip
-h, --help help               for whitelist
--ip string                   ip address to whitelist
--ssh string                  ssh public key to whitelist
--config string               config file (default is $HOME/.avalanche-cli/config.json)
--log-level string            log level for the application (default "ERROR")
--skip-update-check skip      check for new versions
```

<a id="avalanche-primary"></a>
## avalanche primary

The primary command suite provides a collection of tools for interacting with the
Primary Network

**Usage:**
```bash
avalanche primary [subcommand] [flags]
```

**Subcommands:**

- [`addValidator`](#avalanche-primary-addvalidator): The primary addValidator command adds a node as a validator 
in the Primary Network
- [`describe`](#avalanche-primary-describe): The subnet describe command prints details of the primary network configuration to the console.

**Flags:**

```bash
-h, --help help             for primary
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-primary-addvalidator"></a>
### addValidator

The primary addValidator command adds a node as a validator 
in the Primary Network

**Usage:**
```bash
avalanche primary addValidator [subcommand] [flags]
```

**Flags:**

```bash
--cluster string                operate on the given cluster
--delegation-fee uint32         set the delegation fee (20 000 is equivalent to 2%)
--devnet operate                on a devnet network
--endpoint string               use the given endpoint for network operations
-f, --fuji testnet              operate on fuji (alias to testnet
-h, --help help                 for addValidator
-k, --key string                select the key to use [fuji only]
-g, --ledger use                ledger instead of key (always true on mainnet, defaults to false on fuji)
--ledger-addrs strings          use the given ledger addresses
-m, --mainnet operate           on mainnet
--nodeID string                 set the NodeID of the validator to add
--proof-of-possession string    set the BLS proof of possession of the validator to add
--public-key string             set the BLS public key of the validator to add
--staking-period duration       how long this validator will be staking
--start-time string             UTC start time when this validator starts validating, in 'YYYY-MM-DD HH:MM:SS' format
-t, --testnet fuji              operate on testnet (alias to fuji)
--weight uint                   set the staking weight of the validator to add
--config string                 config file (default is $HOME/.avalanche-cli/config.json)
--log-level string              log level for the application (default "ERROR")
--skip-update-check skip        check for new versions
```

<a id="avalanche-primary-describe"></a>
### describe

The subnet describe command prints details of the primary network configuration to the console.

**Usage:**
```bash
avalanche primary describe [subcommand] [flags]
```

**Flags:**

```bash
--cluster string            operate on the given cluster
-h, --help help             for describe
-l, --local operate         on a local network
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-subnet"></a>
## avalanche subnet

The subnet command suite provides a collection of tools for developing
and deploying Blockchains.

To get started, use the subnet create command wizard to walk through the
configuration of your very first Blockchain. Then, go ahead and deploy it
with the subnet deploy command. You can use the rest of the commands to
manage your Blockchain configurations and live deployments.

Deprecation notice: use 'avalanche blockchain'

**Usage:**
```bash
avalanche subnet [subcommand] [flags]
```

**Subcommands:**

- [`addValidator`](#avalanche-subnet-addvalidator): The blockchain addValidator command adds a node as a validator to
an L1 of the user provided deployed network. If the network is proof of 
authority, the owner of the validator manager contract must sign the 
transaction. If the network is proof of stake, the node must stake the L1's
staking token. Both processes will issue a RegisterL1ValidatorTx on the P-Chain.

This command currently only works on Blockchains deployed to either the Fuji
Testnet or Mainnet.
- [`changeOwner`](#avalanche-subnet-changeowner): The blockchain changeOwner changes the owner of the subnet of the deployed Blockchain.
- [`changeWeight`](#avalanche-subnet-changeweight): The blockchain changeWeight command changes the weight of a Subnet Validator.

The Subnet has to be a Proof of Authority Subnet-Only Validator Subnet.
- [`configure`](#avalanche-subnet-configure): AvalancheGo nodes support several different configuration files. Subnets have their own
Subnet config which applies to all chains/VMs in the Subnet. Each chain within the Subnet
can have its own chain config. A chain can also have special requirements for the AvalancheGo node 
configuration itself. This command allows you to set all those files.
- [`create`](#avalanche-subnet-create): The blockchain create command builds a new genesis file to configure your Blockchain.
By default, the command runs an interactive wizard. It walks you through
all the steps you need to create your first Blockchain.

The tool supports deploying Subnet-EVM, and custom VMs. You
can create a custom, user-generated genesis with a custom VM by providing
the path to your genesis and VM binaries with the --genesis and --vm flags.

By default, running the command with a blockchainName that already exists
causes the command to fail. If you'd like to overwrite an existing
configuration, pass the -f flag.
- [`delete`](#avalanche-subnet-delete): The blockchain delete command deletes an existing blockchain configuration.
- [`deploy`](#avalanche-subnet-deploy): The blockchain deploy command deploys your Blockchain configuration locally, to Fuji Testnet, or to Mainnet.

At the end of the call, the command prints the RPC URL you can use to interact with the Subnet.

Avalanche-CLI only supports deploying an individual Blockchain once per network. Subsequent
attempts to deploy the same Blockchain to the same network (local, Fuji, Mainnet) aren't
allowed. If you'd like to redeploy a Blockchain locally for testing, you must first call
avalanche network clean to reset all deployed chain state. Subsequent local deploys
redeploy the chain with fresh state. You can deploy the same Blockchain to multiple networks,
so you can take your locally tested Subnet and deploy it on Fuji or Mainnet.
- [`describe`](#avalanche-subnet-describe): The blockchain describe command prints the details of a Blockchain configuration to the console.
By default, the command prints a summary of the configuration. By providing the --genesis
flag, the command instead prints out the raw genesis file.
- [`export`](#avalanche-subnet-export): The blockchain export command write the details of an existing Blockchain deploy to a file.

The command prompts for an output path. You can also provide one with
the --output flag.
- [`import`](#avalanche-subnet-import): Import blockchain configurations into avalanche-cli.

This command suite supports importing from a file created on another computer,
or importing from blockchains running public networks
(e.g. created manually or with the deprecated subnet-cli)
- [`join`](#avalanche-subnet-join): The subnet join command configures your validator node to begin validating a new Blockchain.

To complete this process, you must have access to the machine running your validator. If the
CLI is running on the same machine as your validator, it can generate or update your node's
config file automatically. Alternatively, the command can print the necessary instructions
to update your node manually. To complete the validation process, the Subnet's admins must add
the NodeID of your validator to the Subnet's allow list by calling addValidator with your
NodeID.

After you update your validator's config, you need to restart your validator manually. If
you provide the --avalanchego-config flag, this command attempts to edit the config file
at that path.

This command currently only supports Blockchains deployed on the Fuji Testnet and Mainnet.
- [`list`](#avalanche-subnet-list): The blockchain list command prints the names of all created Blockchain configurations. Without any flags,
it prints some general, static information about the Blockchain. With the --deployed flag, the command
shows additional information including the VMID, BlockchainID and SubnetID.
- [`publish`](#avalanche-subnet-publish): The blockchain publish command publishes the Blockchain's VM to a repository.
- [`removeValidator`](#avalanche-subnet-removevalidator): The blockchain removeValidator command stops a whitelisted, subnet network validator from
validating your deployed Blockchain.

To remove the validator from the Subnet's allow list, provide the validator's unique NodeID. You can bypass
these prompts by providing the values with flags.
- [`stats`](#avalanche-subnet-stats): The blockchain stats command prints validator statistics for the given Blockchain.
- [`upgrade`](#avalanche-subnet-upgrade): The blockchain upgrade command suite provides a collection of tools for
updating your developmental and deployed Blockchains.
- [`validators`](#avalanche-subnet-validators): The blockchain validators command lists the validators of a blockchain's subnet and provides
several statistics about them.
- [`vmid`](#avalanche-subnet-vmid): The blockchain vmid command prints the virtual machine ID (VMID) for the given Blockchain.

**Flags:**

```bash
-h, --help help             for subnet
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-subnet-addvalidator"></a>
### addValidator

The blockchain addValidator command adds a node as a validator to
an L1 of the user provided deployed network. If the network is proof of 
authority, the owner of the validator manager contract must sign the 
transaction. If the network is proof of stake, the node must stake the L1's
staking token. Both processes will issue a RegisterL1ValidatorTx on the P-Chain.

This command currently only works on Blockchains deployed to either the Fuji
Testnet or Mainnet.

**Usage:**
```bash
avalanche subnet addValidator [subcommand] [flags]
```

**Flags:**

```bash
--aggregator-allow-private-peers allow    the signature aggregator to connect to peers with private IP (default true)
--aggregator-extra-endpoints strings      endpoints for extra nodes that are needed in signature aggregation
--aggregator-log-level string             log level to use with signature aggregator (default "Off")
--balance uint                            set the AVAX balance of the validator that will be used for continuous fee on P-Chain
--blockchain-genesis-key use              genesis allocated key to pay fees for completing the validator's registration (blockchain gas token)
--blockchain-key string                   CLI stored key to use to pay fees for completing the validator's registration (blockchain gas token)
--blockchain-private-key string           private key to use to pay fees for completing the validator's registration (blockchain gas token)
--bls-proof-of-possession string          set the BLS proof of possession of the validator to add
--bls-public-key string                   set the BLS public key of the validator to add
--cluster string                          operate on the given cluster
--create-local-validator create           additional local validator and add it to existing running local node
--default-duration                        (for Subnets, not L1s) set duration so as to validate until primary validator ends its period
--default-start-time                      (for Subnets, not L1s) use default start time for subnet validator (5 minutes later for fuji & mainnet, 30 seconds later for devnet)
--default-validator-params                (for Subnets, not L1s) use default weight/start/duration params for subnet validator
--delegation-fee uint16                   (PoS only) delegation fee (in bips) (default 100)
--devnet operate                          on a devnet network
--disable-owner string                    P-Chain address that will able to disable the validator with a P-Chain transaction
--endpoint string                         use the given endpoint for network operations
-e, --ewoq use                            ewoq key [fuji/devnet only]
-f, --fuji testnet                        operate on fuji (alias to testnet
-h, --help help                           for addValidator
-k, --key string                          select the key to use [fuji/devnet only]
-g, --ledger use                          ledger instead of key (always true on mainnet, defaults to false on fuji/devnet)
--ledger-addrs strings                    use the given ledger addresses
-l, --local operate                       on a local network
-m, --mainnet operate                     on mainnet
--node-endpoint string                    gather node id/bls from publicly available avalanchego apis on the given endpoint
--node-id string                          node-id of the validator to add
--output-tx-path string                   (for Subnets, not L1s) file path of the add validator tx
--partial-sync set                        primary network partial sync for new validators (default true)
--remaining-balance-owner string          P-Chain address that will receive any leftover AVAX from the validator when it is removed from Subnet
--rpc string                              connect to validator manager at the given rpc endpoint
--stake-amount uint                       (PoS only) amount of tokens to stake
--staking-period duration                 how long this validator will be staking
--start-time string                       (for Subnets, not L1s) UTC start time when this validator starts validating, in 'YYYY-MM-DD HH:MM:SS' format
--subnet-auth-keys strings                (for Subnets, not L1s) control keys that will be used to authenticate add validator tx
-t, --testnet fuji                        operate on testnet (alias to fuji)
--wait-for-tx-acceptance                  (for Subnets, not L1s) just issue the add validator tx, without waiting for its acceptance (default true)
--weight uint                             set the staking weight of the validator to add (default 20)
--config string                           config file (default is $HOME/.avalanche-cli/config.json)
--log-level string                        log level for the application (default "ERROR")
--skip-update-check skip                  check for new versions
```

<a id="avalanche-subnet-changeowner"></a>
### changeOwner

The blockchain changeOwner changes the owner of the subnet of the deployed Blockchain.

**Usage:**
```bash
avalanche subnet changeOwner [subcommand] [flags]
```

**Flags:**

```bash
--cluster string              operate on the given cluster
--control-keys strings        addresses that may make subnet changes
--devnet operate              on a devnet network
--endpoint string             use the given endpoint for network operations
-e, --ewoq use                ewoq key [fuji/devnet]
-f, --fuji testnet            operate on fuji (alias to testnet
-h, --help help               for changeOwner
-k, --key string              select the key to use [fuji/devnet]
-g, --ledger use              ledger instead of key (always true on mainnet, defaults to false on fuji/devnet)
--ledger-addrs strings        use the given ledger addresses
-l, --local operate           on a local network
-m, --mainnet operate         on mainnet
--output-tx-path string       file path of the transfer subnet ownership tx
-s, --same-control-key use    the fee-paying key as control key
--subnet-auth-keys strings    control keys that will be used to authenticate transfer subnet ownership tx
-t, --testnet fuji            operate on testnet (alias to fuji)
--threshold uint32            required number of control key signatures to make subnet changes
--config string               config file (default is $HOME/.avalanche-cli/config.json)
--log-level string            log level for the application (default "ERROR")
--skip-update-check skip      check for new versions
```

<a id="avalanche-subnet-changeweight"></a>
### changeWeight

The blockchain changeWeight command changes the weight of a Subnet Validator.

The Subnet has to be a Proof of Authority Subnet-Only Validator Subnet.

**Usage:**
```bash
avalanche subnet changeWeight [subcommand] [flags]
```

**Flags:**

```bash
--cluster string            operate on the given cluster
--devnet operate            on a devnet network
--endpoint string           use the given endpoint for network operations
-e, --ewoq use              ewoq key [fuji/devnet only]
-f, --fuji testnet          operate on fuji (alias to testnet
-h, --help help             for changeWeight
-k, --key string            select the key to use [fuji/devnet only]
-g, --ledger use            ledger instead of key (always true on mainnet, defaults to false on fuji/devnet)
--ledger-addrs strings      use the given ledger addresses
-l, --local operate         on a local network
-m, --mainnet operate       on mainnet
--node-id string            node-id of the validator
-t, --testnet fuji          operate on testnet (alias to fuji)
--weight uint               set the new staking weight of the validator (default 20)
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-subnet-configure"></a>
### configure

AvalancheGo nodes support several different configuration files. Subnets have their own
Subnet config which applies to all chains/VMs in the Subnet. Each chain within the Subnet
can have its own chain config. A chain can also have special requirements for the AvalancheGo node 
configuration itself. This command allows you to set all those files.

**Usage:**
```bash
avalanche subnet configure [subcommand] [flags]
```

**Flags:**

```bash
--chain-config string             path to the chain configuration
-h, --help help                   for configure
--node-config string              path to avalanchego node configuration
--per-node-chain-config string    path to per node chain configuration for local network
--subnet-config string            path to the subnet configuration
--config string                   config file (default is $HOME/.avalanche-cli/config.json)
--log-level string                log level for the application (default "ERROR")
--skip-update-check skip          check for new versions
```

<a id="avalanche-subnet-create"></a>
### create

The blockchain create command builds a new genesis file to configure your Blockchain.
By default, the command runs an interactive wizard. It walks you through
all the steps you need to create your first Blockchain.

The tool supports deploying Subnet-EVM, and custom VMs. You
can create a custom, user-generated genesis with a custom VM by providing
the path to your genesis and VM binaries with the --genesis and --vm flags.

By default, running the command with a blockchainName that already exists
causes the command to fail. If you'd like to overwrite an existing
configuration, pass the -f flag.

**Usage:**
```bash
avalanche subnet create [subcommand] [flags]
```

**Flags:**

```bash
--custom use                        a custom VM template
--custom-vm-branch string           custom vm branch or commit
--custom-vm-build-script string     custom vm build-script
--custom-vm-path string             file path of custom vm to use
--custom-vm-repo-url string         custom vm repository url
--debug enable                      blockchain debugging (default true)
--evm use                           the Subnet-EVM as the base template
--evm-chain-id uint                 chain ID to use with Subnet-EVM
--evm-defaults deprecation          notice: use '--production-defaults'
--evm-token string                  token symbol to use with Subnet-EVM
--external-gas-token use            a gas token from another blockchain
-f, --force overwrite               the existing configuration if one exists
--from-github-repo generate         custom VM binary from github repository
--genesis string                    file path of genesis to use
-h, --help help                     for create
--icm interoperate                  with other blockchains using ICM
--icm-registry-at-genesis setup     ICM registry smart contract on genesis [experimental]
--latest use                        latest Subnet-EVM released version, takes precedence over --vm-version
--pre-release use                   latest Subnet-EVM pre-released version, takes precedence over --vm-version
--production-defaults use           default production settings for your blockchain
--proof-of-authority use            proof of authority(PoA) for validator management
--proof-of-stake use                proof of stake(PoS) for validator management
--proxy-contract-owner string       EVM address that controls ProxyAdmin for TransparentProxy of ValidatorManager contract
--reward-basis-points uint          (PoS only) reward basis points for PoS Reward Calculator (default 100)
--sovereign set                     to false if creating non-sovereign blockchain (default true)
--teleporter interoperate           with other blockchains using ICM
--test-defaults use                 default test settings for your blockchain
--validator-manager-owner string    EVM address that controls Validator Manager Owner
--vm string                         file path of custom vm to use. alias to custom-vm-path
--vm-version string                 version of Subnet-EVM template to use
--warp generate                     a vm with warp support (needed for ICM) (default true)
--config string                     config file (default is $HOME/.avalanche-cli/config.json)
--log-level string                  log level for the application (default "ERROR")
--skip-update-check skip            check for new versions
```

<a id="avalanche-subnet-delete"></a>
### delete

The blockchain delete command deletes an existing blockchain configuration.

**Usage:**
```bash
avalanche subnet delete [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help             for delete
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-subnet-deploy"></a>
### deploy

The blockchain deploy command deploys your Blockchain configuration locally, to Fuji Testnet, or to Mainnet.

At the end of the call, the command prints the RPC URL you can use to interact with the Subnet.

Avalanche-CLI only supports deploying an individual Blockchain once per network. Subsequent
attempts to deploy the same Blockchain to the same network (local, Fuji, Mainnet) aren't
allowed. If you'd like to redeploy a Blockchain locally for testing, you must first call
avalanche network clean to reset all deployed chain state. Subsequent local deploys
redeploy the chain with fresh state. You can deploy the same Blockchain to multiple networks,
so you can take your locally tested Subnet and deploy it on Fuji or Mainnet.

**Usage:**
```bash
avalanche subnet deploy [subcommand] [flags]
```

**Flags:**

```bash
--aggregator-allow-private-peers allow                 the signature aggregator to connect to peers with private IP (default true)
--aggregator-extra-endpoints strings                   endpoints for extra nodes that are needed in signature aggregation
--aggregator-log-level string                          log level to use with signature aggregator (default "Off")
--avalanchego-path string                              use this avalanchego binary path
--avalanchego-version string                           use this version of avalanchego (ex: v1.17.12) (default "latest-prerelease")
--balance float                                        set the AVAX balance of each bootstrap validator that will be used for continuous fee on P-Chain (default 0.1)
--blockchain-genesis-key use                           genesis allocated key to fund validator manager initialization
--blockchain-key string                                CLI stored key to use to fund validator manager initialization
--blockchain-private-key string                        private key to use to fund validator manager initialization
--bootstrap-endpoints strings                          take validator node info from the given endpoints
--bootstrap-filepath string                            JSON file path that provides details about bootstrap validators, leave Node-ID and BLS values empty if using --generate-node-id=true
--cchain-funding-key string                            key to be used to fund relayer account on cchain
--cchain-icm-key string                                key to be used to pay for ICM deploys on C-Chain
--change-owner-address string                          address that will receive change if node is no longer L1 validator
--cluster string                                       operate on the given cluster
--control-keys strings                                 addresses that may make subnet changes
--convert-only avoid                                   node track, restart and poa manager setup
--devnet operate                                       on a devnet network
--endpoint string                                      use the given endpoint for network operations
-e, --ewoq use                                         ewoq key [fuji/devnet deploy only]
-f, --fuji testnet                                     operate on fuji (alias to testnet
--generate-node-id whether                             to create new node id for bootstrap validators (Node-ID and BLS values in bootstrap JSON file will be overridden if --bootstrap-filepath flag is used)
-h, --help help                                        for deploy
--icm-key string                                       key to be used to pay for ICM deploys (default "cli-teleporter-deployer")
--icm-version string                                   ICM version to deploy (default "latest")
-k, --key string                                       select the key to use [fuji/devnet deploy only]
-g, --ledger use                                       ledger instead of key (always true on mainnet, defaults to false on fuji/devnet)
--ledger-addrs strings                                 use the given ledger addresses
-l, --local operate                                    on a local network
-m, --mainnet operate                                  on mainnet
--mainnet-chain-id uint32                              use different ChainID for mainnet deployment
--noicm skip                                           automatic ICM deploy
--num-bootstrap-validators int                         (only if --generate-node-id is true) number of bootstrap validators to set up in sovereign L1 validator)
--num-local-nodes int                                  number of nodes to be created on local machine
--num-nodes uint32                                     number of nodes to be created on local network deploy (default 2)
--output-tx-path string                                file path of the blockchain creation tx
--partial-sync set                                     primary network partial sync for new validators (default true)
--pos-maximum-stake-amount uint                        maximum stake amount (default 1000)
--pos-maximum-stake-multiplier uint8                   maximum stake multiplier (default 1)
--pos-minimum-delegation-fee uint16                    minimum delegation fee (default 1)
--pos-minimum-stake-amount uint                        minimum stake amount (default 1)
--pos-minimum-stake-duration uint                      minimum stake duration (default 100)
--pos-weight-to-value-factor uint                      weight to value factor (default 1)
--relay-cchain relay                                   C-Chain as source and destination (default true)
--relayer-allow-private-ips allow                      relayer to connec to private ips (default true)
--relayer-amount float                                 automatically fund relayer fee payments with the given amount
--relayer-key string                                   key to be used by default both for rewards and to pay fees
--relayer-log-level string                             log level to be used for relayer logs (default "info")
--relayer-path string                                  relayer binary to use
--relayer-version string                               relayer version to deploy (default "latest-prerelease")
-s, --same-control-key use                             the fee-paying key as control key
--skip-icm-deploy skip                                 automatic ICM deploy
--skip-local-teleporter skip                           automatic ICM deploy on local networks [to be deprecated]
--skip-relayer skip                                    relayer deploy
--skip-teleporter-deploy skip                          automatic ICM deploy
--subnet-auth-keys strings                             control keys that will be used to authenticate chain creation
-u, --subnet-id string                                 do not create a subnet, deploy the blockchain into the given subnet id
--subnet-only only                                     create a subnet
--teleporter-messenger-contract-address-path string    path to an ICM Messenger contract address file
--teleporter-messenger-deployer-address-path string    path to an ICM Messenger deployer address file
--teleporter-messenger-deployer-tx-path string         path to an ICM Messenger deployer tx file
--teleporter-registry-bytecode-path string             path to an ICM Registry bytecode file
--teleporter-version string                            ICM version to deploy (default "latest")
-t, --testnet fuji                                     operate on testnet (alias to fuji)
--threshold uint32                                     required number of control key signatures to make subnet changes
--use-local-machine use                                local machine as a blockchain validator
--config string                                        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string                                     log level for the application (default "ERROR")
--skip-update-check skip                               check for new versions
```

<a id="avalanche-subnet-describe"></a>
### describe

The blockchain describe command prints the details of a Blockchain configuration to the console.
By default, the command prints a summary of the configuration. By providing the --genesis
flag, the command instead prints out the raw genesis file.

**Usage:**
```bash
avalanche subnet describe [subcommand] [flags]
```

**Flags:**

```bash
-g, --genesis Print         the genesis to the console directly instead of the summary
-h, --help help             for describe
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-subnet-export"></a>
### export

The blockchain export command write the details of an existing Blockchain deploy to a file.

The command prompts for an output path. You can also provide one with
the --output flag.

**Usage:**
```bash
avalanche subnet export [subcommand] [flags]
```

**Flags:**

```bash
--custom-vm-branch string          custom vm branch
--custom-vm-build-script string    custom vm build-script
--custom-vm-repo-url string        custom vm repository url
-h, --help help                    for export
-o, --output string                write the export data to the provided file path
--config string                    config file (default is $HOME/.avalanche-cli/config.json)
--log-level string                 log level for the application (default "ERROR")
--skip-update-check skip           check for new versions
```

<a id="avalanche-subnet-import"></a>
### import

Import blockchain configurations into avalanche-cli.

This command suite supports importing from a file created on another computer,
or importing from blockchains running public networks
(e.g. created manually or with the deprecated subnet-cli)

**Usage:**
```bash
avalanche subnet import [subcommand] [flags]
```

**Subcommands:**

- [`file`](#avalanche-subnet-import-file): The blockchain import command will import a blockchain configuration from a file or a git repository.

To import from a file, you can optionally provide the path as a command-line argument.
Alternatively, running the command without any arguments triggers an interactive wizard.
To import from a repository, go through the wizard. By default, an imported Blockchain doesn't 
overwrite an existing Blockchain with the same name. To allow overwrites, provide the --force
flag.
- [`public`](#avalanche-subnet-import-public): The blockchain import public command imports a Blockchain configuration from a running network.

By default, an imported Blockchain
doesn't overwrite an existing Blockchain with the same name. To allow overwrites, provide the --force
flag.

**Flags:**

```bash
-h, --help help             for import
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-subnet-import-file"></a>
#### import file

The blockchain import command will import a blockchain configuration from a file or a git repository.

To import from a file, you can optionally provide the path as a command-line argument.
Alternatively, running the command without any arguments triggers an interactive wizard.
To import from a repository, go through the wizard. By default, an imported Blockchain doesn't 
overwrite an existing Blockchain with the same name. To allow overwrites, provide the --force
flag.

**Usage:**
```bash
avalanche subnet import file [subcommand] [flags]
```

**Flags:**

```bash
--branch string             the repo branch to use if downloading a new repo
-f, --force overwrite       the existing configuration if one exists
-h, --help help             for file
--repo string               the repo to import (ex: ava-labs/avalanche-plugins-core) or url to download the repo from
--subnet string             the subnet configuration to import from the provided repo
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-subnet-import-public"></a>
#### import public

The blockchain import public command imports a Blockchain configuration from a running network.

By default, an imported Blockchain
doesn't overwrite an existing Blockchain with the same name. To allow overwrites, provide the --force
flag.

**Usage:**
```bash
avalanche subnet import public [subcommand] [flags]
```

**Flags:**

```bash
--blockchain-id string      the blockchain ID
--cluster string            operate on the given cluster
--custom use                a custom VM template
--devnet operate            on a devnet network
--endpoint string           use the given endpoint for network operations
--evm import                a subnet-evm
--force overwrite           the existing configuration if one exists
-f, --fuji testnet          operate on fuji (alias to testnet
-h, --help help             for public
-l, --local operate         on a local network
-m, --mainnet operate       on mainnet
--node-url string           [optional] URL of an already running subnet validator
-t, --testnet fuji          operate on testnet (alias to fuji)
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-subnet-join"></a>
### join

The subnet join command configures your validator node to begin validating a new Blockchain.

To complete this process, you must have access to the machine running your validator. If the
CLI is running on the same machine as your validator, it can generate or update your node's
config file automatically. Alternatively, the command can print the necessary instructions
to update your node manually. To complete the validation process, the Subnet's admins must add
the NodeID of your validator to the Subnet's allow list by calling addValidator with your
NodeID.

After you update your validator's config, you need to restart your validator manually. If
you provide the --avalanchego-config flag, this command attempts to edit the config file
at that path.

This command currently only supports Blockchains deployed on the Fuji Testnet and Mainnet.

**Usage:**
```bash
avalanche subnet join [subcommand] [flags]
```

**Flags:**

```bash
--avalanchego-config string    file path of the avalanchego config file
--cluster string               operate on the given cluster
--data-dir string              path of avalanchego's data dir directory
--devnet operate               on a devnet network
--endpoint string              use the given endpoint for network operations
--force-write if               true, skip to prompt to overwrite the config file
-f, --fuji testnet             operate on fuji (alias to testnet
-h, --help help                for join
-k, --key string               select the key to use [fuji only]
-g, --ledger use               ledger instead of key (always true on mainnet, defaults to false on fuji)
--ledger-addrs strings         use the given ledger addresses
-l, --local operate            on a local network
-m, --mainnet operate          on mainnet
--node-id string               set the NodeID of the validator to check
--plugin-dir string            file path of avalanchego's plugin directory
--print if                     true, print the manual config without prompting
--stake-amount uint            amount of tokens to stake on validator
--staking-period duration      how long validator validates for after start time
--start-time string            start time that validator starts validating
-t, --testnet fuji             operate on testnet (alias to fuji)
--config string                config file (default is $HOME/.avalanche-cli/config.json)
--log-level string             log level for the application (default "ERROR")
--skip-update-check skip       check for new versions
```

<a id="avalanche-subnet-list"></a>
### list

The blockchain list command prints the names of all created Blockchain configurations. Without any flags,
it prints some general, static information about the Blockchain. With the --deployed flag, the command
shows additional information including the VMID, BlockchainID and SubnetID.

**Usage:**
```bash
avalanche subnet list [subcommand] [flags]
```

**Flags:**

```bash
--deployed show             additional deploy information
-h, --help help             for list
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-subnet-publish"></a>
### publish

The blockchain publish command publishes the Blockchain's VM to a repository.

**Usage:**
```bash
avalanche subnet publish [subcommand] [flags]
```

**Flags:**

```bash
--alias string               We publish to a remote repo, but identify the repo locally under a user-provided alias (e.g. myrepo).
--force If                   true, ignores if the subnet has been published in the past, and attempts a forced publish.
-h, --help help              for publish
--no-repo-path string        Do not let the tool manage file publishing, but have it only generate the files and put them in the location given by this flag.
--repo-url string            The URL of the repo where we are publishing
--subnet-file-path string    Path to the Subnet description file. If not given, a prompting sequence will be initiated.
--vm-file-path string        Path to the VM description file. If not given, a prompting sequence will be initiated.
--config string              config file (default is $HOME/.avalanche-cli/config.json)
--log-level string           log level for the application (default "ERROR")
--skip-update-check skip     check for new versions
```

<a id="avalanche-subnet-removevalidator"></a>
### removeValidator

The blockchain removeValidator command stops a whitelisted, subnet network validator from
validating your deployed Blockchain.

To remove the validator from the Subnet's allow list, provide the validator's unique NodeID. You can bypass
these prompts by providing the values with flags.

**Usage:**
```bash
avalanche subnet removeValidator [subcommand] [flags]
```

**Flags:**

```bash
--aggregator-allow-private-peers allow    the signature aggregator to connect to peers with private IP (default true)
--aggregator-extra-endpoints strings      endpoints for extra nodes that are needed in signature aggregation
--aggregator-log-level string             log level to use with signature aggregator (default "Off")
--blockchain-genesis-key use              genesis allocated key to pay fees for completing the validator's removal (blockchain gas token)
--blockchain-key string                   CLI stored key to use to pay fees for completing the validator's removal (blockchain gas token)
--blockchain-private-key string           private key to use to pay fees for completing the validator's removal (blockchain gas token)
--cluster string                          operate on the given cluster
--devnet operate                          on a devnet network
--endpoint string                         use the given endpoint for network operations
--force force                             validator removal even if it's not getting rewarded
-f, --fuji testnet                        operate on fuji (alias to testnet
-h, --help help                           for removeValidator
-k, --key string                          select the key to use [fuji deploy only]
-g, --ledger use                          ledger instead of key (always true on mainnet, defaults to false on fuji)
--ledger-addrs strings                    use the given ledger addresses
-l, --local operate                       on a local network
-m, --mainnet operate                     on mainnet
--node-endpoint string                    remove validator that responds to the given endpoint
--node-id string                          node-id of the validator
--output-tx-path string                   (for non-SOV blockchain only) file path of the removeValidator tx
--rpc string                              connect to validator manager at the given rpc endpoint
--subnet-auth-keys strings                (for non-SOV blockchain only) control keys that will be used to authenticate the removeValidator tx
-t, --testnet fuji                        operate on testnet (alias to fuji)
--uptime uint                             validator's uptime in seconds. If not provided, it will be automatically calculated
--config string                           config file (default is $HOME/.avalanche-cli/config.json)
--log-level string                        log level for the application (default "ERROR")
--skip-update-check skip                  check for new versions
```

<a id="avalanche-subnet-stats"></a>
### stats

The blockchain stats command prints validator statistics for the given Blockchain.

**Usage:**
```bash
avalanche subnet stats [subcommand] [flags]
```

**Flags:**

```bash
--cluster string            operate on the given cluster
--devnet operate            on a devnet network
--endpoint string           use the given endpoint for network operations
-f, --fuji testnet          operate on fuji (alias to testnet
-h, --help help             for stats
-l, --local operate         on a local network
-m, --mainnet operate       on mainnet
-t, --testnet fuji          operate on testnet (alias to fuji)
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-subnet-upgrade"></a>
### upgrade

The blockchain upgrade command suite provides a collection of tools for
updating your developmental and deployed Blockchains.

**Usage:**
```bash
avalanche subnet upgrade [subcommand] [flags]
```

**Subcommands:**

- [`apply`](#avalanche-subnet-upgrade-apply): Apply generated upgrade bytes to running Blockchain nodes to trigger a network upgrade.

For public networks (Fuji Testnet or Mainnet), to complete this process,
you must have access to the machine running your validator.
If the CLI is running on the same machine as your validator, it can manipulate your node's
configuration automatically. Alternatively, the command can print the necessary instructions
to upgrade your node manually.

After you update your validator's configuration, you need to restart your validator manually.
If you provide the --avalanchego-chain-config-dir flag, this command attempts to write the upgrade file at that path.
Refer to https://docs.avax.network/nodes/maintain/chain-config-flags#subnet-chain-configs for related documentation.
- [`export`](#avalanche-subnet-upgrade-export): Export the upgrade bytes file to a location of choice on disk
- [`generate`](#avalanche-subnet-upgrade-generate): The blockchain upgrade generate command builds a new upgrade.json file to customize your Blockchain. It
guides the user through the process using an interactive wizard.
- [`import`](#avalanche-subnet-upgrade-import): Import the upgrade bytes file into the local environment
- [`print`](#avalanche-subnet-upgrade-print): Print the upgrade.json file content
- [`vm`](#avalanche-subnet-upgrade-vm): The blockchain upgrade vm command enables the user to upgrade their Blockchain's VM binary. The command
can upgrade both local Blockchains and publicly deployed Blockchains on Fuji and Mainnet.

The command walks the user through an interactive wizard. The user can skip the wizard by providing
command line flags.

**Flags:**

```bash
-h, --help help             for upgrade
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-subnet-upgrade-apply"></a>
#### upgrade apply

Apply generated upgrade bytes to running Blockchain nodes to trigger a network upgrade.

For public networks (Fuji Testnet or Mainnet), to complete this process,
you must have access to the machine running your validator.
If the CLI is running on the same machine as your validator, it can manipulate your node's
configuration automatically. Alternatively, the command can print the necessary instructions
to upgrade your node manually.

After you update your validator's configuration, you need to restart your validator manually.
If you provide the --avalanchego-chain-config-dir flag, this command attempts to write the upgrade file at that path.
Refer to https://docs.avax.network/nodes/maintain/chain-config-flags#subnet-chain-configs for related documentation.

**Usage:**
```bash
avalanche subnet upgrade apply [subcommand] [flags]
```

**Flags:**

```bash
--avalanchego-chain-config-dir string    avalanchego's chain config file directory (default "/Users/owen.wahlgren/.avalanchego/chains")
--config create                          upgrade config for future subnet deployments (same as generate)
--force If                               true, don't prompt for confirmation of timestamps in the past
--fuji fuji                              apply upgrade existing fuji deployment (alias for `testnet`)
-h, --help help                          for apply
--local local                            apply upgrade existing local deployment
--mainnet mainnet                        apply upgrade existing mainnet deployment
--print if                               true, print the manual config without prompting (for public networks only)
--testnet testnet                        apply upgrade existing testnet deployment (alias for `fuji`)
--log-level string                       log level for the application (default "ERROR")
--skip-update-check skip                 check for new versions
```

<a id="avalanche-subnet-upgrade-export"></a>
#### upgrade export

Export the upgrade bytes file to a location of choice on disk

**Usage:**
```bash
avalanche subnet upgrade export [subcommand] [flags]
```

**Flags:**

```bash
--force If                   true, overwrite a possibly existing file without prompting
-h, --help help              for export
--upgrade-filepath string    Export upgrade bytes file to location of choice on disk
--config string              config file (default is $HOME/.avalanche-cli/config.json)
--log-level string           log level for the application (default "ERROR")
--skip-update-check skip     check for new versions
```

<a id="avalanche-subnet-upgrade-generate"></a>
#### upgrade generate

The blockchain upgrade generate command builds a new upgrade.json file to customize your Blockchain. It
guides the user through the process using an interactive wizard.

**Usage:**
```bash
avalanche subnet upgrade generate [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help             for generate
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-subnet-upgrade-import"></a>
#### upgrade import

Import the upgrade bytes file into the local environment

**Usage:**
```bash
avalanche subnet upgrade import [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help              for import
--upgrade-filepath string    Import upgrade bytes file into local environment
--config string              config file (default is $HOME/.avalanche-cli/config.json)
--log-level string           log level for the application (default "ERROR")
--skip-update-check skip     check for new versions
```

<a id="avalanche-subnet-upgrade-print"></a>
#### upgrade print

Print the upgrade.json file content

**Usage:**
```bash
avalanche subnet upgrade print [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help             for print
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-subnet-upgrade-vm"></a>
#### upgrade vm

The blockchain upgrade vm command enables the user to upgrade their Blockchain's VM binary. The command
can upgrade both local Blockchains and publicly deployed Blockchains on Fuji and Mainnet.

The command walks the user through an interactive wizard. The user can skip the wizard by providing
command line flags.

**Usage:**
```bash
avalanche subnet upgrade vm [subcommand] [flags]
```

**Flags:**

```bash
--binary string             Upgrade to custom binary
--config upgrade            config for future subnet deployments
--fuji fuji                 upgrade existing fuji deployment (alias for `testnet`)
-h, --help help             for vm
--latest upgrade            to latest version
--local local               upgrade existing local deployment
--mainnet mainnet           upgrade existing mainnet deployment
--plugin-dir string         plugin directory to automatically upgrade VM
--print print               instructions for upgrading
--testnet testnet           upgrade existing testnet deployment (alias for `fuji`)
--version string            Upgrade to custom version
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-subnet-validators"></a>
### validators

The blockchain validators command lists the validators of a blockchain's subnet and provides
several statistics about them.

**Usage:**
```bash
avalanche subnet validators [subcommand] [flags]
```

**Flags:**

```bash
--cluster string            operate on the given cluster
--devnet operate            on a devnet network
--endpoint string           use the given endpoint for network operations
-f, --fuji testnet          operate on fuji (alias to testnet
-h, --help help             for validators
-l, --local operate         on a local network
-m, --mainnet operate       on mainnet
-t, --testnet fuji          operate on testnet (alias to fuji)
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-subnet-vmid"></a>
### vmid

The blockchain vmid command prints the virtual machine ID (VMID) for the given Blockchain.

**Usage:**
```bash
avalanche subnet vmid [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help             for vmid
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-teleporter"></a>
## avalanche teleporter

The messenger command suite provides a collection of tools for interacting
with ICM messenger contracts.

**Usage:**
```bash
avalanche teleporter [subcommand] [flags]
```

**Subcommands:**

- [`deploy`](#avalanche-teleporter-deploy): Deploys ICM Messenger and Registry into a given L1.
- [`sendMsg`](#avalanche-teleporter-sendmsg): Sends and wait reception for a ICM msg between two subnets.

**Flags:**

```bash
-h, --help help             for teleporter
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-teleporter-deploy"></a>
### deploy

Deploys ICM Messenger and Registry into a given L1.

**Usage:**
```bash
avalanche teleporter deploy [subcommand] [flags]
```

**Flags:**

```bash
--blockchain string                         deploy ICM into the given CLI blockchain
--blockchain-id string                      deploy ICM into the given blockchain ID/Alias
--c-chain deploy                            ICM into C-Chain
--cchain-key string                         key to be used to pay fees to deploy ICM to C-Chain
--cluster string                            operate on the given cluster
--deploy-messenger deploy                   ICM Messenger (default true)
--deploy-registry deploy                    ICM Registry (default true)
--devnet operate                            on a devnet network
--endpoint string                           use the given endpoint for network operations
--force-registry-deploy deploy              ICM Registry even if Messenger has already been deployed
-f, --fuji testnet                          operate on fuji (alias to testnet
--genesis-key use                           genesis allocated key to fund ICM deploy
-h, --help help                             for deploy
--include-cchain deploy                     ICM also to C-Chain
--key string                                CLI stored key to use to fund ICM deploy
-l, --local operate                         on a local network
--messenger-contract-address-path string    path to a messenger contract address file
--messenger-deployer-address-path string    path to a messenger deployer address file
--messenger-deployer-tx-path string         path to a messenger deployer tx file
--private-key string                        private key to use to fund ICM deploy
--registry-bytecode-path string             path to a registry bytecode file
--rpc-url string                            use the given RPC URL to connect to the subnet
-t, --testnet fuji                          operate on testnet (alias to fuji)
--version string                            version to deploy (default "latest")
--config string                             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string                          log level for the application (default "ERROR")
--skip-update-check skip                    check for new versions
```

<a id="avalanche-teleporter-sendmsg"></a>
### sendMsg

Sends and wait reception for a ICM msg between two subnets.

**Usage:**
```bash
avalanche teleporter sendMsg [subcommand] [flags]
```

**Flags:**

```bash
--cluster string                operate on the given cluster
--dest-rpc string               use the given destination blockchain rpc endpoint
--destination-address string    deliver the message to the given contract destination address
--devnet operate                on a devnet network
--endpoint string               use the given endpoint for network operations
-f, --fuji testnet              operate on fuji (alias to testnet
--genesis-key use               genesis allocated key as message originator and to pay source blockchain fees
-h, --help help                 for sendMsg
--hex-encoded given             message is hex encoded
--key string                    CLI stored key to use as message originator and to pay source blockchain fees
-l, --local operate             on a local network
--private-key string            private key to use as message originator and to pay source blockchain fees
--source-rpc string             use the given source blockchain rpc endpoint
-t, --testnet fuji              operate on testnet (alias to fuji)
--config string                 config file (default is $HOME/.avalanche-cli/config.json)
--log-level string              log level for the application (default "ERROR")
--skip-update-check skip        check for new versions
```

<a id="avalanche-transaction"></a>
## avalanche transaction

The transaction command suite provides all of the utilities required to sign multisig transactions.

**Usage:**
```bash
avalanche transaction [subcommand] [flags]
```

**Subcommands:**

- [`commit`](#avalanche-transaction-commit): The transaction commit command commits a transaction by submitting it to the P-Chain.
- [`sign`](#avalanche-transaction-sign): The transaction sign command signs a multisig transaction.

**Flags:**

```bash
-h, --help help             for transaction
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-transaction-commit"></a>
### commit

The transaction commit command commits a transaction by submitting it to the P-Chain.

**Usage:**
```bash
avalanche transaction commit [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help               for commit
--input-tx-filepath string    Path to the transaction signed by all signatories
--config string               config file (default is $HOME/.avalanche-cli/config.json)
--log-level string            log level for the application (default "ERROR")
--skip-update-check skip      check for new versions
```

<a id="avalanche-transaction-sign"></a>
### sign

The transaction sign command signs a multisig transaction.

**Usage:**
```bash
avalanche transaction sign [subcommand] [flags]
```

**Flags:**

```bash
-h, --help help               for sign
--input-tx-filepath string    Path to the transaction file for signing
-k, --key string              select the key to use [fuji only]
-g, --ledger use              ledger instead of key (always true on mainnet, defaults to false on fuji)
--ledger-addrs strings        use the given ledger addresses
--config string               config file (default is $HOME/.avalanche-cli/config.json)
--log-level string            log level for the application (default "ERROR")
--skip-update-check skip      check for new versions
```

<a id="avalanche-update"></a>
## avalanche update

Check if an update is available, and prompt the user to install it

**Usage:**
```bash
avalanche update [subcommand] [flags]
```

**Flags:**

```bash
-c, --confirm Assume        yes for installation
-h, --help help             for update
-v, --version version       for update
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-validator"></a>
## avalanche validator

The validator command suite provides a collection of tools for managing validator
balance on P-Chain.

Validator's balance is used to pay for continuous fee to the P-Chain. When this Balance reaches 0, 
the validator will be considered inactive and will no longer participate in validating the L1

**Usage:**
```bash
avalanche validator [subcommand] [flags]
```

**Subcommands:**

- [`getBalance`](#avalanche-validator-getbalance): This command gets the remaining validator P-Chain balance that is available to pay
P-Chain continuous fee
- [`increaseBalance`](#avalanche-validator-increasebalance): This command increases the validator P-Chain balance
- [`list`](#avalanche-validator-list): This command gets a list of the validators of the L1

**Flags:**

```bash
-h, --help help             for validator
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-validator-getbalance"></a>
### getBalance

This command gets the remaining validator P-Chain balance that is available to pay
P-Chain continuous fee

**Usage:**
```bash
avalanche validator getBalance [subcommand] [flags]
```

**Flags:**

```bash
--cluster string            operate on the given cluster
--devnet operate            on a devnet network
--endpoint string           use the given endpoint for network operations
-f, --fuji testnet          operate on fuji (alias to testnet
-h, --help help             for getBalance
--l1 string                 name of L1
-l, --local operate         on a local network
-m, --mainnet operate       on mainnet
--node-id string            node ID of the validator
-t, --testnet fuji          operate on testnet (alias to fuji)
--validation-id string      validation ID of the validator
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-validator-increasebalance"></a>
### increaseBalance

This command increases the validator P-Chain balance

**Usage:**
```bash
avalanche validator increaseBalance [subcommand] [flags]
```

**Flags:**

```bash
--balance float             amount of AVAX to increase validator's balance by
--cluster string            operate on the given cluster
--devnet operate            on a devnet network
--endpoint string           use the given endpoint for network operations
-f, --fuji testnet          operate on fuji (alias to testnet
-h, --help help             for increaseBalance
-k, --key string            select the key to use [fuji/devnet deploy only]
--l1 string                 name of L1 (to increase balance of bootstrap validators only)
-l, --local operate         on a local network
-m, --mainnet operate       on mainnet
--node-id string            node ID of the validator
-t, --testnet fuji          operate on testnet (alias to fuji)
--validation-id string      validationIDStr of the validator
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```

<a id="avalanche-validator-list"></a>
### list

This command gets a list of the validators of the L1

**Usage:**
```bash
avalanche validator list [subcommand] [flags]
```

**Flags:**

```bash
--cluster string            operate on the given cluster
--devnet operate            on a devnet network
--endpoint string           use the given endpoint for network operations
-f, --fuji testnet          operate on fuji (alias to testnet
-h, --help help             for list
-l, --local operate         on a local network
-m, --mainnet operate       on mainnet
-t, --testnet fuji          operate on testnet (alias to fuji)
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check skip    check for new versions
```



# Make Avalanche L1 Permissionless (/docs/avalanche-l1s/elastic-avalanche-l1s/make-avalanche-l1-permissionless)

---
title: Make Avalanche L1 Permissionless
description: Learn how to transform a Permissioned Avalanche L1 into an Elastic Avalanche L1.
---

> Elastic L1s / Elastic Subnets have been deprecated. Please check out the PoS Validator Manager instead

Elastic Avalanche L1s are permissionless Avalanche L1s. More information can be found [here](/docs/avalanche-l1s/elastic-avalanche-l1s/parameters).

This how-to guide focuses on taking an already created permissioned Avalanche L1 and transforming it to an elastic (or permissionless) Avalanche L1.

## Prerequisites

- [Avalanche-CLI installed](/docs/tooling/get-avalanche-cli)
- You have deployed a permissioned Avalanche L1 on [local](/docs/avalanche-l1s/deploy-a-avalanche-l1/local-network), on [Fuji](/docs/avalanche-l1s/deploy-a-avalanche-l1/fuji-testnet) or on [Mainnet](/docs/avalanche-l1s/deploy-a-avalanche-l1/avalanche-mainnet)

Getting Started[​](#getting-started "Direct link to heading")
-------------------------------------------------------------

In the following commands, make sure to substitute the name of your Avalanche L1 configuration for `<blockchainName>`.

To transform your permissioned Avalanche L1 into an Elastic Avalanche L1 (NOTE: this action is irreversible), run:

```bash
avalanche blockchain elastic <blockchainName>
```

and, select the network that you want to transform the Avalanche L1 on. Alternatively, you can bypass this prompt by providing the `--local`, `--fuji`, or `--mainnet` flag.

Provide the name and the symbol for the permissionless Avalanche L1's native token. You can also bypass this prompt by providing the `--tokenName` and `--tokenSymbol` flags.

Next, select the Elastic Avalanche L1 config. You can choose to use the default values detailed [here](/docs/avalanche-l1s/elastic-avalanche-l1s/parameters#primary-network-parameters-on-mainnet) or customize the Elastic Avalanche L1 config. To bypass the prompt, you can use `--default` flag to use the default Elastic Avalanche L1 config.

The command may take a couple minutes to run.

### Elastic Avalanche L1 Transformation on Fuji and Mainnet[​](#elastic-avalanche-l1-transformation-on-fuji-and-mainnet "Direct link to heading")

Elastic Avalanche L1 transformation on public network requires private key loaded into the tool, or a connected ledger device.

Both stored key usage and ledger usage are enabled on Fuji (see more on creating keys [here](/docs/avalanche-l1s/deploy-a-avalanche-l1/fuji-testnet#private-key)) while only ledger usage is enabled on Mainnet (see more on setting up your ledger [here](/docs/avalanche-l1s/deploy-a-avalanche-l1/avalanche-mainnet#setting-up-your-ledger)).

To transform a permissioned Avalanche L1 into Elastic Avalanche L1 on public networks, users are required to provide the keys that control the Avalanche L1 defined during the Avalanche L1 deployment process (more info on keys in Fuji can be found [here](/docs/avalanche-l1s/deploy-a-avalanche-l1/fuji-testnet#deploy-the-avalanche-l1), while more info on ledger signing in Mainnet can be found [here](/docs/avalanche-l1s/deploy-a-avalanche-l1/avalanche-mainnet#deploy-the-avalanche-l1)).

### Results[​](#results "Direct link to heading")

If all works as expected, you then have the option to automatically transform all existing permissioned validators to permissionless validators.

You can also to skip automatic transformation at this point and choose to manually add permissionless validators later.

You can use the output details such as the Asset ID and Elastic Avalanche L1 ID (SubnetID) to connect to and interact with your Elastic Avalanche L1.

Adding Permissionless Validators to Elastic Avalanche L1[​](#adding-permissionless-validators-to-elastic-avalanche-l1 "Direct link to heading")
-----------------------------------------------------------------------------------------------------------------------------------

If you are running this command on local network, you will need to first remove permissioned validators (by running `avalanche subnet removeValidator <blockchainName>`) so that you can have a list of local nodes to choose from to be added as a permissionless validator in the Elastic Avalanche L1.

To add permissionless validators to an Elastic Avalanche L1, run:

```bash
avalanche blockchain join <blockchainName> --elastic
```

You will be prompted with which node you would like to add as a permissionless validator. You can skip this prompt by using `--nodeID` flag.

You will then be prompted with the amount of the Avalanche L1 native token that you like to stake in the validator. Alternatively, you can bypass this prompt by providing the `--stake-amount` flag. Note that choosing to add the maximum validator stake amount (defined during Elastic Avalanche L1 transformation step above) means that you effectively disable delegation in your validator.

Next, select when the validator will start validating and how long it will be validating for. You can also bypass these prompts by using `--start-time` and `--staking-period` flags.

Adding Permissionless Delegator to a Permissionless Validator in Elastic Avalanche L1[​](#adding-permissionless-delegator-to-a-permissionless-validator-in-elastic-avalanche-l1 "Direct link to heading")
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

To add permissionless delegators, run:

```bash
avalanche blockchain addPermissionlessDelegator <blockchainName>
```

You will be prompted with which Avalanche L1 validator you would like to delegate to. You can skip this prompt by using `--nodeID` flag.

You will then be prompted with the amount of the Avalanche L1 native token that you like to stake in the validator. Alternatively, you can bypass this prompt by providing the `--stake-amount` flag. The amount that can be delegated to a validator is detailed [here](/docs/avalanche-l1s/elastic-avalanche-l1s/parameters#delegators-weight-checks).

Next, select when you want to start delegating and how long you want to delegate for. You can also bypass these prompts by using `--start-time` and `--staking-period` flags.


# Parameters (/docs/avalanche-l1s/elastic-avalanche-l1s/parameters)

---
title: Parameters
description: Learn about the different parameters of Elastic Avalanche L1s.
---

> Elastic L1s / Elastic Subnets have been deprecated. Please check out the PoS Validator Manager instead

Avalanche Permissioned Avalanche L1s can be turned into Elastic Avalanche L1s via the `TransformSubnetTx` transaction. `TransformSubnetTx` specifies a set of structural parameters for the Elastic Avalanche L1.

This reference document describes these structural parameters and illustrates the constraints they must satisfy.

## Elastic Avalanche L1 Parameters

### `Subnet`

`Subnet` has type `ids.ID` and it's the Avalanche L1 ID (SubnetID). `Subnet` is the ID of the `CreateSubnetTx` transaction that created the Avalanche L1 in the first place. The following constraints apply:

- `Subnet` must be different from `PrimaryNetworkID`.

### `AssetID`

`AssetID` has type `ids.ID` and it's the ID of the asset to use when staking on the Avalanche L1. The following constraints apply:

- `AssetID` must not be the `Empty ID`.
- `AssetID` must not be `AVAX ID`, the Primary Network asset.

### `InitialSupply`

`InitialSupply` has type `uint64` and it's the initial amount of `AssetID` transferred in the Elastic Avalanche L1 upon its transformation. Such amount is available for distributing staking rewards. The following constraints apply:

- `InitialSupply` must be larger than zero.

### `MaximumSupply`

`MaximumSupply` has type `uint64` and it's the maximum amount of `AssetID` that Avalanche L1 has available for staking and rewards at any time. The following constraints apply:

- `MaximumSupply` must be larger or equal to `InitialSupply`.

an Avalanche L1 supply can vary in time but it should be no larger than the configured maximum at any point in time, including at Avalanche L1 creation.

### `MinConsumptionRate`

`MinConsumptionRate` has type `uint64` and it's the minimal rate a validator can earn if the `UptimeRequirement` is satisfied. If `StakingPeriod` == `MinStakeDuration`, the validator will earn the `MinConsumptionRate`.

You can find more details about it in the [Reward Formula section](#reward-formula). The following constraints apply:

- `MinConsumptionRate` must be smaller or equal to `PercentDenominator`.

See [Notes on Percentages](#notes-on-percentages) section to understand `PercentDenominator` role.

### `MaxConsumptionRate`

`MaxConsumptionRate` has type `uint64` and it's the maximal rate a validator can earn if the `UptimeRequirement` is satisfied. If `StakingPeriod` == `MaxStakeDuration` == `MintingPeriod`, the validator will earn the `MaxConsumptionRate`.

You can find more details about it in the [Reward Formula section](#reward-formula). The following constraints apply:

- `MaxConsumptionRate` must be larger or equal to `MinConsumptionRate`.
- `MaxConsumptionRate` must be smaller or equal to `PercentDenominator`.

See [Notes on Percentages](#notes-on-percentages) section to understand `PercentDenominator` role.

### `MinValidatorStake`

`MinValidatorStake` has type `uint64` and it's the minimum amount of funds required to become a validator. The following constraints apply:

- `MinValidatorStake` must be larger than zero
- `MinValidatorStake` must be smaller or equal to `InitialSupply`

### `MaxValidatorStake`

`MaxValidatorStake` has type `uint64` and it's the maximum amount of funds a single validator can be allocated, including delegated funds. The following constraints apply:

- `MaxValidatorStake` must be larger or equal to `MinValidatorStake`
- `MaxValidatorStake` must be smaller or equal to `MaximumSupply`

### `MinStakeDuration`

`MinStakeDuration` has type `uint32` and it's the minimum number of seconds a staker can stake for. The following constraints apply:

- `MinStakeDuration` must be larger than zero.

### `MaxStakeDuration`

`MaxStakeDuration` has type `uint32` and it's the maximum number of seconds a staker can stake for. The following constraints apply:

- `MaxStakeDuration` must be larger or equal to `MinStakeDuration`.
- `MaxStakeDuration` must be smaller or equal to `GlobalMaxStakeDuration`.

`GlobalMaxStakeDuration` is defined in genesis and applies to both the Primary Network and all Avalanche L1s.

Its Mainnet value is $365 \times 24 \times time.Hour$.

### `MinDelegationFee`

`MinDelegationFee` has type `uint32` and it's the minimum fee rate a delegator must pay to its validator for delegating. `MinDelegationFee` is a percentage; the actual fee is calculated multiplying the fee rate for the delegator reward. The following constraints apply:

- `MinDelegationFee` must be smaller or equal to `PercentDenominator`.

The `MinDelegationFee` rate applies to Primary Network as well. Its Mainnet value is $2\%$.

### `MinDelegatorStake`

`MinDelegatorStake` has type `uint64` and it's the minimum amount of funds required to become a delegator. The following constraints apply:

- `MinDelegatorStake` must be larger than zero.

### `MaxValidatorWeightFactor`

`MaxValidatorWeightFactor` has type `uint8` and it's the factor which calculates the maximum amount of delegation a validator can receive. A value of 1 effectively disables delegation. You can find more details about it in the [Delegators Weight Checks section](#delegators-weight-checks). The following constraints apply:

- `MaxValidatorWeightFactor` must be larger than zero.

### `UptimeRequirement`

`UptimeRequirement` has type `uint32` and it's the minimum percentage of its staking time that a validator must be online and responsive for to receive a reward. The following constraints apply:

- `UptimeRequirement` must be smaller or equal `PercentDenominator`.

See [Notes on Percentages](#notes-on-percentages) section to understand `PercentDenominator` role.

## Reward Formula

Consider an Elastic Avalanche L1 validator which stakes a $Stake$ amount `AssetID` for $StakingPeriod$ seconds.

Assume that at the start of the staking period there is a $Supply$ amount of `AssetID` in the Avalanche L1. The maximum amount of Avalanche L1 asset is $MaximumSupply$ `AssetID`.

Then at the end of its staking period, a responsive Elastic Avalanche L1 validator receives a reward calculated as follows:

$$
Reward = \left(MaximumSupply - Supply \right) \times \frac{Stake}{Supply} \times \frac{Staking Period}{Minting Period} \times EffectiveConsumptionRate
$$

where,

$$
MaximumSupply - Supply = \text{the number of tokens left to emit in the avalanche-l1}
$$

$$
\frac{Stake}{Supply} = \text{the individual's stake as a percentage of all available tokens in the network}
$$

$$
\frac{StakingPeriod}{MintingPeriod} = \text{time tokens are locked up divided by the $MintingPeriod$}
$$

$$
\text{$MintingPeriod$ is one year as configured by the Primary Network).}
$$

$$
EffectiveConsumptionRate =
$$

$$
\frac{MinConsumptionRate}{PercentDenominator} \times \left(1- \frac{Staking Period}{Minting Period}\right) + \frac{MaxConsumptionRate}{PercentDenominator} \times \frac{Staking Period}{Minting Period}
$$

Note that $StakingPeriod$ is the staker's entire staking period, not just the staker's uptime, that is the aggregated time during which the staker has been responsive. The uptime comes into play only to decide whether a staker should be rewarded; to calculate the actual reward only the staking period duration is taken into account.

$EffectiveConsumptionRate$ is the rate at which the validator is rewarded based on $StakingPeriod$ selection.

$MinConsumptionRate$ and $MaxConsumptionRate$ bound $EffectiveConsumptionRate$:

$$
MinConsumptionRate \leq EffectiveConsumptionRate \leq MaxConsumptionRate
$$

The larger $StakingPeriod$ is, the closer $EffectiveConsumptionRate$ is to $MaxConsumptionRate$. The smaller $StakingPeriod$ is, the closer $EffectiveConsumptionRate$ is to $MinConsumptionRate$.

A staker achieves the maximum reward for its stake if $StakingPeriod$ = $Minting Period$. The reward is:

$$
Max Reward = \left(MaximumSupply - Supply \right) \times \frac{Stake}{Supply} \times \frac{MaxConsumptionRate}{PercentDenominator}
$$

Note that this formula is the same as the reward formula at the top of this section because $EffectiveConsumptionRate$ = $MaxConsumptionRate$.

The reward formula above is used in the Primary Network to calculate stakers reward. For reference, you can find Primary network parameters in [the section below](#primary-network-parameters-on-mainnet).

## Delegators Weight Checks

There are bounds set of the maximum amount of delegators' stake that a validator can receive.

The maximum weight $MaxWeight$ a validator $Validator$ can have is:

$$
MaxWeight = \min(Validator.Weight \times MaxValidatorWeightFactor, MaxValidatorStake)
$$

where $MaxValidatorWeightFactor$ and $MaxValidatorStake$ are the Elastic Avalanche L1 Parameters described above.

A delegator won't be added to a validator if the combination of their weights and all other validator's delegators' weight is larger than $MaxWeight$. Note that this must be true at any point in time.

Note that setting $MaxValidatorWeightFactor$ to 1 disables delegation since the $MaxWeight = Validator.Weight$.

## Notes on Percentages

`PercentDenominator = 1_000_000` is the denominator used to calculate percentages.

It allows you to specify percentages up to 4 digital positions. To denominate your percentage in `PercentDenominator` just multiply it by `10_000`. For example:

- `100%` corresponds to `100 * 10_000 = 1_000_000`
- `1%` corresponds to `1* 10_000 = 10_000`
- `0.02%` corresponds to `0.002 * 10_000 = 200`
- `0.0007%` corresponds to `0.0007 * 10_000 = 7`

## Primary Network Parameters on Mainnet

An Elastic Avalanche L1 is free to pick any parameters affecting rewards, within the constraints specified above. For reference we list below Primary Network parameters on Mainnet:

- `AssetID = Avax`
- `InitialSupply = 240_000_000 Avax`
- `MaximumSupply = 720_000_000 Avax`.
- `MinConsumptionRate = 0.10 * reward.PercentDenominator`.
- `MaxConsumptionRate = 0.12 * reward.PercentDenominator`.
- `Minting Period = 365 * 24 * time.Hour`.
- `MinValidatorStake = 2_000 Avax`.
- `MaxValidatorStake = 3_000_000 Avax`.
- `MinStakeDuration = 2 * 7 * 24 * time.Hour`.
- `MaxStakeDuration = 365 * 24 * time.Hour`.
- `MinDelegationFee = 20000`, that is `2%`.
- `MinDelegatorStake = 25 Avax`.
- `MaxValidatorWeightFactor = 5`. This is a platformVM parameter rather than a genesis one, so it's shared across networks.
- `UptimeRequirement = 0.8`, that is `80%`.

### Interactive Graph

The graph below demonstrates the reward as a function of the length of time
staked. The x-axis depicts $\frac{StakingPeriod}{MintingPeriod}$ as a percentage
while the y-axis depicts $Reward$ as a percentage of $MaximumSupply - Supply$,
the amount of tokens left to be emitted.

Graph variables correspond to those defined above:

- `h` (high) = $MaxConsumptionRate$
- `l` (low) = $MinConsumptionRate$
- `s` = $\frac{Stake}{Supply}$

<iframe src="https://www.desmos.com/calculator/uqtank2gcn" width="100%" height="400px"></iframe>


# Allowlist Interface (/docs/avalanche-l1s/evm-configuration/allowlist)

---
title: Allowlist Interface
description: The AllowList interface is used by many default precompiles to permission access to the features they provide.
---

## Overview

The AllowList is a security feature used by precompiles to manage which addresses have permission to interact with certain contract functionalities. For example, in the Native Minter Precompile, the allow list is used to control who can mint new native tokens.

## Role-Based Permissions

The AllowList implements a consistent role-based permission system:

| Role | Value | Description | Permissions |
|------|-------|-------------|-------------|
| Admin | 2 | Can manage all roles | Can add/remove any role (Admin, Manager, Enabled) |
| Manager | 3 | Can manage enabled addresses | Can add/remove only Enabled addresses |
| Enabled | 1 | Basic permissions | Can use the precompile's functionality |
| None | 0 | No permissions | Cannot use the precompile or manage permissions |

Each precompile that uses the AllowList interface follows this permission structure, though the specific actions allowed for "Enabled" addresses vary depending on the precompile's purpose. For example:
- In the Contract Deployer AllowList, "Enabled" addresses can deploy contracts
- In the Transaction AllowList, "Enabled" addresses can submit transactions
- In the Native Minter, "Enabled" addresses can mint tokens

## Interface

The AllowList interface is defined as follows:

```solidity
//SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

interface IAllowList {
  event RoleSet(uint256 indexed role, address indexed account, address indexed sender, uint256 oldRole);

  // Set [addr] to have the admin role over the precompile contract.
  function setAdmin(address addr) external;

  // Set [addr] to be enabled on the precompile contract.
  function setEnabled(address addr) external;

  // Set [addr] to have the manager role over the precompile contract.
  function setManager(address addr) external;

  // Set [addr] to have no role for the precompile contract.
  function setNone(address addr) external;

  // Read the status of [addr].
  function readAllowList(address addr) external view returns (uint256 role);
}
```

## Implementation

The AllowList interface is implemented by multiple precompiles in the Subnet-EVM. You can find the core implementation in the [subnet-evm repository](https://github.com/ava-labs/subnet-evm/blob/master/precompile/allowlist/allowlist.go).

## Precompiles Using AllowList

Several precompiles in Subnet-EVM use the AllowList interface:

- [Native Minter](/docs/avalanche-l1s/evm-configuration/tokenomics#native-minter)
- [Fee Manager](/docs/avalanche-l1s/evm-configuration/transaction-fees#fee-manager)
- [Reward Manager](/docs/avalanche-l1s/evm-configuration/transaction-fees#reward-manager)
- [Contract Deployer Allow List](/docs/avalanche-l1s/evm-configuration/permissions#contract-deployer-allowlist)
- [Transaction Allow List](/docs/avalanche-l1s/evm-configuration/permissions#transaction-allowlist)


# Introduction (/docs/avalanche-l1s/evm-configuration/evm-l1-customization)

---
title: Introduction
description: Learn how to customize the Ethereum Virtual Machine with EVM and Precompiles.
root: true
---

Welcome to the EVM configuration guide. This documentation explores how to extend and customize your Avalanche L1 using **EVM** and **precompiles**. Building upon the Validator Manager capabilities we discussed in the previous section, we'll now dive into other powerful customization features available in EVM.

## Overview of EVM

EVM is Avalanche's customized version of the Ethereum Virtual Machine, tailored to run on Avalanche L1s. It allows developers to deploy Solidity smart contracts with enhanced capabilities, benefiting from Avalanche's high throughput and low latency. EVM enables more flexibility and performance optimizations compared to the standard EVM.

Beyond the Validator Manager functionality we've covered, EVM provides additional configuration options through precompiles, allowing you to extend your L1's capabilities even further.

## Genesis Configuration

Each blockchain has some genesis state when it's created. Each Virtual Machine defines the format and semantics of its genesis data. The genesis configuration is crucial for setting up your Avalanche L1's initial state and behavior.

### Chain Configuration

The chain configuration section in your genesis file defines fundamental parameters of your blockchain:

```json
{
  "config": {
    "chainId": 43214,
    "homesteadBlock": 0,
    "eip150Block": 0,
    "eip150Hash": "0x2086799aeebeae135c246c65021c82b4e15a2c451340993aacfd2751886514f0",
    "eip155Block": 0,
    "eip158Block": 0,
    "byzantiumBlock": 0,
    "constantinopleBlock": 0,
    "petersburgBlock": 0,
    "istanbulBlock": 0,
    "muirGlacierBlock": 0
  }
}
```

#### Chain ID
`chainID`: Denotes the ChainID of to be created chain. Must be picked carefully since a conflict with other chains can cause issues. One suggestion is to check with [chainlist.org](https://chainlist.org/) to avoid ID collision, reserve and publish your ChainID properly.

You can use `eth_getChainConfig` RPC call to get the current chain config. See [here](/docs/api-reference/subnet-evm-api#eth_getchainconfig) for more info.

#### Hard Forks
The following parameters define EVM hard fork activation times. These should be handled with care as changes may cause compatibility issues:
- `homesteadBlock`
- `eip150Block`
- `eip150Hash`
- `eip155Block`
- `byzantiumBlock`
- `constantinopleBlock`
- `petersburgBlock`
- `istanbulBlock`
- `muirGlacierBlock`

### Genesis Block Header

The genesis block header is defined by several parameters that set the initial state of your blockchain:

```json
{
  "nonce": "0x0",
  "timestamp": "0x0",
  "extraData": "0x00",
  "difficulty": "0x0",
  "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
  "coinbase": "0x0000000000000000000000000000000000000000",
  "number": "0x0",
  "gasUsed": "0x0",
  "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000"
}
```

These parameters have specific roles:

- `nonce`, `mixHash`, `difficulty`: These are remnants from Proof of Work systems. For Avalanche, they don't play any relevant role and should be left as their default values.
- `timestamp`: The creation timestamp of the genesis block (commonly set to `0x0`).
- `extraData`: Optional extra data field (commonly set to `0x`).
- `coinbase`: The address of block producers (usually set to zero address for genesis).
- `parentHash`: The hash of the parent block (set to zero hash for genesis).
- `gasUsed`: Amount of gas used by the genesis block (usually `0x0`).
- `number`: The block number (must be `0x0` for genesis).

## Precompiles

Precompiles are specialized smart contracts that execute native Go code within the EVM context. They act as a bridge between Solidity and lower-level functionalities, allowing for performance optimizations and access to features not available in Solidity alone.

### Default Precompiles in EVM

EVM comes with a set of default precompiles that extend the EVM's functionality:

- **AllowList**: Interface that manages access control by allowing or restricting specific addresses, inherited by all precompiles.
- **Deployer AllowList**: Restricts which addresses can deploy smart contracts.
- **Native Minter**: Manages the minting and burning of native tokens.
- **Transaction AllowList**: Controls which addresses can submit transactions.
- **Fee Manager**: Controls gas fee parameters and fee markets.
- **Reward Manager**: Handles the distribution of staking rewards to validators.
- **Warp Messenger**: Enables cross-chain communication between Avalanche L1s.

### Precompile Addresses and Configuration

If a precompile is enabled within the `genesis.json` using the respective `ConfigKey`, you can interact with the precompile using Foundry or other tools such as Remix.

Below are the addresses and `ConfigKey` values of default precompiles available in EVM. The address and `ConfigKey` [are defined in the `module.go` of each precompile contract](https://github.com/ava-labs/subnet-evm/tree/master/precompile/contracts).

| Precompile             | ConfigKey                         | Address                                      |
| ---------------------- | --------------------------------- | -------------------------------------------- |
| Deployer AllowList     | `contractDeployerAllowListConfig` | `0x0200000000000000000000000000000000000000` |
| Native Minter          | `contractNativeMinterConfig`      | `0x0200000000000000000000000000000000000001` |
| Transaction AllowList  | `txAllowListConfig`               | `0x0200000000000000000000000000000000000002` |
| Fee Manager            | `feeManagerConfig`                | `0x0200000000000000000000000000000000000003` |
| Reward Manager         | `rewardManagerConfig`             | `0x0200000000000000000000000000000000000004` |
| Warp Messenger         | `warpConfig`                      | `0x0200000000000000000000000000000000000005` |

#### Example Interaction

For example, if `contractDeployerAllowListConfig` is enabled in the `genesis.json`:

```json title="genesis.json"
 "contractDeployerAllowListConfig": {
      "adminAddresses": [ // Addresses that can manage (add/remove) enabled addresses. They are also enabled themselves for contract deployment.
        "0x4f9e12d407b18ad1e96e4f139ef1c144f4058a4e",
        "0x4b9e5977a46307dd93674762f9ddbe94fb054def"
      ],
      "blockTimestamp": 0,
      "enabledAddresses": [
        "0x09c6fa19dd5d41ec6d0f4ca6f923ec3d941cc569" // Addresses that can only deploy contracts
      ]
    },
```

We can then add an `Enabled` address to the Deployer AllowList by interacting with the `IAllowList` interface at `0x0200000000000000000000000000000000000000`:

```bash
cast send 0x0200000000000000000000000000000000000000 setEnabled(address addr) <ADDRESS_TO_ENABLE> --rpc-url $MY_L1_RPC --private-key $ADMIN_PRIVATE_KEY
```

# Interacting with Precompiles (/docs/avalanche-l1s/evm-configuration/interacting-with-precompiles)

---
title: Interacting with Precompiles
description: Learn how to interact with Avalanche L1 precompiles using the Builder Hub Developer Console or Remix IDE.
---

This guide shows you how to interact with precompiled contracts on your Avalanche L1. For standard precompile implementations, we recommend using the **Builder Hub Developer Console** for the best experience. For custom implementations or advanced use cases, you can use **Remix IDE** with browser wallets.

## Recommended: Using Builder Hub Developer Console

The Builder Hub provides dedicated tools for interacting with standard Avalanche L1 precompiles. These tools offer:

- ✅ **User-friendly interface** - No need to manually enter contract addresses or ABIs
- ✅ **Built-in validation** - Prevents common configuration mistakes
- ✅ **Connected to your Builder account** - Track your L1s and configurations
- ✅ **Visual feedback** - See changes reflected in real-time

### Available Console Tools

| Precompile | Console Tool |
|------------|--------------|
| Fee Manager | [Fee Manager Console](/console/l1-tokenomics/fee-manager) |
| Reward Manager | [Reward Manager Console](/console/l1-tokenomics/reward-manager) |
| Native Minter | [Native Minter Console](/console/l1-tokenomics/native-minter) |
| Contract Deployer Allowlist | [Deployer Allowlist Console](/console/l1-access-restrictions/deployer-allowlist) |
| Transaction Allowlist | [Transactor Allowlist Console](/console/l1-access-restrictions/transactor-allowlist) |

### How to Use Console Tools

1. **Navigate** to the appropriate console tool from the table above
2. **Connect** your wallet (Core or MetaMask)
3. **Switch** to your L1 network in your wallet
4. The tool will automatically detect your permissions
5. **Configure** using the visual interface:
   - For Fee Manager: Adjust gas limits, base fees, and target rates
   - For Native Minter: Mint tokens to specific addresses
   - For Allowlists: Add or remove addresses with specific roles
   - For Reward Manager: Configure fee distribution settings
6. **Review** the transaction details
7. **Submit** and approve in your wallet

<Callout type="info">
**Why use the Developer Console?**

Using the Builder Hub console tools allows us to:
- Provide better support for your L1
- Track feature usage to improve the platform
- Build your profile in our builders/developers database
- Offer personalized recommendations and resources
</Callout>

### Example Workflows

**Configuring Transaction Fees:**
1. Go to [Fee Manager Console](/console/l1-tokenomics/fee-manager)
2. Connect wallet and switch to your L1
3. Adjust fee parameters using sliders and inputs
4. See real-time preview of how changes affect gas costs
5. Submit transaction to update fees

**Minting Native Tokens:**
1. Go to [Native Minter Console](/console/l1-tokenomics/native-minter)
2. Connect with an admin/manager address
3. Enter recipient address and amount
4. Review the minting transaction
5. Approve to mint tokens instantly

**Managing Permissions:**
1. Go to [Deployer Allowlist](/console/l1-access-restrictions/deployer-allowlist) or [Transactor Allowlist](/console/l1-access-restrictions/transactor-allowlist)
2. Connect with an admin address
3. Add addresses with desired roles (Admin, Manager, Enabled)
4. Remove addresses by changing their role to "None"
5. View current allowlist status

## Alternative: Using Remix IDE

For custom precompile implementations or if you prefer a code-based approach, you can use Remix IDE to interact with precompiles directly.

### When to Use Remix

Use Remix when:
- You have a **custom precompile** implementation (non-standard addresses or interfaces)
- You need to interact with precompiles **programmatically**
- You're **debugging** contract interactions
- The Builder Console doesn't support your specific use case

### Prerequisites

- Access to an Avalanche L1 where you have admin/manager rights for a precompile
- [Core Browser Extension](https://core.app) or MetaMask
- Private key for an admin/manager address on your L1
- Your L1's RPC URL and Chain ID

## Setup Your Wallet

### Using Core

1. Install the [Core Browser Extension](https://core.app)
2. Import or create the account with admin/manager privileges
3. Enable **Testnet Mode** (if using testnet):
   - Open Core extension
   - Click hamburger menu → **Advanced**
   - Toggle **Testnet Mode** on

4. Add your L1 network:
   - Click the networks dropdown
   - Select **Manage Networks**
   - Click **Add Network** and enter:
     - **Network Name**: Your L1 name
     - **RPC URL**: Your L1's RPC endpoint
     - **Chain ID**: Your L1's chain ID
     - **Symbol**: Your native token symbol
     - **Explorer**: (Optional) Your L1's explorer URL

5. Switch to your L1 network in the dropdown

### Using MetaMask

1. Install MetaMask browser extension
2. Import the account with admin/manager privileges
3. Add your L1 network:
   - Click the networks dropdown
   - Click **Add Network** → **Add a network manually**
   - Enter your L1's network details
   - Click **Save**

## Connect Remix to Your L1

1. Open [Remix IDE](https://remix.ethereum.org/) in your browser

2. In the left sidebar, click the **Deploy & run transactions** icon

3. In the **Environment** dropdown, select **Injected Provider - MetaMask** (or Core)

4. Approve the connection request in your wallet extension

5. Verify the connection shows your L1's network (e.g., "Custom (11111) network")

## Load Precompile Interfaces

You need to load the Solidity interfaces for the precompiles you want to interact with.

### Available Precompile Interfaces

From the Remix home screen, use **load from GitHub** to import:

**Required for all precompiles:**
- [IAllowList.sol](https://github.com/ava-labs/subnet-evm/blob/master/contracts/contracts/interfaces/IAllowList.sol)

**Specific precompile interfaces:**
- [IFeeManager.sol](https://github.com/ava-labs/subnet-evm/blob/master/contracts/contracts/interfaces/IFeeManager.sol) - For fee configuration
- [INativeMinter.sol](https://github.com/ava-labs/subnet-evm/blob/master/contracts/contracts/interfaces/INativeMinter.sol) - For minting native tokens
- [IAllowList.sol](https://github.com/ava-labs/subnet-evm/blob/master/contracts/contracts/interfaces/IAllowList.sol) - For transaction/deployer allowlists
- [IRewardManager.sol](https://github.com/ava-labs/subnet-evm/blob/master/contracts/contracts/interfaces/IRewardManager.sol) - For block rewards

### Compile the Interface

1. In Remix, click the **Solidity Compiler** icon in the left sidebar
2. Select the precompile interface file (e.g., `IFeeManager.sol`)
3. Click **Compile**

## Interact with Precompiles

### Connect to Deployed Precompile

Each precompile is deployed at a fixed address on your L1:

| Precompile | Address |
|------------|---------|
| NativeMinter | `0x0200000000000000000000000000000000000001` |
| ContractDeployerAllowList | `0x0200000000000000000000000000000000000000` |
| FeeManager | `0x0200000000000000000000000000000000000003` |
| RewardManager | `0x0200000000000000000000000000000000000004` |
| TransactionAllowList | `0x0200000000000000000000000000000000000002` |

1. In Remix, click **Deploy & run transactions**
2. In the **Contract** dropdown, select your compiled interface
3. Paste the precompile address in the **At Address** field
4. Click **At Address**

The precompile contract will appear in the **Deployed Contracts** section.

## Example: Using Fee Manager

### Read Current Fee Configuration

Anyone can read the current fee configuration (no special permissions required):

1. Expand the FeeManager contract in **Deployed Contracts**
2. Click **getFeeConfig**
3. View the current fee parameters:
   - `gasLimit`: Maximum gas per block
   - `targetBlockRate`: Target time between blocks (seconds)
   - `minBaseFee`: Minimum base fee (wei)
   - `targetGas`: Target gas per second
   - `baseFeeChangeDenominator`: Rate of base fee adjustment
   - `minBlockGasCost`: Minimum gas cost for a block
   - `maxBlockGasCost`: Maximum gas cost for a block
   - `blockGasCostStep`: Increment for block gas cost

### Update Fee Configuration

Only admin addresses can update the fee configuration:

1. Ensure you're connected with the admin address in your wallet
2. Expand **setFeeConfig** in the FeeManager contract
3. Fill in the new fee parameters:
   ```
   gasLimit: 8000000
   targetBlockRate: 2
   minBaseFee: 25000000000
   targetGas: 15000000
   baseFeeChangeDenominator: 36
   minBlockGasCost: 0
   maxBlockGasCost: 1000000
   blockGasCostStep: 200000
   ```
4. Click **transact**
5. Approve the transaction in your wallet
6. Wait for transaction confirmation

The new fee configuration takes effect immediately after the transaction is accepted.

## Example: Using Native Minter

### Mint Native Tokens

Only admin, manager, or enabled addresses can mint native tokens:

1. Expand the NativeMinter contract in **Deployed Contracts**
2. Click on **mintNativeCoin**
3. Fill in the parameters:
   - `addr`: Recipient address (e.g., `0xB78cbAa319ffBD899951AA30D4320f5818938310`)
   - `amount`: Amount to mint in wei (e.g., `1000000000000000000` for 1 token)
4. Click **transact**
5. Approve the transaction in your wallet

The minted tokens are added directly to the recipient's balance by the EVM (no sender transaction).

### Check Minting Permissions

Anyone can check who has minting permissions:

1. Click **readAllowList** with an address parameter
2. Returns:
   - `0`: No permission
   - `1`: Enabled (can mint)
   - `2`: Manager (can mint and manage enabled addresses)  
   - `3`: Admin (full control)

## Example: Managing Allow Lists

### Add Address to Allow List

Admins can add addresses to transaction or deployer allow lists:

1. Expand the AllowList contract
2. Use **setAdmin**, **setManager**, or **setEnabled**:
   ```
   addr: 0x1234...5678
   ```
3. Click **transact**
4. Approve in wallet

### Remove Address from Allow List

1. Use **setNone** with the address:
   ```
   addr: 0x1234...5678
   ```
2. Click **transact**

### Check Address Status

1. Click **readAllowList**:
   ```
   addr: 0x1234...5678
   ```
2. Returns permission level (0-3)

## Best Practices

### Security

- **Never share private keys** for admin addresses
- **Use hardware wallets** for admin accounts when possible
- **Test on testnet first** before making changes on mainnet
- **Use multi-sig contracts** for critical admin operations
- **Document all changes** and announce them to validators

### Network Upgrades

When enabling precompiles via network upgrades:

1. **Announce upgrades** well in advance on social media and Discord
2. **Coordinate with validators** to ensure they update their nodes
3. **Use upgrade.json** to schedule precompile activation (see [Precompile Upgrades](/docs/avalanche-l1s/evm-configuration/precompile-upgrades))
4. **Test the upgrade** on a testnet first
5. **Monitor** the network after activation

### Troubleshooting

**Connection Issues:**
- Verify your wallet is connected to the correct network
- Check that the RPC URL is accessible
- Ensure you have native tokens for gas fees

**Transaction Failures:**
- Confirm you're using an admin/manager address
- Check that the precompile is enabled on your L1
- Verify parameter formats (addresses must be checksummed)
- Ensure sufficient gas limit

**Precompile Not Found:**
- Verify the precompile address is correct
- Confirm the precompile is activated in your genesis or upgrade.json
- Check that you're on the correct network

## Additional Resources

### Builder Hub Console Tools
- [Fee Manager Console](/console/l1-tokenomics/fee-manager) - Configure transaction fees
- [Reward Manager Console](/console/l1-tokenomics/reward-manager) - Manage fee distribution
- [Native Minter Console](/console/l1-tokenomics/native-minter) - Mint native tokens
- [Deployer Allowlist Console](/console/l1-access-restrictions/deployer-allowlist) - Control contract deployment
- [Transactor Allowlist Console](/console/l1-access-restrictions/transactor-allowlist) - Control transaction submission

### Documentation
- [Precompile Configuration](/docs/avalanche-l1s/evm-configuration/evm-l1-customization) - Overview of precompiles
- [Transaction Fees](/docs/avalanche-l1s/evm-configuration/transaction-fees) - Fee Manager and Reward Manager details
- [Tokenomics](/docs/avalanche-l1s/evm-configuration/tokenomics) - Native Minter details
- [Permissions](/docs/avalanche-l1s/evm-configuration/permissions) - Allowlist precompiles
- [Precompile Upgrades](/docs/avalanche-l1s/evm-configuration/precompile-upgrades) - Network upgrade process
- [AllowList Interface](/docs/avalanche-l1s/evm-configuration/allowlist) - Role-based access control
- [Subnet-EVM Contracts](https://github.com/ava-labs/subnet-evm/tree/master/contracts/contracts/interfaces) - Precompile interfaces

## Conclusion

For standard Avalanche L1 precompiles, **we strongly recommend using the [Builder Hub Developer Console tools](/console)** for the best experience. These tools provide:

- ✅ Guided workflows with validation
- ✅ No need to manage contract addresses or ABIs manually  
- ✅ Integration with your Builder Hub account
- ✅ Support from the Builder Hub team

For custom implementations or advanced scenarios, the Remix IDE approach provides flexibility to interact with any contract at any address. This is useful for:

- Custom precompile implementations
- Testing and debugging
- Programmatic interactions
- Non-standard use cases

Whichever method you choose, always test on testnet first and follow security best practices when managing admin keys.



# Permissions (/docs/avalanche-l1s/evm-configuration/permissions)

---
title: Permissions
description: Control access to contract deployment and transaction submission on your Avalanche L1 blockchain.
---

## Overview

The Subnet-EVM provides two powerful precompiles for managing permissions on your Avalanche L1 blockchain:

- **Contract Deployer Allowlist**: Control which addresses can deploy smart contracts
- **Transaction Allowlist**: Control which addresses can submit transactions

Both precompiles use the [AllowList interface](/docs/avalanche-l1s/evm-configuration/allowlist) to manage permissions with a consistent role-based system.

## Contract Deployer Allowlist

### Purpose
The Contract Deployer Allowlist allows you to maintain a controlled environment where only authorized addresses can deploy new smart contracts. This is particularly useful for:

- Maintaining a curated ecosystem of verified contracts
- Preventing malicious contract deployments
- Implementing KYC/AML requirements for contract deployers

### Configuration
Located at address `0x0200000000000000000000000000000000000000`, you can activate this precompile in your genesis file:

```json
{
  "config": {
    "contractDeployerAllowListConfig": {
      "blockTimestamp": 0,
      "adminAddresses": ["0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC"]
    }
  }
}
```

By enabling this feature, you can define which addresses are allowed to deploy smart contracts and manage these permissions over time.

## Transaction Allowlist

### Purpose
The Transaction Allowlist enables you to control which addresses can submit transactions to your network. This is essential for:

- Creating fully permissioned networks
- Implementing KYC/AML requirements for users
- Controlling network access during testing or initial deployment

### Configuration
Located at address `0x0200000000000000000000000000000000000002`, you can activate this precompile in your genesis file:

```json
{
  "config": {
    "txAllowListConfig": {
      "blockTimestamp": 0,
      "adminAddresses": ["0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC"]
    }
  }
}
```

By enabling this feature, you can define which addresses are allowed to submit transactions and manage these permissions over time.

## Permissions Management

Both precompiles use the [AllowList interface](/docs/avalanche-l1s/evm-configuration/allowlist) to manage permissions. This provides a consistent way to:
- Assign and revoke permissions
- Manage admin and manager roles
- Control who can deploy contracts or submit transactions

For detailed information about the role-based permission system and available functions, see the [AllowList interface documentation](/docs/avalanche-l1s/evm-configuration/allowlist).

## Implementation

The precompiles implement the following interface:

```solidity
//SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

interface IAllowList {
  event RoleSet(uint256 indexed role, address indexed account, address indexed sender, uint256 oldRole);

  // Set [addr] to have the admin role over the precompile contract.
  function setAdmin(address addr) external;

  // Set [addr] to be enabled on the precompile contract.
  function setEnabled(address addr) external;

  // Set [addr] to have the manager role over the precompile contract.
  function setManager(address addr) external;

  // Set [addr] to have no role for the precompile contract.
  function setNone(address addr) external;

  // Read the status of [addr].
  function readAllowList(address addr) external view returns (uint256 role);
}
```

## Best Practices

1. **Initial Setup**: Always configure at least one admin address in the genesis file to ensure you can manage permissions after deployment.

2. **Role Management**:
   - Use Admin roles sparingly and secure their private keys
   - Assign Manager roles to trusted entities who need to manage user access
   - Regularly audit the list of enabled addresses

3. **Security Considerations**:
   - Keep private keys of admin addresses secure
   - Implement a multi-sig wallet as an admin for additional security
   - Maintain an off-chain record of role assignments

4. **Monitoring**:
   - Monitor the `RoleSet` events to track permission changes
   - Regularly audit the enabled addresses list
   - Keep documentation of why each address was granted permissions

You can find the implementations in the subnet-evm repository:
- [Contract Deployer Allowlist](https://github.com/ava-labs/subnet-evm/blob/master/precompile/contracts/deployerallowlist/contract.go)
- [Transaction Allowlist](https://github.com/ava-labs/subnet-evm/blob/master/precompile/contracts/txallowlist/contract.go) 

# Precompile Upgrades (/docs/avalanche-l1s/evm-configuration/precompile-upgrades)

---
title: Precompile Upgrades
description: Learn how to enable, disable, and configure precompiles in your Subnet-EVM.
---

# Precompile Upgrades

<Callout type="warn">
Performing a network upgrade requires coordinating the upgrade network-wide. A network upgrade changes the rule set used to process and verify blocks, such that any node that upgrades incorrectly or fails to upgrade by the time that upgrade goes into effect may become out of sync with the rest of the network.

Any mistakes in configuring network upgrades or coordinating them on validators may cause the network to halt and recovering may be difficult.
</Callout>

Subnet-EVM precompiles can be individually enabled or disabled at a given timestamp as a network upgrade. When disabling a precompile, it disables calling the precompile and destructs its storage, allowing it to be enabled later with a new configuration if desired.

## Configuration File

These upgrades must be specified in a file named `upgrade.json` placed in the same directory where `config.json` resides: `{chain-config-dir}/{blockchainID}/upgrade.json`. For example, `WAGMI Subnet` upgrade should be placed in `~/.avalanchego/configs/chains/2ebCneCbwthjQ1rYT41nhd7M76Hc6YmosMAQrTFhBq8qeqh6tt/upgrade.json`.

The content of the `upgrade.json` should be formatted according to the following:

```json
{
  "precompileUpgrades": [
    {
      "[PRECOMPILE_NAME]": {
        "blockTimestamp": "[ACTIVATION_TIMESTAMP]", // unix timestamp precompile should activate at
        "[PARAMETER]": "[VALUE]" // precompile specific configuration options, eg. "adminAddresses"
      }
    }
  ]
}
```

<Callout type="warn">
An invalid `blockTimestamp` in an upgrade file results the update failing. The `blockTimestamp` value should be set to a valid Unix timestamp value which is in the _future_ relative to the _head of the chain_. If the node encounters a `blockTimestamp` which is in the past, it will fail on startup.
</Callout>

## Disabling Precompiles

To disable a precompile, use the following format:

```json
{
  "precompileUpgrades": [
    {
      "<precompileName>": {
        "blockTimestamp": "[DEACTIVATION_TIMESTAMP]", // unix timestamp the precompile should deactivate at
        "disable": true
      }
    }
  ]
}
```

Each item in `precompileUpgrades` must specify exactly one precompile to enable or disable and the block timestamps must be in increasing order. Once an upgrade has been activated (a block after the specified timestamp has been accepted), it must always be present in `upgrade.json` exactly as it was configured at the time of activation (otherwise the node will refuse to start).

<Callout type="warn">
For safety, you should always treat `precompileUpgrades` as append-only.

As a last resort measure, it is possible to abort or reconfigure a precompile upgrade that has not been activated since the chain is still processing blocks using the prior rule set.
</Callout>

If aborting an upgrade becomes necessary, you can remove the precompile upgrade from `upgrade.json` from the end of the list of upgrades. As long as the blockchain has not accepted a block with a timestamp past that upgrade's timestamp, it will abort the upgrade for that node.

## Example Configuration

Here's a complete example that demonstrates enabling and disabling precompiles:

```json
{
  "precompileUpgrades": [
    {
      "feeManagerConfig": {
        "blockTimestamp": 1668950000,
        "adminAddresses": ["0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC"]
      }
    },
    {
      "txAllowListConfig": {
        "blockTimestamp": 1668960000,
        "adminAddresses": ["0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC"]
      }
    },
    {
      "feeManagerConfig": {
        "blockTimestamp": 1668970000,
        "disable": true
      }
    }
  ]
}
```

This example:
1. Enables the `feeManagerConfig` at timestamp `1668950000`
2. Enables `txAllowListConfig` at timestamp `1668960000`
3. Disables `feeManagerConfig` at timestamp `1668970000`

## Initial Precompile Configurations

Precompiles can be managed by privileged addresses to change their configurations and activate their effects. For example, the `feeManagerConfig` precompile can have `adminAddresses` which can change the fee structure of the network:

```json
{
  "precompileUpgrades": [
    {
      "feeManagerConfig": {
        "blockTimestamp": 1668950000,
        "adminAddresses": ["0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC"]
      }
    }
  ]
}
```

In this example, only the specified address can change the network's fee structure. The admin must call the precompile to activate changes by sending a transaction with a new fee config.

### Initial Configurations Without Admin

Precompiles can also activate their effect immediately at the activation timestamp without admin addresses. For example:

```json
{
  "precompileUpgrades": [
    {
      "feeManagerConfig": {
        "blockTimestamp": 1668950000,
        "initialFeeConfig": {
          "gasLimit": 20000000,
          "targetBlockRate": 2,
          "minBaseFee": 1000000000,
          "targetGas": 100000000,
          "baseFeeChangeDenominator": 48,
          "minBlockGasCost": 0,
          "maxBlockGasCost": 10000000,
          "blockGasCostStep": 500000
        }
      }
    }
  ]
}
```

<Callout title="Note">
It's still possible to add `adminAddresses` or `enabledAddresses` along with these initial configurations. In this case, the precompile will be activated with the initial configuration, and admin/enabled addresses can access to the precompiled contract normally.
</Callout>

<Callout title="Note">
If you want to change the precompile initial configuration, you will need to first disable it then activate the precompile again with the new configuration.
</Callout>

## Verifying Upgrades

After creating or modifying `upgrade.json`, restart your node to load the changes. The node will print the chain configuration on startup, allowing you to verify the upgrade configuration:

```bash
INFO [08-15|15:09:36.772] <2ebCneCbwthjQ1rYT41nhd7M76Hc6YmosMAQrTFhBq8qeqh6tt Chain>
github.com/ava-labs/subnet-evm/eth/backend.go:155: Initialised chain configuration
config="{ChainID: 11111 Homestead: 0 EIP150: 0 EIP155: 0 EIP158: 0 Byzantium: 0
Constantinople: 0 Petersburg: 0 Istanbul: 0, Muir Glacier: 0, Subnet EVM: 0, FeeConfig:
{\"gasLimit\":20000000,\"targetBlockRate\":2,\"minBaseFee\":1000000000,\"targetGas\
":100000000,\"baseFeeChangeDenominator\":48,\"minBlockGasCost\":0,\"maxBlockGasCost\
":10000000,\"blockGasCostStep\":500000}, AllowFeeRecipients: false, NetworkUpgrades: {\
"subnetEVMTimestamp\":0}, PrecompileUpgrade: {}, UpgradeConfig: {\"precompileUpgrades\":[{\"feeManagerConfig\":{\"adminAddresses\":[\"0x8db97c7cece249c2b98bdc0226cc4c2a57bf52fc\"],\"enabledAddresses\":null,\"blockTimestamp\":1668950000}},{\"txAllowListConfig\":{\"adminAddresses\":[\"0x8db97c7cece249c2b98bdc0226cc4c2a57bf52fc\"],\"enabledAddresses\":null,\"blockTimestamp\":1668960000}},{\"feeManagerConfig\":{\"adminAddresses\":null,\"enabledAddresses\":null,\"blockTimestamp\":1668970000,\"disable\":true}}]}, Engine: Dummy Consensus Engine}"
```

You can also verify precompile configurations using:
- [`eth_getActiveRulesAt`](/docs/api-reference/subnet-evm-api#eth_getactiverulesat) RPC method to check activated precompiles at a timestamp
- [`eth_getChainConfig`](/docs/api-reference/subnet-evm-api#eth_getchainconfig) RPC method to view the complete configuration including upgrades 


# Tokenomics (/docs/avalanche-l1s/evm-configuration/tokenomics)

---
title: Tokenomics
description: Configure and manage the native token supply of your Avalanche L1 blockchain.
---

## Overview

The tokenomics of your Avalanche L1 blockchain is a crucial aspect that determines how value flows through your network. The Subnet-EVM provides powerful tools to manage your token economy:

- Initial token allocation in genesis
- Dynamic token minting through the Native Minter precompile
- Fee burning or redistribution mechanisms (via [Transaction Fees & Gas](/docs/avalanche-l1s/evm-configuration/transaction-fees))

## Initial Token Supply

When creating your Avalanche L1, you can configure the initial token distribution in the genesis file:

```json
{
  "alloc": {
    "0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC": {
      "balance": "0x3635C9ADC5DEA00000" // 1000 tokens (in wei)
    },
    "0x1234567890123456789012345678901234567890": {
      "balance": "0x21E19E0C9BAB2400000" // 10000 tokens (in wei)
    }
  }
}
```

Consider the following when planning initial allocation:

- Reserve tokens for validator rewards
- Allocate tokens for development and ecosystem growth
- Set aside tokens for future community initiatives
- Consider vesting schedules for team allocations

## Native Minter

### Purpose
The Native Minter precompile allows authorized addresses to mint additional tokens after network launch. This is useful for:

- Implementing programmatic token emission schedules
- Providing validator rewards
- Supporting ecosystem growth initiatives
- Implementing monetary policy

### Configuration
Located at address `0x0200000000000000000000000000000000000001`, you can activate this precompile in your genesis file:

```json
{
  "config": {
    "contractNativeMinterConfig": {
      "blockTimestamp": 0,
      "adminAddresses": ["0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC"]
    }
  }
}
```

### Interface

```solidity
//SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;
 
interface INativeMinter {
  event NativeCoinMinted(address indexed sender, address indexed recipient, uint256 amount);
  // Mint [amount] number of native coins and send to [addr]
  function mintNativeCoin(address addr, uint256 amount) external;
 
  // IAllowList
  event RoleSet(uint256 indexed role, address indexed account, address indexed sender, uint256 oldRole);
 
  // Set [addr] to have the admin role over the precompile contract.
  function setAdmin(address addr) external;
 
  // Set [addr] to be enabled on the precompile contract.
  function setEnabled(address addr) external;
 
  // Set [addr] to have the manager role over the precompile contract.
  function setManager(address addr) external;
 
  // Set [addr] to have no role for the precompile contract.
  function setNone(address addr) external;
 
  // Read the status of [addr].
  function readAllowList(address addr) external view returns (uint256 role);
}
```

The Native Minter precompile uses the [AllowList interface](/docs/avalanche-l1s/evm-configuration/allowlist) to restrict access to its functionality with the following roles.

## Tokenomics Best Practices

1. **Initial Distribution**:
   - Ensure fair distribution among stakeholders
   - Reserve sufficient tokens for network operation
   - Consider long-term sustainability
   - Document allocation rationale

2. **Minting Policy**:
   - Define clear minting guidelines
   - Use multi-sig for admin control
   - Implement transparent emission schedules
   - Monitor total supply changes

3. **Supply Management**:
   - Balance minting with burning mechanisms
   - Consider implementing supply caps
   - Monitor token velocity and distribution
   - Plan for long-term sustainability

4. **Security Considerations**:
   - Use multi-sig wallets for admin addresses
   - Implement time-locks for large mints
   - Regular audits of minting activity
   - Monitor for unusual minting patterns

5. **Validator Incentives**:
   - Design sustainable reward mechanisms
   - Balance inflation with network security
   - Consider validator stake requirements
   - Plan for long-term validator participation

## Example Implementations

### Fixed Supply with Emergency Minting

```json
{
  "config": {
    "contractNativeMinterConfig": {
      "blockTimestamp": 0,
      "adminAddresses": ["MULTISIG_ADDRESS"],
      "enabledAddresses": []
    }
  },
  "alloc": {
    "TREASURY": {"balance": "TOTAL_SUPPLY"},
    "VALIDATOR_REWARDS": {"balance": "VALIDATOR_ALLOCATION"},
    "ECOSYSTEM_FUND": {"balance": "ECOSYSTEM_ALLOCATION"}
  }
}
```

### Programmatic Emission Schedule

```solidity
contract EmissionSchedule {
    INativeMinter public constant NATIVE_MINTER = INativeMinter(0x0200000000000000000000000000000000000001);
    uint256 public constant EMISSION_RATE = 1000 * 1e18; // 1000 tokens per day
    uint256 public constant EMISSION_DURATION = 365 days;
    uint256 public immutable startTime;

    constructor() {
        startTime = block.timestamp;
    }

    function mintDailyEmission() external {
        require(block.timestamp < startTime + EMISSION_DURATION, "Emission ended");
        NATIVE_MINTER.mintNativeCoin(address(this), EMISSION_RATE);
        // Distribution logic here
    }
}
```

### Validator Reward Contract

```solidity
contract ValidatorRewards {
    INativeMinter public constant NATIVE_MINTER = INativeMinter(0x0200000000000000000000000000000000000001);
    uint256 public constant REWARD_RATE = 10 * 1e18; // 10 tokens per block

    function distributeRewards(address[] calldata validators) external {
        uint256 reward = REWARD_RATE / validators.length;
        for (uint i = 0; i < validators.length; i++) {
            NATIVE_MINTER.mintNativeCoin(validators[i], reward);
        }
    }
}
```

You can find the Native Minter implementation in the [subnet-evm repository](https://github.com/ava-labs/subnet-evm/blob/master/precompile/contracts/nativeminter/contract.go). 

# Transaction Fees & Validator Rewards (/docs/avalanche-l1s/evm-configuration/transaction-fees)

---
title: Transaction Fees & Validator Rewards
description: Configure fee parameters and reward mechanisms for your Avalanche L1 blockchain.
---

## Overview

The Subnet-EVM provides two powerful precompiles for managing transaction fees and rewards:

- **Fee Manager**: Configure dynamic fee parameters and gas costs
- **Reward Manager**: Control how transaction fees are distributed or burned

Both precompiles use the [AllowList interface](/docs/avalanche-l1s/evm-configuration/allowlist) to restrict access to their functionality.

## Fee Manager

### Purpose
The Fee Manager allows you to configure the parameters of the dynamic fee algorithm on-chain. This gives you control over:

- Gas limits and target block rates
- Base fee parameters
- Block gas cost parameters

### Configuration
Located at address `0x0200000000000000000000000000000000000003`, you can activate this precompile in your genesis file:

```json
{
  "config": {
    "feeManagerConfig": {
      "blockTimestamp": 0,
      "adminAddresses": ["0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC"],
      "initialFeeConfig": {
        "gasLimit": 20000000,
        "targetBlockRate": 2,
        "minBaseFee": 1000000000,
        "targetGas": 100000000,
        "baseFeeChangeDenominator": 48,
        "minBlockGasCost": 0,
        "maxBlockGasCost": 10000000,
        "blockGasCostStep": 500000
      }
    }
  }
}
```

### Fee Parameters

The Fee Manager allows configuration of the following parameters:

| Parameter | Description | Recommended Range |
|-----------|-------------|------------------|
| gasLimit | Maximum gas allowed per block | 8M - 100M |
| targetBlockRate | Target time between blocks (seconds) | 2 - 10 |
| minBaseFee | Minimum base fee (in wei) | 25 - 500 gwei |
| targetGas | Target gas spending over the last 10 seconds | 5M - 50M |
| baseFeeChangeDenominator | Controls how quickly base fee changes | 8 - 1000 |
| minBlockGasCost | Minimum gas cost for a block | 0 - 1B |
| maxBlockGasCost | Maximum gas cost for a block | > minBlockGasCost |
| blockGasCostStep | How quickly block gas cost changes | < 5M |

### Access Control and Additional Features

The FeeManager precompile uses the [AllowList interface](/docs/avalanche-l1s/evm-configuration/allowlist) to restrict access to its functionality.

In addition to the AllowList interface, the FeeManager adds the following capabilities:

- `getFeeConfig`: retrieves the current dynamic fee config
- `getFeeConfigLastChangedAt`: retrieves the timestamp of the last block where the fee config was updated
- `setFeeConfig`: sets the dynamic fee config on chain. This function can only be called by an Admin, Manager or Enabled address.
- `FeeConfigChanged`: an event that is emitted when the fee config is updated. Topics include the sender, the old fee config, and the new fee config.

You can also get the fee configuration at a block with the `eth_feeConfig` RPC method. For more information see [here](/docs/api-reference/subnet-evm-api#eth_feeconfig).

## Reward Manager

### Purpose
The Reward Manager allows you to control how transaction fees are handled in your network. You can:

- Send fees to a specific address (e.g., treasury)
- Allow validators to collect fees
- Burn fees entirely

### Configuration
Located at address `0x0200000000000000000000000000000000000004`, you can activate this precompile in your genesis file:

```json
{
  "config": {
    "rewardManagerConfig": {
      "blockTimestamp": 0,
      "adminAddresses": ["0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC"],
      "initialRewardConfig": {
        // Choose one of:
        "allowFeeRecipients": true,  // Allow validators to collect fees
        "rewardAddress": "0x...",    // Send fees to specific address
        // Empty config = burn fees
      }
    }
  }
}
```

### Reward Mechanisms

The Reward Manager supports three mutually exclusive mechanisms:

1. **Validator Fee Collection** (`allowFeeRecipients`)
   - Validators can specify their own fee recipient addresses
   - Fees go to the block producer's chosen address
   - Good for incentivizing network participation

2. **Fixed Reward Address** (`rewardAddress`)
   - All fees go to a single specified address
   - Can be a contract or EOA
   - Useful for treasury or DAO-controlled fee collection

3. **Fee Burning** (default)
   - All transaction fees are burned
   - Reduces total token supply over time
   - Similar to Ethereum's EIP-1559

## Implementation

### Fee Manager Interface

```solidity
interface IFeeManager {
  struct FeeConfig {
    uint256 gasLimit;
    uint256 targetBlockRate;
    uint256 minBaseFee;
    uint256 targetGas;
    uint256 baseFeeChangeDenominator;
    uint256 minBlockGasCost;
    uint256 maxBlockGasCost;
    uint256 blockGasCostStep;
  }
  
  event FeeConfigChanged(address indexed sender, FeeConfig oldFeeConfig, FeeConfig newFeeConfig);

  function setFeeConfig(
    uint256 gasLimit,
    uint256 targetBlockRate,
    uint256 minBaseFee,
    uint256 targetGas,
    uint256 baseFeeChangeDenominator,
    uint256 minBlockGasCost,
    uint256 maxBlockGasCost,
    uint256 blockGasCostStep
  ) external;

  function getFeeConfig() external view returns (
    uint256 gasLimit,
    uint256 targetBlockRate,
    uint256 minBaseFee,
    uint256 targetGas,
    uint256 baseFeeChangeDenominator,
    uint256 minBlockGasCost,
    uint256 maxBlockGasCost,
    uint256 blockGasCostStep
  );

  function getFeeConfigLastChangedAt() external view returns (uint256 blockNumber);
}
```

### Reward Manager Interface

```solidity
interface IRewardManager {
  event RewardAddressChanged(
    address indexed sender,
    address indexed oldRewardAddress,
    address indexed newRewardAddress
  );
  event FeeRecipientsAllowed(address indexed sender);
  event RewardsDisabled(address indexed sender);

  function setRewardAddress(address addr) external;
  function allowFeeRecipients() external;
  function disableRewards() external;
  function currentRewardAddress() external view returns (address rewardAddress);
  function areFeeRecipientsAllowed() external view returns (bool isAllowed);
}
```

## Best Practices

1. **Reward Management**:
   - Choose reward mechanism based on network goals
   - Consider using a multi-sig or DAO as reward address
   - Monitor fee collection and distribution
   - Keep documentation of fee policy changes

2. **Security Considerations**:
   - Use multi-sig for admin addresses
   - Test fee changes on testnet first
   - Monitor events for unauthorized changes
   - Have a plan for fee parameter adjustments

You can find the implementations in the subnet-evm repository:
- [Fee Manager](https://github.com/ava-labs/subnet-evm/blob/master/precompile/contracts/feemanager/contract.go)
- [Reward Manager](https://github.com/ava-labs/subnet-evm/blob/master/precompile/contracts/rewardmanager/contract.go) 

# WarpMessenger Precompile - Technical Details (/docs/avalanche-l1s/evm-configuration/warpmessenger)

---
title: "WarpMessenger Precompile - Technical Details"
description: "Technical documentation for the WarpMessenger precompile implementation in subnet-evm."
edit_url: https://github.com/ava-labs/subnet-evm/1ab7114c339f866b65cc02dfd586b2ed9041dd0b/precompile/contracts/warp/README.md
---

# Integrating Avalanche Warp Messaging into the EVM

Avalanche Warp Messaging offers a basic primitive to enable Cross-L1 communication on the Avalanche Network.

It is intended to allow communication between arbitrary Custom Virtual Machines (including, but not limited to Subnet-EVM and Coreth).

## How does Avalanche Warp Messaging Work?

Avalanche Warp Messaging uses BLS Multi-Signatures with Public-Key Aggregation where every Avalanche validator registers a public key alongside its NodeID on the Avalanche P-Chain.

Every node tracking an Avalanche L1 has read access to the Avalanche P-Chain. This provides weighted sets of BLS Public Keys that correspond to the validator sets of each L1 on the Avalanche Network. Avalanche Warp Messaging provides a basic primitive for signing and verifying messages between L1s: the receiving network can verify whether an aggregation of signatures from a set of source L1 validators represents a threshold of stake large enough for the receiving network to process the message.

For more details on Avalanche Warp Messaging, see the AvalancheGo [Warp README](https://docs.avax.network/build/cross-chain/awm/deep-dive).

### Flow of Sending / Receiving a Warp Message within the EVM

The Avalanche Warp Precompile enables this flow to send a message from blockchain A to blockchain B:

1. Call the Warp Precompile `sendWarpMessage` function with the arguments for the `UnsignedMessage`
2. Warp Precompile emits an event / log containing the `UnsignedMessage` specified by the caller of `sendWarpMessage`
3. Network accepts the block containing the `UnsignedMessage` in the log, so that validators are willing to sign the message
4. An off-chain relayer queries the validators for their signatures of the message and aggregates the signatures to create a `SignedMessage`
5. The off-chain relayer encodes the `SignedMessage` as the [predicate](#predicate-encoding) in the AccessList of a transaction to deliver on blockchain B
6. The transaction is delivered on blockchain B, the signature is verified prior to executing the block, and the message is accessible via the Warp Precompile's `getVerifiedWarpMessage` during the execution of that transaction

### Warp Precompile

The Warp Precompile is broken down into three functions defined in the Solidity interface file [here](https://github.com/ava-labs/subnet-evm/blob/1ab7114c339f866b65cc02dfd586b2ed9041dd0b/contracts/contracts/interfaces/IWarpMessenger.sol).

#### sendWarpMessage

`sendWarpMessage` is used to send a verifiable message. Calling this function results in sending a message with the following contents:

- `SourceChainID` - blockchainID of the sourceChain on the Avalanche P-Chain
- `SourceAddress` - `msg.sender` encoded as a 32 byte value that calls `sendWarpMessage`
- `Payload` - `payload` argument specified in the call to `sendWarpMessage` emitted as the unindexed data of the resulting log

Calling this function will issue a `SendWarpMessage` event from the Warp Precompile. Since the EVM limits the number of topics to 4 including the EventID, this message includes only the topics that would be expected to help filter messages emitted from the Warp Precompile the most.

Specifically, the `payload` is not emitted as a topic because each topic must be encoded as a hash. Therefore, we opt to take advantage of each possible topic to maximize the possible filtering for emitted Warp Messages.

Additionally, the `SourceChainID` is excluded because anyone parsing the chain can be expected to already know the blockchainID. Therefore, the `SendWarpMessage` event includes the indexable attributes:

- `sender`
- The `messageID` of the unsigned message (sha256 of the unsigned message)

The actual `message` is the entire [Avalanche Warp Unsigned Message](https://github.com/ava-labs/avalanchego/blob/master/vms/platformvm/warp/unsigned_message.go#L14) including an [AddressedCall](https://github.com/ava-labs/avalanchego/tree/master/vms/platformvm/warp/payload#readme). The unsigned message is emitted as the unindexed data in the log.

#### getVerifiedMessage

`getVerifiedMessage` is used to read the contents of the delivered Avalanche Warp Message into the expected format.

It returns the message if present and a boolean indicating if a message is present.

To use this function, the transaction must include the signed Avalanche Warp Message encoded in the [predicate](#predicate-encoding) of the transaction. Prior to executing a block, the VM iterates through transactions and pre-verifies all predicates. If a transaction's predicate is invalid, then it is considered invalid to include in the block and dropped.

This leads to the following advantages:

1. The EVM execution does not need to verify the Warp Message at runtime (no signature verification or external calls to the P-Chain)
2. The EVM can deterministically re-execute and re-verify blocks assuming the predicate was verified by the network (e.g., in bootstrapping)

This pre-verification is performed using the ProposerVM Block header during [block verification](https://github.com/ava-labs/subnet-evm/blob/1ab7114c339f866b65cc02dfd586b2ed9041dd0b/plugin/evm/block.go#L220) and [block building](https://github.com/ava-labs/subnet-evm/blob/1ab7114c339f866b65cc02dfd586b2ed9041dd0b/miner/worker.go#L200).

#### getBlockchainID

`getBlockchainID` returns the blockchainID of the blockchain that the VM is running on.

This is different from the conventional Ethereum ChainID registered to [ChainList](https://chainlist.org/).

The `blockchainID` in Avalanche refers to the txID that created the blockchain on the Avalanche P-Chain ([docs](https://docs.avax.network/specs/platform-transaction-serialization#unsigned-create-chain-tx)).

### Predicate Encoding

Avalanche Warp Messages are encoded as a signed Avalanche [Warp Message](https://github.com/ava-labs/avalanchego/blob/master/vms/platformvm/warp/message.go) where the [UnsignedMessage](https://github.com/ava-labs/avalanchego/blob/master/vms/platformvm/warp/unsigned_message.go)'s payload includes an [AddressedPayload](https://github.com/ava-labs/avalanchego/blob/master/vms/platformvm/warp/payload/payload.go).

Since the predicate is encoded into the [Transaction Access List](https://eips.ethereum.org/EIPS/eip-2930), it is packed into 32 byte hashes intended to declare storage slots that should be pre-warmed into the cache prior to transaction execution.

Therefore, we use the [Predicate Utils](https://github.com/ava-labs/subnet-evm/blob/master/predicate/Predicate.md) package to encode the actual byte slice of size N into the access list.

### Performance Optimization: Primary Network to Avalanche L1

The Primary Network has a large validator set compared to most Subnets and L1s, which makes Warp signature collection and verification from the entire Primary Network validator set costly. All Subnets and L1s track at least one blockchain of the Primary Network, so we can instead optimize this by using the validator set of the receiving L1 instead of the Primary Network for certain Warp messages.

#### Subnets

Recall that Avalanche Subnet validators must also validate the Primary Network, so it tracks all of the blockchains in the Primary Network (X, C, and P-Chains).

When an Avalanche Subnet receives a message from a blockchain on the Primary Network, we use the validator set of the receiving Subnet instead of the entire network when validating the message. 

Sending messages from the X, C, or P-Chain remains unchanged.
However, when the Subnet receives the message, it changes the semantics to the following:

1. Read the `SourceChainID` of the signed message
2. Look up the `SubnetID` that validates `SourceChainID`. In this case it will be the Primary Network's `SubnetID`
3. Look up the validator set of the Subnet (instead of the Primary Network) and the registered BLS Public Keys of the Subnet validators at the P-Chain height specified by the ProposerVM header
4. Continue Warp Message verification using the validator set of the Subnet instead of the Primary Network

This means that Primary Network to Subnet communication only requires a threshold of stake on the receiving Subnet to sign the message instead of a threshold of stake for the entire Primary Network.

Since the security of the Subnet is provided by trust in its validator set, requiring a threshold of stake from the receiving Subnet's validator set instead of the whole Primary Network does not meaningfully change the security of the receiving L1.

Note: this special case is ONLY applied during Warp Message verification. The message sent by the Primary Network will still contain the blockchainID of the Primary Network chain that sent the message as the sourceChainID and signatures will be served by querying the source chain directly.

#### L1s

Avalanche L1s are only required to sync the P-Chain, but are not required to validate the Primary Network. Therefore, **for L1s, this optimization only applies to Warp messages sent by the P-Chain.** The rest of the description of this optimization in the above section applies to L1s.

Note that **in order to properly verify messages from the C-Chain and X-Chain, the Warp precompile must be configured with `requirePrimaryNetworkSigners` set to `true`**. Otherwise, we will attempt to verify the message signature against the receiving L1's validator set, which is not required to track the C-Chain or X-Chain, and therefore will not in general be able to produce a valid Warp message.

## Design Considerations

### Re-Processing Historical Blocks

Avalanche Warp Messaging depends on the Avalanche P-Chain state at the P-Chain height specified by the ProposerVM block header.

Verifying a message requires looking up the validator set of the source L1 on the P-Chain. To support this, Avalanche Warp Messaging uses the ProposerVM header, which includes the P-Chain height it was issued at as the canonical point to lookup the source L1's validator set.

This means verifying the Warp Message and therefore the state transition on a block depends on state that is external to the blockchain itself: the P-Chain.

The Avalanche P-Chain tracks only its current state and reverse diff layers (reversing the changes from past blocks) in order to re-calculate the validator set at a historical height. This means calculating a very old validator set that is used to verify a Warp Message in an old block may become prohibitively expensive.

Therefore, we need a heuristic to ensure that the network can correctly re-process old blocks (note: re-processing old blocks is a requirement to perform bootstrapping and is used in some VMs to serve or verify historical data).

As a result, we require that the block itself provides a deterministic hint which determines which Avalanche Warp Messages were considered valid/invalid during the block's execution. This ensures that we can always re-process blocks and use the hint to decide whether an Avalanche Warp Message should be treated as valid/invalid even after the P-Chain state that was used at the original execution time may no longer support fast lookups.

To provide that hint, we've explored two designs:

1. Include a predicate in the transaction to ensure any referenced message is valid
2. Append the results of checking whether a Warp Message is valid/invalid to the block data itself

The current implementation uses option (1).

The original reason for this was that the notion of predicates for precompiles was designed with Shared Memory in mind. In the case of shared memory, there is no canonical "P-Chain height" in the block which determines whether or not Avalanche Warp Messages are valid.

Instead, the VM interprets a shared memory import operation as valid as soon as the UTXO is available in shared memory. This means that if it were up to the block producer to staple the valid/invalid results of whether or not an attempted atomic operation should be treated as valid, a byzantine block producer could arbitrarily report that such atomic operations were invalid and cause a griefing attack to burn the gas of users that attempted to perform an import.

Therefore, a transaction specified predicate is required to implement the shared memory precompile to prevent such a griefing attack.

In contrast, Avalanche Warp Messages are validated within the context of an exact P-Chain height. Therefore, if a block producer attempted to lie about the validity of such a message, the network would interpret that block as invalid.

### Guarantees Offered by Warp Precompile vs. Built on Top

#### Guarantees Offered by Warp Precompile

The Warp Precompile was designed with the intention of minimizing the trusted computing base for the VM as much as possible. Therefore, it makes several tradeoffs which encourage users to use protocols built ON TOP of the Warp Precompile itself as opposed to directly using the Warp Precompile.

The Warp Precompile itself provides ONLY the following ability:

- Emit a verifiable message from (Address A, Blockchain A) to (Address B, Blockchain B) that can be verified by the destination chain

#### Explicitly Not Provided / Built on Top

The Warp Precompile itself does not provide any guarantees of:

- Eventual message delivery (may require re-send on blockchain A and additional assumptions about off-chain relayers and chain progress)
- Ordering of messages (requires ordering provided a layer above)
- Replay protection (requires replay protection provided a layer above)

# Considerations (/docs/avalanche-l1s/upgrade/considerations)

---
title: Considerations
description: Learn about some of the key considerations while upgrading your Avalanche L1.
---

In the course of Avalanche L1 operation, you will inevitably need to upgrade or change some part of the software stack that is running your Avalanche L1. If nothing else, you will have to upgrade the AvalancheGo node client. Same goes for the VM plugin binary that is used to run the blockchain on your Avalanche L1, which is most likely the [Subnet-EVM](https://github.com/ava-labs/subnet-evm), the Avalanche L1 implementation of the Ethereum virtual machine.

Node and VM upgrades usually don't change the way your Avalanche L1 functions, instead they keep your Avalanche L1 in sync with the rest of the network, bringing security, performance and feature upgrades. Most upgrades are optional, but all of them are recommended, and you should make optional upgrades part of your routine Avalanche L1 maintenance. Some upgrades will be mandatory, and those will be clearly communicated as such ahead of time, you need to pay special attention to those.

Besides the upgrades due to new releases, you also may want to change the configuration of the VM, to alter the way Avalanche L1 runs, for various business or operational needs. These upgrades are solely the purview of your team, and you have complete control over the timing of their roll out. Any such change represents a **network upgrade** and needs to be carefully planned and executed.

<Callout type="warn">
Network Upgrades Permanently Change the Rules of Your Avalanche L1. Procedural mistakes or a botched upgrade can halt your Avalanche L1 or lead to data loss!

When performing an Avalanche L1 upgrade, every single validator on the Avalanche L1 will need to perform the identical upgrade.

If you are coordinating a network upgrade, you must schedule advance notice to every Avalanche L1 validator so that they have time to perform the upgrade prior to activation. Make sure you have direct line of communication to all your validators!
</Callout>

This tutorial will guide you through the process of doing various Avalanche L1 upgrades and changes. We will point out things to watch out for and precautions you need to be mindful about.

General Upgrade Considerations[​](#general-upgrade-considerations "Direct link to heading")
-------------------------------------------------------------------------------------------

When operating an Avalanche L1, you should always keep in mind that Proof of Stake networks like Avalanche can only make progress if sufficient amount of validating nodes are connected and processing transactions. Each validator on an Avalanche L1 is assigned a certain `weight`, which is a numerical value representing the significance of the node in consensus decisions. On the Primary Network, weight is equal to the amount of AVAX staked on the node. On Avalanche L1s, weight is currently assigned by the Avalanche L1 owners when they issue the transaction adding a validator to the Avalanche L1.

Avalanche L1s can operate normally only if validators representing 80% or more of the cumulative validator weight is connected. If the amount of connected stake falls close to or below 80%, Avalanche L1 performance (time to finality) will suffer, and ultimately the Avalanche L1 will halt (stop processing transactions).

You as an Avalanche L1 operator need to ensure that whatever you do, at least 80% of the validators' cumulative weight is connected and working at all times.

<Callout title="Note">
It is mandatory that the cumulative weight of all validators in the Avalanche L1 must be at least the value of [`snow-sample-size`](/docs/nodes/configure/configs-flags#--snow-sample-size-int) (default 20). For example, if there is only one validator in the Avalanche L1, its weight must be at least `snow-sample-size` . Hence, when assigning weight to the nodes, always use values greater than 20. Recall that a validator's weight can't be changed while it is validating, so take care to use an appropriate value.
</Callout>

Upgrading Avalanche L1 Validator Nodes[​](#upgrading-avalanche-l1-validator-nodes "Direct link to heading")
-----------------------------------------------------------------------------------------------

AvalancheGo, the node client that is running the Avalanche validators is under constant and rapid development. New versions come out often (roughly every two weeks), bringing added capabilities, performance improvements or security fixes. Updates are usually optional, but from time to time (much less frequently than regular updates) there will be an update that includes a mandatory network upgrade. Those upgrades are **MANDATORY** for every node running the Avalanche L1. Any node that does not perform the update before the activation timestamp will immediately stop working when the upgrade activates.

That's why having a node upgrade strategy is absolutely vital, and you should always update to the latest AvalancheGo client immediately when it is made available.

For a general guide on upgrading AvalancheGo check out [this tutorial](/docs/nodes/maintain/upgrade). When upgrading Avalanche L1 nodes and keeping in mind the previous section, make sure to stagger node upgrades and start a new upgrade only once the previous node has successfully upgraded. Use the [Health API](/docs/api-reference/health-api#healthhealth) to check that `healthy` value in the response is `true` on the upgraded node, and on other Avalanche L1 validators check that [platform.getCurrentValidators()](/docs/api-reference/p-chain/api#platformgetcurrentvalidators) has `true` in `connected` attribute for the upgraded node's `nodeID`. Once those two conditions are satisfied, node is confirmed to be online and validating the Avalanche L1 and you can start upgrading another node.

Continue the upgrade cycle until all the Avalanche L1 nodes are upgraded.

Upgrading Avalanche L1 VM Plugin Binaries[​](#upgrading-avalanche-l1-vm-plugin-binaries "Direct link to heading")
-----------------------------------------------------------------------------------------------------

Besides the AvalancheGo client itself, new versions get released for the VM binaries that run the blockchains on the Avalanche L1. On most Avalanche L1s, that is the [Subnet-EVM](https://github.com/ava-labs/subnet-evm), so this tutorial will go through the steps for updating the `subnet-evm` binary. The update process will be similar for updating any VM plugin binary.

All the considerations for doing staggered node upgrades as discussed in previous section are valid for VM upgrades as well.

In the future, VM upgrades will be handled by the [Avalanche-CLI tool](https://github.com/ava-labs/avalanche-cli), but for now we need to do it manually.

Go to the [releases page](https://github.com/ava-labs/subnet-evm/releases) of the Subnet-EVM repository. Locate the latest version, and copy link that corresponds to the OS and architecture of the machine the node is running on (`darwin` = Mac, `amd64` = Intel/AMD processor, `arm64` = Arm processor). Log into the machine where the node is running and download the archive, using `wget` and the link to the archive, like this:

```bash
wget https://github.com/ava-labs/subnet-evm/releases/download/v0.2.9/subnet-evm_0.2.9_linux_amd64.tar.gz
```

This will download the archive to the machine. Unpack it like this (use the correct filename, of course):

```bash
tar xvf subnet-evm_0.2.9_linux_amd64.tar.gz
```

This will unpack and place the contents of the archive in the current directory, file `subnet-evm` is the plugin binary. You need to stop the node now (if the node is running as a service, use `sudo systemctl stop avalanchego` command). You need to place that file into the plugins directory where the AvalancheGo binary is located. If the node is installed using the install script, the path will be `~/avalanche-node/plugins` Instead of the `subnet-evm` filename, VM binary needs to be named as the VM ID of the chain on the Avalanche L1. For example, for the [WAGMI Avalanche L1](/docs/avalanche-l1s/wagmi-avalanche-l1) that VM ID is `srEXiWaHuhNyGwPUi444Tu47ZEDwxTWrbQiuD7FmgSAQ6X7Dy`. So, the command to copy the new plugin binary would look like:

```bash
cp subnet-evm ~/avalanche-node/plugins/srEXiWaHuhNyGwPUi444Tu47ZEDwxTWrbQiuD7FmgSAQ6X7Dy
```

<Callout type="warn">
Make sure you use the correct VM ID, otherwise, your VM will not get updated and your Avalanche L1 may halt.
</Callout>

After you do that, you can start the node back up (if running as service do `sudo systemctl start avalanchego`). You can monitor the log output on the node to check that everything is OK, or you can use the [info.getNodeVersion()](/docs/api-reference/info-api#infogetnodeversion) API to check the versions. Example output would look like:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "version": "avalanche/1.7.18",
    "databaseVersion": "v1.4.5",
    "gitCommit": "b6d5827f1a87e26da649f932ad649a4ea0e429c4",
    "vmVersions": {
      "avm": "v1.7.18",
      "evm": "v0.8.15",
      "platform": "v1.7.18",
      "sqja3uK17MJxfC7AN8nGadBw9JK5BcrsNwNynsqP5Gih8M5Bm": "v0.0.7",
      "srEXiWaHuhNyGwPUi444Tu47ZEDwxTWrbQiuD7FmgSAQ6X7Dy": "v0.2.9"
    }
  },
  "id": 1
}
```

Note that entry next to the VM ID we upgraded correctly says `v0.2.9`. You have successfully upgraded the VM!

Refer to the previous section on how to make sure node is healthy and connected before moving on to upgrading the next Avalanche L1 validator.

If you don't get the expected result, you can stop the `AvalancheGo`, examine and follow closely step-by-step of the above. You are free to remove files under `~/avalanche-node/plugins`, however, you should keep in mind that removing files is to remove an existing VM binary. You must put the correct VM plugin in place before you restart AvalancheGo.

Network Upgrades[​](#network-upgrades "Direct link to heading")
---------------------------------------------------------------

Sometimes you need to do a network upgrade to change the configured rules in the genesis under which the Chain operates. In regular EVM, network upgrades are a pretty involved process that includes deploying the new EVM binary, coordinating the timed upgrade and deploying changes to the nodes. But since [Subnet-EVM v0.2.8](https://github.com/ava-labs/subnet-evm/releases/tag/v0.2.8), we introduced the long awaited feature to perform network upgrades by just using a few lines of JSON. Upgrades can consist of enabling/disabling particular precompiles, or changing their parameters. Currently available precompiles allow you to:

- Restrict Smart Contract Deployers
- Restrict Who Can Submit Transactions
- Mint Native Coins
- Configure Dynamic Fees

Please refer to [Customize an Avalanche L1](/docs/avalanche-l1s/upgrade/customize-avalanche-l1#network-upgrades-enabledisable-precompiles) for a detailed discussion of possible precompile upgrade parameters.

Summary[​](#summary "Direct link to heading")
---------------------------------------------

Vital part of Avalanche L1 maintenance is performing timely upgrades at all levels of the software stack running your Avalanche L1. We hope this tutorial will give you enough information and context to allow you to do those upgrades with confidence and ease. If you have additional questions or any issues, please reach out to us on [Discord](https://chat.avalabs.org/).


# Customize an Avalanche L1 (/docs/avalanche-l1s/upgrade/customize-avalanche-l1)

---
title: Customize an Avalanche L1
description: Learn how to customize your EVM-powered Avalanche L1.
---

All Avalanche L1s can be customized by utilizing [`L1s Configs`](#avalanche-l1-configs).

an Avalanche L1 can have one or more blockchains. For example, the Primary Network, which is an Avalanche L1, a special one nonetheless, has 3 blockchains. Each chain can be further customized using chain specific configuration file. See [here](/docs/nodes/configure/configs-flags) for detailed explanation.

An Avalanche L1 created by or forked from [Subnet-EVM](https://github.com/ava-labs/subnet-evm) can be customized by utilizing one or more of the following methods:

- [Genesis](#genesis)
- [Precompile](#precompiles)
- [Upgrade Configs](#network-upgrades-enabledisable-precompiles)
- [Chain Configs](#avalanchego-chain-configs)

Avalanche L1 Configs[​](#avalanche-l1-configs "Direct link to heading")
-----------------------------------------------------------

an Avalanche L1 can customized by setting parameters for the following:

- [Validator-only communication to create a private Avalanche L1](/docs/nodes/configure/avalanche-l1-configs#validatoronly-bool)
- [Consensus](/docs/nodes/configure/avalanche-l1-configs#consensus-parameters)
- [Gossip](/docs/nodes/configure/avalanche-l1-configs#gossip-configs)

See [here](/docs/nodes/configure/avalanche-l1-configs) for more info.

Genesis[​](#genesis "Direct link to heading")
---------------------------------------------

Each blockchain has some genesis state when it's created. Each Virtual Machine defines the format and semantics of its genesis data.

The default genesis Subnet-EVM provided below has some well defined parameters:

```json
{
  "config": {
    "chainId": 43214,
    "homesteadBlock": 0,
    "eip150Block": 0,
    "eip150Hash": "0x2086799aeebeae135c246c65021c82b4e15a2c451340993aacfd2751886514f0",
    "eip155Block": 0,
    "eip158Block": 0,
    "byzantiumBlock": 0,
    "constantinopleBlock": 0,
    "petersburgBlock": 0,
    "istanbulBlock": 0,
    "muirGlacierBlock": 0,
    "feeConfig": {
      "gasLimit": 15000000,
      "minBaseFee": 25000000000,
      "targetGas": 15000000,
      "baseFeeChangeDenominator": 36,
      "minBlockGasCost": 0,
      "maxBlockGasCost": 1000000,
      "targetBlockRate": 2,
      "blockGasCostStep": 200000
    },
    "allowFeeRecipients": false
  },
  "alloc": {
    "8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC": {
      "balance": "0x295BE96E64066972000000"
    }
  },
  "nonce": "0x0",
  "timestamp": "0x0",
  "extraData": "0x00",
  "gasLimit": "0xe4e1c0",
  "difficulty": "0x0",
  "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
  "coinbase": "0x0000000000000000000000000000000000000000",
  "number": "0x0",
  "gasUsed": "0x0",
  "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000"
}
```

### Chain Config[​](#chain-config "Direct link to heading")

`chainID`: Denotes the ChainID of to be created chain. Must be picked carefully since a conflict with other chains can cause issues. One suggestion is to check with [chainlist.org](https://chainlist.org/) to avoid ID collision, reserve and publish your ChainID properly.

You can use `eth_getChainConfig` RPC call to get the current chain config. See [here](/docs/api-reference/subnet-evm-api#eth_getchainconfig) for more info.

#### Hard Forks[​](#hard-forks "Direct link to heading")

`homesteadBlock`, `eip150Block`, `eip150Hash`, `eip155Block`, `byzantiumBlock`, `constantinopleBlock`, `petersburgBlock`, `istanbulBlock`, `muirGlacierBlock` are EVM hard fork activation times. Changing these may cause issues, so treat them carefully.

#### Fee Config[​](#fee-config "Direct link to heading")

`gasLimit`: Sets the max amount of gas consumed per block. This restriction puts a cap on the amount of computation that can be done in a single block, which in turn sets a limit on the maximum gas usage allowed for a single transaction. For reference, C-Chain value is set to `15,000,000`.

`targetBlockRate`: Sets the target rate of block production in seconds. A target of 2 will target producing a block every 2 seconds. If the network starts producing blocks at a faster rate, it indicates that more blocks than anticipated are being issued to the network, resulting in an increase in base fees. For C-chain this value is set to `2`.

`minBaseFee`: Sets a lower bound on the EIP-1559 base fee of a block. Since the block's base fee sets the minimum gas price for any transaction included in that block, this effectively sets a minimum gas price for any transaction.

`targetGas`: Specifies the targeted amount of gas (including block gas cost) to consume within a rolling 10-seconds window. When the dynamic fee algorithm observes that network activity is above/below the `targetGas`, it increases/decreases the base fee proportionally to how far above/below the target actual network activity is. If the network starts producing blocks with gas cost higher than this, base fees are increased accordingly.

`baseFeeChangeDenominator`: Divides the difference between actual and target utilization to determine how much to increase/decrease the base fee. A larger denominator indicates a slower changing, stickier base fee, while a lower denominator allows the base fee to adjust more quickly. For reference, the C-chain value is set to `36`. This value sets the base fee to increase or decrease by a factor of `1/36` of the parent block's base fee.

`minBlockGasCost`: Sets the minimum amount of gas to charge for the production of a block. This value is set to `0` in C-Chain.

`maxBlockGasCost`: Sets the maximum amount of gas to charge for the production of a block.

`blockGasCostStep`: Determines how much to increase/decrease the block gas cost depending on the amount of time elapsed since the previous block.

If the block is produced at the target rate, the block gas cost will stay the same as the block gas cost for the parent block.

If it is produced faster/slower, the block gas cost will be increased/decreased by the step value for each second faster/slower than the target block rate accordingly.

<Callout title="Note">
If the `blockGasCostStep` is set to a very large number, it effectively requires block production to go no faster than the `targetBlockRate`. For example, if a block is produced two seconds faster than the target block rate, the block gas cost will increase by `2 * blockGasCostStep`.
</Callout>

#### Custom Fee Recipients[​](#custom-fee-recipients "Direct link to heading")

See section [Setting a Custom Fee Recipient](#setting-a-custom-fee-recipient)

### Alloc[​](#alloc "Direct link to heading")

The fields `nonce`, `timestamp`, `extraData`, `gasLimit`, `difficulty`, `mixHash`, `coinbase`, `number`, `gasUsed`, `parentHash` defines the genesis block header. The field `gasLimit` should be set to match the `gasLimit` set in the `feeConfig`. You do not need to change any of the other genesis header fields.

`nonce`, `mixHash` and `difficulty` are remnant parameters from Proof of Work systems. For Avalanche, these don't play any relevant role, so you should just leave them as their default values:

`nonce`: The result of the mining process iteration is this value. It can be any value in the genesis block. Default value is `0x0`.

`mixHash`: The combination of `nonce` and `mixHash` allows to verify that the Block has really been cryptographically mined, thus, from this aspect, is valid. Default value is `0x0000000000000000000000000000000000000000000000000000000000000000`.

`difficulty`: The difficulty level applied during the nonce discovering process of this block. Default value is `0x0`.

`timestamp`: The timestamp of the creation of the genesis block. This is commonly set to `0x0`.

`extraData`: Optional extra data that can be included in the genesis block. This is commonly set to `0x`.

`gasLimit`: The total amount of gas that can be used in a single block. It should be set to the same value as in the [fee config](#fee-config). The value `e4e1c0` is hexadecimal and is equal to `15,000,000`.

`coinbase`: Refers to the address of the block producers. This also means it represents the recipient of the block reward. It is usually set to `0x0000000000000000000000000000000000000000` for the genesis block. To allow fee recipients in Subnet-EVM, refer to [this section.](#setting-a-custom-fee-recipient)

`parentHash`: This is the Keccak 256-bit hash of the entire parent block's header. It is usually set to `0x0000000000000000000000000000000000000000000000000000000000000000` for the genesis block.

`gasUsed`: This is the amount of gas used by the genesis block. It is usually set to `0x0`.

`number`: This is the number of the genesis block. This required to be `0x0` for the genesis. Otherwise it will error.

### Genesis Examples[​](#genesis-examples "Direct link to heading")

Another example of a genesis file can be found in the [networks folder](https://github.com/ava-labs/public-chain-assets/blob/1951594346dcc91682bdd8929bcf8c1bf6a04c33/chains/11111/genesis.json). Please remove `airdropHash` and `airdropAmount` fields if you want to start with it.

Here are a few examples on how a genesis file is used: [scripts/run.sh](https://github.com/ava-labs/subnet-evm/blob/master/scripts/run.sh#L99)

### Setting the Genesis Allocation[​](#setting-the-genesis-allocation "Direct link to heading")

Alloc defines addresses and their initial balances. This should be changed accordingly for each chain. If you don't provide any genesis allocation, you won't be able to interact with your new chain (all transactions require a fee to be paid from the sender's balance).

The `alloc` field expects key-value pairs. Keys of each entry must be a valid `address`. The `balance` field in the value can be either a `hexadecimal` or `number` to indicate initial balance of the address. The default value contains `8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC` with `50000000000000000000000000` balance in it. Default:

```json
"alloc": {
  "8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC": {
    "balance": "0x295BE96E64066972000000"
  }
}
```

To specify a different genesis allocation, populate the `alloc` field in the genesis JSON as follows:

```json
"alloc": {
  "8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC": {
    "balance": "0x52B7D2DCC80CD2E4000000"
  },
  "Ab5801a7D398351b8bE11C439e05C5B3259aeC9B": {
    "balance": "0xa796504b1cb5a7c0000"
  }
},
```

The keys in the allocation are [hex](https://en.wikipedia.org/wiki/Hexadecimal) addresses **without the canonical `0x` prefix**. The balances are denominated in Wei ([10^18 Wei = 1 Whole Unit of Native Token](https://eth-converter.com/)) and expressed as hex strings **with the canonical `0x` prefix**. You can use [this converter](https://www.rapidtables.com/convert/number/hex-to-decimal.html) to translate between decimal and hex numbers.

The above example yields the following genesis allocations (denominated in whole units of the native token, that is 1 AVAX/1 WAGMI):

```bash
0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC: 100000000 (0x52B7D2DCC80CD2E4000000=100000000000000000000000000 Wei)
0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B: 49463 (0xa796504b1cb5a7c0000=49463000000000000000000 Wei)
```

### Setting a Custom Fee Recipient[​](#setting-a-custom-fee-recipient "Direct link to heading")

By default, all fees are burned (sent to the black hole address with `"allowFeeRecipients": false`). However, it is possible to enable block producers to set a fee recipient (who will get compensated for blocks they produce).

To enable this feature, you'll need to add the following to your genesis file (under the `"config"` key):

```json
{
  "config": {
    "allowFeeRecipients": true
  }
}
```

#### Fee Recipient Address[​](#fee-recipient-address "Direct link to heading")

With `allowFeeRecipients` enabled, your validators can specify their addresses to collect fees. They need to update their EVM [chain config](#avalanchego-chain-configs) with the following to specify where the fee should be sent to.

```json
{
  "feeRecipient": "<YOUR 0x-ADDRESS>"
}
```

<Callout type="warn">
If `allowFeeRecipients` feature is enabled on the Avalanche L1, but a validator doesn't specify a "feeRecipient", the fees will be burned in blocks it produces.
</Callout>

This mechanism can be also activated as a precompile. See [Changing Fee Reward Mechanisms](#changing-fee-reward-mechanisms) section for more details.

Precompiles[​](#precompiles "Direct link to heading")
-----------------------------------------------------

Subnet-EVM can provide custom functionalities with precompiled contracts. These precompiled contracts can be activated through `ChainConfig` (in genesis or as an upgrade).

### AllowList Interface[​](#allowlist-interface "Direct link to heading")

The `AllowList` interface is used by precompiles to check if a given address is allowed to use a precompiled contract. `AllowList` consist of three roles, `Admin`, `Manager` and `Enabled`. `Admin` can add/remove other `Admin` and `Enabled` addresses. `Manager` is introduced with Durango upgrade and can add/remove `Enabled` addresses, without the ability to add/remove `Admin` or `Manager` addresses. `Enabled` addresses can use the precompiled contract, but cannot modify other roles.

`AllowList` adds `adminAddresses`, `managerAddresses`, `enabledAddresses` fields to precompile contract configurations. For instance fee manager precompile contract configuration looks like this:

```json
{
  "feeManagerConfig": {
    "blockTimestamp": 0,
    "adminAddresses": [<list of addresses>],
    "managerAddresses": [<list of addresses>],
    "enabledAddresses": [<list of addresses>],
  }
}
```

`AllowList` configuration affects only the related precompile. For instance, the admin address in `feeManagerConfig` does not affect admin addresses in other activated precompiles.

The `AllowList` solidity interface is defined as follows, and can be found in [IAllowList.sol](https://github.com/ava-labs/subnet-evm/blob/helloworld-official-tutorial-v2/contracts/contracts/interfaces/IAllowList.sol):

```solidity
//SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

interface IAllowList {
  event RoleSet(
    uint256 indexed role,
    address indexed account,
    address indexed sender,
    uint256 oldRole
  );

  // Set [addr] to have the admin role over the precompile contract.
  function setAdmin(address addr) external;

  // Set [addr] to be enabled on the precompile contract.
  function setEnabled(address addr) external;

  // Set [addr] to have the manager role over the precompile contract.
  function setManager(address addr) external;

  // Set [addr] to have no role for the precompile contract.
  function setNone(address addr) external;

  // Read the status of [addr].
  function readAllowList(address addr) external view returns (uint256 role);
}
```

`readAllowList(addr)` will return a uint256 with a value of 0, 1, or 2, corresponding to the roles `None`, `Enabled`, and `Admin` respectively.

`RoleSet` is an event that is emitted when a role is set for an address. It includes the role, the modified address, the sender as indexed parameters and the old role as non-indexed parameter. Events in precompiles are activated after Durango upgrade.

Note: `AllowList` is not an actual contract but just an interface. It's not callable by itself. This is used by other precompiles. Check other precompile sections to see how this works.

### Restricting Smart Contract Deployers[​](#restricting-smart-contract-deployers "Direct link to heading")

If you'd like to restrict who has the ability to deploy contracts on your Avalanche L1, you can provide an `AllowList` configuration in your genesis or upgrade file:

```json
{
  "contractDeployerAllowListConfig": {
    "blockTimestamp": 0,
    "adminAddresses": ["0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC"]
  }
}
```

In this example, `0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC` is named as the `Admin` of the `ContractDeployerAllowList`. This enables it to add other `Admin` or to add `Enabled` addresses. Both `Admin` and `Enabled` can deploy contracts. To provide a great UX with factory contracts, the `tx.Origin` is checked for being a valid deployer instead of the caller of `CREATE`. This means that factory contracts will still be able to create new contracts as long as the sender of the original transaction is an allow listed deployer.

The `Stateful Precompile` contract powering the `ContractDeployerAllowList` adheres to the [AllowList Solidity interface](#allowlist-interface) at `0x0200000000000000000000000000000000000000` (you can load this interface and interact directly in Remix):

- If you attempt to add a `Enabled` and you are not an `Admin`, you will see something like: ![admin fail](/images/customize1.png)   
- If you attempt to deploy a contract but you are not an `Admin` not a `Enabled`, you will see something like: ![deploy fail](/images/customize2.png)
- If you call `readAllowList(addr)` then you can read the current role of `addr`, which will return a uint256 with a value of 0, 1, or 2, corresponding to the roles `None`, `Enabled`, and `Admin` respectively.

<Callout type="warn">
If you remove all of the admins from the allow list, it will no longer be possible to update the allow list without modifying the Subnet-EVM to schedule a network upgrade.
</Callout>

#### Initial Contract Allow List Configuration[​](#initial-contract-allow-list-configuration "Direct link to heading")

It's possible to enable this precompile with an initial configuration to activate its effect on activation timestamp. This provides a way to enable the precompile without an admin address to manage the deployer list. With this, you can define a list of addresses that are allowed to deploy contracts. Since there will be no admin address to manage the deployer list, it can only be modified through a network upgrade.

To use initial configuration, you need to specify addresses in `enabledAddresses` field in your genesis or upgrade file:

```json
{
  "contractDeployerAllowListConfig": {
    "blockTimestamp": 0,
    "enabledAddresses": ["0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC"]
  }
}
```

This will allow only `0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC` to deploy contracts. For further information about precompile initial configurations see [Initial Precompile Configurations](#initial-precompile-configurations).

### Restricting Who Can Submit Transactions[​](#restricting-who-can-submit-transactions "Direct link to heading")

Similar to restricting contract deployers, this precompile restricts which addresses may submit transactions on chain. Like the previous section, you can activate the precompile by including an `AllowList` configuration in your genesis file:

```json
{
  "config": {
    "txAllowListConfig": {
      "blockTimestamp": 0,
      "adminAddresses": ["0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC"]
    }
  }
}
```

In this example, `0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC` is named as the `Admin` of the `TransactionAllowList`. This enables them to add other `Admins` or to add `Allowed`. `Admins`, `Manager` and `Enabled` can submit transactions to the chain.

The `Stateful Precompile` contract powering the `TxAllowList` adheres to the [AllowList Solidity interface](#allowlist-interface) at `0x0200000000000000000000000000000000000002` (you can load this interface and interact directly in Remix):

- If you attempt to add an `Enabled` and you are not an `Admin`, you will see something like: ![admin fail](/images/customize3.png)   
- If you attempt to submit a transaction but you are not an `Admin`, `Manager` or not `Enabled`, you will see something like: `cannot issue transaction from non-allow listed address` 
- If you call `readAllowList(addr)` then you can read the current role of `addr`, which will return a `uint256` with a value of 0, 1, 2 or 3 corresponding to the roles `None`, `Allowed`, `Admin` and `Manager` respectively.

<Callout type="warn">
If you remove all of the admins and managers from the allow list, it will no longer be possible to update the allow list without modifying the Subnet-EVM to schedule a network upgrade.
</Callout>

#### Initial TX Allow List Configuration[​](#initial-tx-allow-list-configuration "Direct link to heading")

It's possible to enable this precompile with an initial configuration to activate its effect on activation timestamp. This provides a way to enable the precompile without an admin address to manage the TX allow list. With this, you can define a list of addresses that are allowed to submit transactions.

Since there will be no admin address to manage the TX list, it can only be modified through a network upgrade. To use initial configuration, you need to specify addresses in `enabledAddresses` field in your genesis or upgrade file:

```json
{
  "txAllowListConfig": {
    "blockTimestamp": 0,
    "enabledAddresses": ["0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC"]
  }
}
```

This will allow only `0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC` to submit transactions. For further information about precompile initial configurations see [Initial Precompile Configurations](#initial-precompile-configurations).

### Minting Native Coins[​](#minting-native-coins "Direct link to heading")

You can mint native(gas) coins with a precompiled contract. In order to activate this feature, you can provide `nativeMinterConfig` in genesis:

```json
{
  "config": {
    "contractNativeMinterConfig": {
      "blockTimestamp": 0,
      "adminAddresses": ["0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC"]
    }
  }
}
```

`adminAddresses` denotes admin accounts who can add other `Admin`, `Manager` or `Enabled` accounts. `Admin`, `Manager` and `Enabled` are both eligible to mint native coins for other addresses. `ContractNativeMinter` uses same methods as in `ContractDeployerAllowList`.

The `Stateful Precompile` contract powering the `ContractNativeMinter` adheres to the following Solidity interface at `0x0200000000000000000000000000000000000001` (you can load this interface and interact directly in Remix):

```solidity
// (c) 2022-2023, Ava Labs, Inc. All rights reserved.
// See the file LICENSE for licensing terms.

pragma solidity ^0.8.0;
import "./IAllowList.sol";

interface INativeMinter is IAllowList {
  event NativeCoinMinted(
    address indexed sender,
    address indexed recipient,
    uint256 amount
  );

  // Mint [amount] number of native coins and send to [addr]
  function mintNativeCoin(address addr, uint256 amount) external;
}
```

`mintNativeCoin` takes an address and amount of native coins to be minted. The amount denotes the amount in minimum denomination of native coins (10^18). For example, if you want to mint 1 native coin (in AVAX), you need to pass 1 \* 10^18 as the amount. A `NativeCoinMinted` event is emitted with the sender, recipient and amount when a native coin is minted.

Note that this uses `IAllowList` interface directly, meaning that it uses the same `AllowList` interface functions like `readAllowList` and `setAdmin`, `setManager`, `setEnabled`, `setNone`. For more information see [AllowList Solidity interface](#allowlist-interface).

<Callout type="warn">
EVM does not prevent overflows when storing the address balance. Overflows in balance opcodes are handled by setting the balance to maximum. However the same won't apply for API calls. If you try to mint more than the maximum balance, API calls will return the overflowed hex-balance. This can break external tooling. Make sure the total supply of native coins is always less than 2^256-1.
</Callout>

#### Initial Native Minter Configuration[​](#initial-native-minter-configuration "Direct link to heading")

It's possible to enable this precompile with an initial configuration to activate its effect on activation timestamp. This provides a way to enable the precompile without an admin address to mint native coins. With this, you can define a list of addresses that will receive an initial mint of the native coin when this precompile activates. This can be useful for networks that require a one-time mint without specifying any admin addresses. To use initial configuration, you need to specify a map of addresses with their corresponding mint amounts in `initialMint` field in your genesis or upgrade file:

```json
{
  "contractNativeMinterConfig": {
    "blockTimestamp": 0,
    "initialMint": {
      "0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC": "1000000000000000000",
      "0x10037Fb06Ec4aB8c870a92AE3f00cD58e5D484b3": "0xde0b6b3a7640000"
    }
  }
}
```

In the amount field you can specify either decimal or hex string. This will mint 1000000000000000000 (equivalent of 1 Native Coin denominated as 10^18) to both addresses. Note that these are both in string format. "0xde0b6b3a7640000" hex is equivalent to 1000000000000000000. For further information about precompile initial configurations see [Initial Precompile Configurations](#initial-precompile-configurations).

### Configuring Dynamic Fees[​](#configuring-dynamic-fees "Direct link to heading")


You can configure the parameters of the dynamic fee algorithm on chain using the `FeeConfigManager`. In order to activate this feature, you will need to provide the `FeeConfigManager` in the genesis:

```json
{
  "config": {
    "feeManagerConfig": {
      "blockTimestamp": 0,
      "adminAddresses": ["0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC"]
    }
  }
}
```

The precompile implements the `FeeManager` interface which includes the same `AllowList` interface used by ContractNativeMinter, TxAllowList, etc. For an example of the `AllowList` interface, see the [TxAllowList](#allowlist-interface) above.

The `Stateful Precompile` contract powering the `FeeConfigManager` adheres to the following Solidity interface at `0x0200000000000000000000000000000000000003` (you can load this interface and interact directly in Remix). It can be also found in [IFeeManager.sol](https://github.com/ava-labs/subnet-evm/blob/5faabfeaa021a64c2616380ed2d6ec0a96c8f96d/contract-examples/contracts/IFeeManager.sol):

```solidity
//SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;
import "./IAllowList.sol";

interface IFeeManager is IAllowList {
  struct FeeConfig {
    uint256 gasLimit;
    uint256 targetBlockRate;
    uint256 minBaseFee;
    uint256 targetGas;
    uint256 baseFeeChangeDenominator;
    uint256 minBlockGasCost;
    uint256 maxBlockGasCost;
    uint256 blockGasCostStep;
  }
  event FeeConfigChanged(
    address indexed sender,
    FeeConfig oldFeeConfig,
    FeeConfig newFeeConfig
  );

  // Set fee config fields to contract storage
  function setFeeConfig(
    uint256 gasLimit,
    uint256 targetBlockRate,
    uint256 minBaseFee,
    uint256 targetGas,
    uint256 baseFeeChangeDenominator,
    uint256 minBlockGasCost,
    uint256 maxBlockGasCost,
    uint256 blockGasCostStep
  ) external;

  // Get fee config from the contract storage
  function getFeeConfig()
    external
    view
    returns (
      uint256 gasLimit,
      uint256 targetBlockRate,
      uint256 minBaseFee,
      uint256 targetGas,
      uint256 baseFeeChangeDenominator,
      uint256 minBlockGasCost,
      uint256 maxBlockGasCost,
      uint256 blockGasCostStep
    );

  // Get the last block number changed the fee config from the contract storage
  function getFeeConfigLastChangedAt()
    external
    view
    returns (uint256 blockNumber);
}
```

FeeConfigManager precompile uses `IAllowList` interface directly, meaning that it uses the same `AllowList` interface functions like `readAllowList` and `setAdmin`, `setManager`, `setEnabled`, `setNone`. For more information see [AllowList Solidity interface](#allowlist-interface).

In addition to the `AllowList` interface, the FeeConfigManager adds the following capabilities:

- `getFeeConfig`: retrieves the current dynamic fee config
- `getFeeConfigLastChangedAt`: retrieves the timestamp of the last block where the fee config was updated
- `setFeeConfig`: sets the dynamic fee config on chain (see [here](#fee-config) for details on the fee config parameters). This function can only be called by an `Admin`, `Manager` or `Enabled` address.
- `FeeConfigChanged`: an event that is emitted when the fee config is updated. Topics include the sender, the old fee config, and the new fee config.

You can also get the fee configuration at a block with the `eth_feeConfig` RPC method. For more information see [here](/docs/api-reference/subnet-evm-api#eth_feeconfig).

#### Initial Fee Config Configuration[​](#initial-fee-config-configuration "Direct link to heading")

It's possible to enable this precompile with an initial configuration to activate its effect on activation timestamp. This provides a way to define your fee structure to take effect at the activation.

To use the initial configuration, you need to specify the fee config in `initialFeeConfig` field in your genesis or upgrade file:

```json
{
  "feeManagerConfig": {
    "blockTimestamp": 0,
    "initialFeeConfig": {
      "gasLimit": 20000000,
      "targetBlockRate": 2,
      "minBaseFee": 1000000000,
      "targetGas": 100000000,
      "baseFeeChangeDenominator": 48,
      "minBlockGasCost": 0,
      "maxBlockGasCost": 10000000,
      "blockGasCostStep": 500000
    }
  }
}
```

This will set the fee config to the values specified in the `initialFeeConfig` field. For further information about precompile initial configurations see [Initial Precompile Configurations](#initial-precompile-configurations).

### Avalanche Warp Messaging[​](#avalanche-warp-messaging "Direct link to heading")

<Callout type="warn">
Currently Warp Precompile can only be activated in Mainnet after Durango occurs. Durango in Mainnet is set at 11 AM ET (4 PM UTC) on Wednesday, March 6th, 2024. If you plan to use Warp messaging in your own Subnet-EVM chain in Mainnet you should upgrade to AvalancheGo 1.11.11 or later and coordinate your precompile upgrade. Warp Config's "blockTimestamp" must be set after `1709740800`, Durango date (11 AM ET (4 PM UTC) on Wednesday, March 6th, 2024).
</Callout>

Contract Examples[​](#contract-examples "Direct link to heading")
-----------------------------------------------------------------

Subnet-EVM contains example contracts for precompiles under `/contracts`. It's a hardhat project with tests and tasks. For more information see [contract examples README](https://github.com/ava-labs/subnet-evm/tree/master/contracts#subnet-evm-contracts).

Network Upgrades: Enable/Disable Precompiles[​](#network-upgrades-enabledisable-precompiles "Direct link to heading")
---------------------------------------------------------------------------------------------------------------------

<Callout type="warn">
Performing a network upgrade requires coordinating the upgrade network-wide. A network upgrade changes the rule set used to process and verify blocks, such that any node that upgrades incorrectly or fails to upgrade by the time that upgrade goes into effect may become out of sync with the rest of the network.

Any mistakes in configuring network upgrades or coordinating them on validators may cause the network to halt and recovering may be difficult.
</Callout>

In addition to specifying the configuration for each of the above precompiles in the genesis chain config, they can be individually enabled or disabled at a given timestamp as a network upgrade. Disabling a precompile disables calling the precompile and destructs its storage so it can be enabled at a later timestamp with a new configuration if desired.

These upgrades must be specified in a file named `upgrade.json` placed in the same directory where [`config.json`](#avalanchego-chain-configs) resides: `{chain-config-dir}/{blockchainID}/upgrade.json`. For example, `WAGMI Subnet` upgrade should be placed in `~/.avalanchego/configs/chains/2ebCneCbwthjQ1rYT41nhd7M76Hc6YmosMAQrTFhBq8qeqh6tt/upgrade.json`.

The content of the `upgrade.json` should be formatted according to the following:

```json
{
  "precompileUpgrades": [
    {
      "[PRECOMPILE_NAME]": {
        "blockTimestamp": "[ACTIVATION_TIMESTAMP]", // unix timestamp precompile should activate at
        "[PARAMETER]": "[VALUE]" // precompile specific configuration options, eg. "adminAddresses"
      }
    }
  ]
}
```

<Callout type="warn">
An invalid `blockTimestamp` in an upgrade file results the update failing. The `blockTimestamp` value should be set to a valid Unix timestamp value which is in the _future_ relative to the _head of the chain_. If the node encounters a `blockTimestamp` which is in the past, it will fail on startup.
</Callout>

To disable a precompile, the following format should be used:

```json
{
  "precompileUpgrades": [
    {
      "<precompileName>": {
        "blockTimestamp": "[DEACTIVATION_TIMESTAMP]", // unix timestamp the precompile should deactivate at
        "disable": true
      }
    }
  ]
}
```

Each item in `precompileUpgrades` must specify exactly one precompile to enable or disable and the block timestamps must be in increasing order. Once an upgrade has been activated (a block after the specified timestamp has been accepted), it must always be present in `upgrade.json` exactly as it was configured at the time of activation (otherwise the node will refuse to start).

Enabling and disabling a precompile is a network upgrade and should always be done with caution.

<Callout type="warn">
For safety, you should always treat `precompileUpgrades` as append-only.

As a last resort measure, it is possible to abort or reconfigure a precompile upgrade that has not been activated since the chain is still processing blocks using the prior rule set.
</Callout>

If aborting an upgrade becomes necessary, you can remove the precompile upgrade from `upgrade.json` from the end of the list of upgrades. As long as the blockchain has not accepted a block with a timestamp past that upgrade's timestamp, it will abort the upgrade for that node.

### Example[​](#example "Direct link to heading")

```json
{
  "precompileUpgrades": [
    {
      "feeManagerConfig": {
        "blockTimestamp": 1668950000,
        "adminAddresses": ["0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC"]
      }
    },
    {
      "txAllowListConfig": {
        "blockTimestamp": 1668960000,
        "adminAddresses": ["0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC"]
      }
    },
    {
      "feeManagerConfig": {
        "blockTimestamp": 1668970000,
        "disable": true
      }
    }
  ]
}
```

This example enables the `feeManagerConfig` at the first block with timestamp >= `1668950000`, enables `txAllowListConfig` at the first block with timestamp >= `1668960000`, and disables `feeManagerConfig` at the first block with timestamp >= `1668970000`.

When a precompile disable takes effect (that is, after its `blockTimestamp` has passed), its storage will be wiped. If you want to reenable it, you will need to treat it as a new configuration.

After you have created the `upgrade.json` and placed it in the chain config directory, you need to restart the node for the upgrade file to be loaded (again, make sure you don't restart all Avalanche L1 validators at once!). On node restart, it will print out the configuration of the chain, where you can double-check that the upgrade has loaded correctly. In our example:

```bash
INFO [08-15|15:09:36.772] <2ebCneCbwthjQ1rYT41nhd7M76Hc6YmosMAQrTFhBq8qeqh6tt Chain>
github.com/ava-labs/subnet-evm/eth/backend.go:155: Initialised chain configuration
config=“{ChainID: 11111 Homestead: 0 EIP150: 0 EIP155: 0 EIP158: 0 Byzantium: 0
Constantinople: 0 Petersburg: 0 Istanbul: 0, Muir Glacier: 0, Subnet EVM: 0, FeeConfig:
{\“gasLimit\“:20000000,\“targetBlockRate\“:2,\“minBaseFee\“:1000000000,\“targetGas\
“:100000000,\“baseFeeChangeDenominator\“:48,\“minBlockGasCost\“:0,\“maxBlockGasCost\
“:10000000,\“blockGasCostStep\“:500000}, AllowFeeRecipients: false, NetworkUpgrades: {\
“subnetEVMTimestamp\“:0}, PrecompileUpgrade: {}, UpgradeConfig: {\"precompileUpgrades\":[{\"feeManagerConfig\":{\"adminAddresses\":[\"0x8db97c7cece249c2b98bdc0226cc4c2a57bf52fc\"],\"enabledAddresses\":null,\"blockTimestamp\":1668950000}},{\"txAllowListConfig\":{\"adminAddresses\":[\"0x8db97c7cece249c2b98bdc0226cc4c2a57bf52fc\"],\"enabledAddresses\":null,\"blockTimestamp\":1668960000}},{\"feeManagerConfig\":{\"adminAddresses\":null,\"enabledAddresses\":null,\"blockTimestamp\":1668970000,\"disable\":true}}]}, Engine: Dummy Consensus Engine}"
```

Notice that `precompileUpgrades` entry correctly reflects the changes. You can also check the activated precompiles at a timestamp with the [`eth_getActivePrecompilesAt`](/docs/api-reference/subnet-evm-api#eth_getactiveprecompilesat) RPC method. The [`eth_getChainConfig`](/docs/api-reference/subnet-evm-api#eth_getchainconfig) RPC method will also return the configured upgrades in the response.

That's it, your Avalanche L1 is all set and the desired upgrades will be activated at the indicated timestamp!

### Initial Precompile Configurations[​](#initial-precompile-configurations "Direct link to heading")

Precompiles can be managed by some privileged addresses to change their configurations and activate their effects. For example, the `feeManagerConfig` precompile can have `adminAddresses` which can change the fee structure of the network.

```json
{
  "precompileUpgrades": [
    {
      "feeManagerConfig": {
        "blockTimestamp": 1668950000,
        "adminAddresses": ["0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC"]
      }
    }
  ]
}
```

In this example, only the address `0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC` is allowed to change the fee structure of the network. The admin address has to call the precompile in order to activate its effect; that is it needs to send a transaction with a new fee config to perform the update. This is a very powerful feature, but it also gives a large amount of power to the admin address. If the address `0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC` is compromised, the network is compromised.

With the initial configurations, precompiles can immediately activate their effect on the activation timestamp. With this way admin addresses can be omitted from the precompile configuration. For example, the `feeManagerConfig` precompile can have `initialFeeConfig` to setup the fee configuration on the activation:

```json
{
  "precompileUpgrades": [
    {
      "feeManagerConfig": {
        "blockTimestamp": 1668950000,
        "initialFeeConfig": {
          "gasLimit": 20000000,
          "targetBlockRate": 2,
          "minBaseFee": 1000000000,
          "targetGas": 100000000,
          "baseFeeChangeDenominator": 48,
          "minBlockGasCost": 0,
          "maxBlockGasCost": 10000000,
          "blockGasCostStep": 500000
        }
      }
    }
  ]
}
```

Notice that there is no `adminAddresses` field in the configuration. This means that there will be no admin addresses to manage the fee structure with this precompile. The precompile will simply update the fee configuration to the specified fee config when it activates on the `blockTimestamp` `1668950000`.

<Callout title="Note">
It's still possible to add `adminAddresses` or `enabledAddresses` along with these initial configurations. In this case, the precompile will be activated with the initial configuration, and admin/enabled addresses can access to the precompiled contract normally.
</Callout>

<Callout title="Note">
If you want to change the precompile initial configuration, you will need to first disable it then activate the precompile again with the new configuration.
</Callout>

See every precompile initial configuration in their relevant `Initial Configuration` sections under [Precompiles](#precompiles).

AvalancheGo Chain Configs[​](#avalanchego-chain-configs "Direct link to heading")
---------------------------------------------------------------------------------

As described in [this doc](/docs/nodes/configure/configs-flags#avalanche-l1-chain-configs), each blockchain of Avalanche L1s can have its own custom configuration. If an Avalanche L1's ChainID is `2ebCneCbwthjQ1rYT41nhd7M76Hc6YmosMAQrTFhBq8qeqh6tt`, the config file for this chain is located at `{chain-config-dir}/2ebCneCbwthjQ1rYT41nhd7M76Hc6YmosMAQrTFhBq8qeqh6tt/config.json`.

For blockchains created by or forked from Subnet-EVM, most [C-Chain configs](/docs/nodes/chain-configs/c-chain) are applicable except [Avalanche Specific APIs](/docs/nodes/chain-configs/c-chain#enabling-avalanche-specific-apis).

### Priority Regossip[​](#priority-regossip "Direct link to heading")

A transaction is "regossiped" when the node does not find the transaction in a block after `priority-regossip-frequency` (defaults to `1m`). By default, up to 16 transactions (max 1 per address) are regossiped to validators per minute.

Operators can use "priority regossip" to more aggressively "regossip" transactions for a set of important addresses (like bridge relayers). To do so, you'll need to update your [chain config](/docs/nodes/configure/configs-flags#avalanche-l1-chain-configs) with the following:

```json
{
  "priority-regossip-addresses": ["<YOUR 0x-ADDRESS>"]
}
```

By default, up to 32 transactions from priority addresses (max 16 per address) are regossipped to validators per second. You can override these defaults with the following config:

```json
{
  "priority-regossip-frequency": "1s",
  "priority-regossip-max-txs": 32,
  "priority-regossip-addresses": ["<YOUR 0x-ADDRESS>"],
  "priority-regossip-txs-per-address": 16
}
```

### Fee Recipient[​](#fee-recipient "Direct link to heading")

This works together with [`allowFeeRecipients`](#setting-a-custom-fee-recipient) and [RewardManager precompile](/docs/avalanche-l1s/evm-configuration/transaction-fees#reward-manager) to specify where the fees should be sent to.

With `allowFeeRecipients` enabled, validators can specify their addresses to collect fees.

```json
{
  "feeRecipient": "<YOUR 0x-ADDRESS>"
}
```

<Callout type="warn">
If `allowFeeRecipients` or `RewardManager` precompile is enabled on the Avalanche L1, but a validator doesn't specify a "feeRecipient", the fees will be burned in blocks it produces.
</Callout>

### Archival Node Configuration[​](#archival-node-configuration "Direct link to heading")

Running an archival node that retains all historical state data requires specific configuration settings. Incorrect configuration can lead to historical data being pruned despite attempts to run in archival mode. Here are the key settings to configure:

#### Disabling Pruning

To retain all historical state, you must disable pruning. For EVM chains (like C-Chain or Subnet-EVM chains), add the following to your chain's `config.json`:

```json
{
  "pruning-enabled": false
}
```

#### State Sync Considerations

State sync allows nodes to quickly sync by downloading recent state without processing all historical blocks. This can lead to missing historical data. For archival nodes, either disable state sync or ensure you start from genesis:

```json
{
  "state-sync-enabled": false
}
```

#### Transaction History Settings

To maintain access to all historical transactions, you might need to configure these additional settings:

```json
{
  "transaction-history": 0
}
```

#### Database Considerations

<Callout type="warn">
Important: An already synced database cannot be fully converted to an archival node retroactively. The cleanest and most reliable way to set up an archival node is to start from scratch with the proper configuration.
</Callout>

When switching between database types (e.g., from LevelDB to PebbleDB), historical data does not carry over. If you need to change the database type for your archival node, you must start a fresh sync from genesis.

For information about all available configuration options and directory structures, see the [AvalancheGo Config Flags documentation](https://build.avax.network/docs/nodes/configure/configs-flags).

Network Upgrades: State Upgrades[​](#network-upgrades-state-upgrades "Direct link to heading")
----------------------------------------------------------------------------------------------

Subnet-EVM allows the network operators to specify a modification to state that will take place at the beginning of the first block with a timestamp greater than or equal to the one specified in the configuration.

This provides a last resort path to updating non-upgradeable contracts via a network upgrade (for example, to fix issues when you are running your own blockchain).

<Callout type="warn">
This should only be used as a last resort alternative to forking `subnet-evm` and specifying the network upgrade in code.

Using a network upgrade to modify state is not part of normal operations of the EVM. You should ensure the modifications do not invalidate any of the assumptions of deployed contracts or cause incompatibilities with downstream infrastructure such as block explorers.
</Callout>

The timestamps for upgrades in `stateUpgrades` must be in increasing order. `stateUpgrades` can be specified along with `precompileUpgrades` or by itself.

The following three state modifications are supported:

- `balanceChange`: adds a specified amount to the balance of a given account. This amount can be specified as hex or decimal and must be positive.
- `storage`: modifies the specified storage slots to the specified values. Keys and values must be 32 bytes specified in hex, with a `0x` prefix.
- `code`: modifies the code stored in the specified account. The code must _only_ be the runtime portion of a code. The code must start with a `0x` prefix.

<Callout type="warn">
If modifying the code, _only_ the runtime portion of the bytecode should be provided in `upgrades.json`. Do not use the bytecode that would be used for deploying a new contract, as this includes the constructor code as well. Refer to your compiler's documentation for information on how to find the runtime portion of the contract you wish to modify.
</Callout>

The `upgrades.json` file shown below describes a network upgrade that will make the following state modifications at the first block after (or at) `March 8, 2023 1:30:00 AM GMT`:

- Sets the code for the account at `0x71562b71999873DB5b286dF957af199Ec94617F7`,
- And adds `100` wei to the balance of the account at `0xb794f5ea0ba39494ce839613fffba74279579268`,
- Sets the storage slot `0x1234` to the value `0x6666` for the account at `0xb794f5ea0ba39494ce839613fffba74279579268`.

```json
{
  "stateUpgrades": [
    {
      "blockTimestamp": 1678239000,
      "accounts": {
        "0x71562b71999873DB5b286dF957af199Ec94617F7": {
          "code": "0x6080604052348015600f57600080fd5b506004361060285760003560e01c80632e64cec114602d575b600080fd5b60336047565b604051603e91906067565b60405180910390f35b60008054905090565b6000819050919050565b6061816050565b82525050565b6000602082019050607a6000830184605a565b9291505056fea26469706673582212209421042a1fdabcfa2486fb80942da62c28e61fc8362a3f348c4a96a92bccc63c64736f6c63430008120033"
        },
        "0xb794f5ea0ba39494ce839613fffba74279579268": {
          "balanceChange": "0x64",
          "storage": {
            "0x0000000000000000000000000000000000000000000000000000000000001234": "0x0000000000000000000000000000000000000000000000000000000000006666"
          }
        }
      }
    }
  ]
}
```

Network Upgrades: Rescheduling Mandatory Network Upgrades[​](#network-upgrades-rescheduling-mandatory-network-upgrades "Direct link to heading")
------------------------------------------------------------------------------------------------------------------------------------------------

A typical case when a network misses any mandatory activation would result in a network that is not able to operate. This is because validators/nodes running the old version would process transactions differently than nodes running the new version and end up different state. This would result in a fork in the network and new nodes would not be able to sync with the network. Normally this puts the chain in a halt and requires a hard fork to fix the issue. Starting with Subnet-EVM v0.6.3, you can reschedule mandatory activations like Durango via upgrade configs (upgrade.json in chain directory). This is a very advanced operation and should be done only if your network cannot operate going forward. The reschedule operation should be coordinated with your entire network nodes. Network upgrade overrides can be defined in the `upgrade.json` as follows:

```json
{
  "networkUpgradeOverrides": {
    "{networkUpgrade1}": timestamp1,
    "{networkUpgrade2}": timestamp2,
  }
}
```

The `timestamp` should be a Unix timestamp in seconds.

For instance, if you missed the Durango activation in Fuji (February 13th, 2024, 16:00 UTC) or Mainnet (March 6th, 2024, 16:00 UTC) and having issues in your network, you can reschedule the Durango activation via upgrades. In order to do this, you need to prepare a new upgrade.json including following:

```json
{
  "networkUpgradeOverrides": {
    "durangoTimestamp": 1712419200
  }
}
```

This reschedules the Durango activation to 2024-11-06 16:00:00 UTC (one month later than the actual activation). After preparing the upgrade.json, you need to update the chain directory with the new upgrade.json and restart your nodes. You should see logs similar to the following:

```bash
INFO [03-22|14:04:48.284] <fPypUHjNvJqBKXBx2LEoJ9u5b8rRxMtEhb4v2QEDQejEiTtMG Chain> github.com/ava-labs/subnet-evm/plugin/evm/vm.go:367: Applying network upgrade overrides overrides="{\"durangoTimestamp\":1712419200}"
...
INFO [03-22|14:04:48.288] <fPypUHjNvJqBKXBx2LEoJ9u5b8rRxMtEhb4v2QEDQejEiTtMG Chain> github.com/ava-labs/subnet-evm/core/blockchain.go:335: Avalanche Upgrades (timestamp based):
INFO [03-22|14:04:48.288] <fPypUHjNvJqBKXBx2LEoJ9u5b8rRxMtEhb4v2QEDQejEiTtMG Chain> github.com/ava-labs/subnet-evm/core/blockchain.go:335:  - SubnetEVM Timestamp:           @0          (https://github.com/ava-labs/avalanchego/releases/tag/v1.10.0)
INFO [03-22|14:04:48.288] <fPypUHjNvJqBKXBx2LEoJ9u5b8rRxMtEhb4v2QEDQejEiTtMG Chain> github.com/ava-labs/subnet-evm/core/blockchain.go:335:  - Durango Timestamp:            @1712419200 (https://github.com/ava-labs/avalanchego/releases/tag/v1.11.0)
...
```

This means your node is lock and loaded for the new Durango activation. After the new timestamp is reached, your node will activate Durango and start processing transactions with the new Durango features.

<Callout type="warn">
Nodes running non-compatible version (running pre-Durango version after Durango activation), should be updated to most recent version of Subnet-EVM (v0.6.3+) and must have the new upgrade.json to reschedule the Durango activation. Running a new version without the rescheduling upgrade.json might create a fork in the network.

All of network nodes, even ones correctly upgraded to Durango and running the correct version since Durango activation, should be restarted with the new upgrade.json to reschedule the Durango activation. This is a network-wide operation and should be coordinated with all network nodes.
</Callout>

# Durango Upgrade (/docs/avalanche-l1s/upgrade/durango-upgrade)

---
title: Durango Upgrade
description: Learn how to upgrade your Subnet-EVM and precompiles for the Durango network upgrade.
---

Durango will be activated on the Avalanche Mainnet at 11 AM ET (4 PM UTC) on Wednesday, March 6th, 2024. Subnet-EVM introduces a set of new features and backwards-incompatible changes with the Durango network upgrade. This guide will walk you through the process of upgrading your Subnet-EVM and precompiles for the Durango network upgrade.

The Durango network upgrade introduces new features and improvements to the Avalanche platform and Subnet-EVM. This guide will help you ensure that your Subnet-EVM and precompiles are compatible with the Durango network upgrade.

Note: Subnet-EVM already performs these upgrades in native stateful precompiles. This guide is for users who have custom precompiles and need to upgrade them for Durango.

Durango introduces following changes to Subnet-EVM:

- Avalanche Warp Messaging
- Events in Precompiles
- Manager Role
- Non-Strict Mode
- [Shanghai Upgrade from ACP-24](https://github.com/avalanche-foundation/ACPs/tree/main/ACPs/24-shanghai-eips) will be activated with Durango without any further modification in Subnet-EVM.

Avalanche Warp Messaging[​](#avalanche-warp-messaging "Direct link to heading")
-------------------------------------------------------------------------------

Avalanche Warp Messaging (AWM) is a new feature introduced with the Durango network upgrade. It enables native cross-Avalanche L1 communication and allows [Virtual Machine (VM)](/docs/quick-start/virtual-machines) developers to implement arbitrary communication protocols between any two Avalanche L1s. For more information about AWM see [here](/docs/avalanche-l1s/evm-configuration/warpmessenger).

Warp Precompile must be enabled for Avalanche L1s after Durango. For more information the precompile and activation see [here](/docs/avalanche-l1s/upgrade/customize-avalanche-l1#avalanche-warp-messaging)

Events[​](#events "Direct link to heading")
-------------------------------------------

Subnet-EVM Native Precompiles will start emitting events with the Durango network upgrade. This will allow you to listen to events emitted by Subnet-EVM native precompiles. Following events will be introduced:

- `event RoleSet(uint256 indexed role, address indexed account, address indexed sender, uint256 oldRole)`: This event will be emitted when a role is set for an account. Precompiles that uses `IAllowList` interface will emit this event without requiring any changes. The event contains the role, account, sender as indexed parameters and old role as non-indexed parameter.
- `event FeeConfigChanged(address indexed sender, FeeConfig oldFeeConfig, FeeConfig newFeeConfig)`: This event will be emitted when the fee configuration is changed in `FeeManager` precompile. The event contains the sender as indexed parameter and old and new fee configuration as non-indexed parameters.
- `event NativeCoinMinted(address indexed sender, address indexed recipient, uint256 amount)`: This event will be emitted when new native coins are minted. The event contains the sender, recipient as indexed parameters and the amount as non-indexed parameter.
- `event RewardAddressChanged(address indexed sender, address indexed oldRewardAddress, address indexed newRewardAddress)`: This event will be emitted when the reward address is changed in `RewardManager` precompile. The event contains the sender, old and new reward addresses as non-indexed parameters.
- `event FeeRecipientsAllowed(address indexed sender)`: This event will be emitted when the fee recipients are allowed in `RewardManager` precompile. The event contains the sender as indexed parameter.
- `event RewardsDisabled(address indexed sender)`: This event will be emitted when the rewards are disabled in `RewardManager` precompile. The event contains the sender as indexed parameter.

### Custom Events[​](#custom-events "Direct link to heading")

Events above are already introduced and handled in Subnet-EVM native precompiles. If you have a custom precompile, you can start emitting your custom events using Durango activation. In order to do this you can define your custom event in your solidity interface and regenerate the go bindings using `precompilegen` tool, for more information see [here](/docs/virtual-machines/custom-precompiles/create-precompile).

Generally you will generate an `event.go` file in addition to your existing precompile files. You need to implement how to emit your events and your events' gas costs, as in [hello world example](/docs/virtual-machines/custom-precompiles/defining-precompile#event-file). In this guide we will use the hello world example to demonstrate how to emit custom events. The event that will be introduced is:

```go
event GreetingChanged(address indexed sender, string oldGreeting, string newGreeting)
```

It will be emitted when the greeting is changed in the hello world precompile. You can find the hello world precompile [here](https://github.com/ava-labs/subnet-evm/tree/helloworld-official-tutorial-v2/precompile/contracts/helloworld). We also assume that hello world precompile is already deployed before Durango and we will be upgrading it for Durango.

#### Adjusting Gas Costs[​](#adjusting-gas-costs "Direct link to heading")

Adjusting gas costs for your custom events is very important. Emitted events are written to state and consume resources. You should make sure you're charging the right amount of gas before emitting your event.

`precompilegen` tool automatically generates a scaffold for your gas calculations, however you should review and adjust the gas costs according to your needs, especially if you're using any arbitrary size data in your events.

Gas cost function for the event `GreetingChanged(address indexed sender, string oldGreeting, string newGreeting)` looks like this:

```go
func GetGreetingChangedEventGasCost(data GreetingChangedEventData) uint64 {
	gas := contract.LogGas // base gas cost

	// Add topics gas cost (2 topics)
	// Topics always include the signature hash of the event. The rest are the indexed event arguments.
	gas += contract.LogTopicGas * 2

	// CUSTOM CODE STARTS HERE
	// Keep in mind that the data here will be encoded using the ABI encoding scheme.
	// So the computation cost might change according to the data type + data size and should be charged accordingly.
	// i.e gas += LogDataGas * uint64(len(data.oldGreeting))
	gas += contract.LogDataGas * uint64(len(data.OldGreeting)) // * ...
	// CUSTOM CODE ENDS HERE
	// CUSTOM CODE STARTS HERE
	// Keep in mind that the data here will be encoded using the ABI encoding scheme.
	// So the computation cost might change according to the data type + data size and should be charged accordingly.
	// i.e gas += LogDataGas * uint64(len(data.newGreeting))
	gas += contract.LogDataGas * uint64(len(data.NewGreeting)) // * ...
	// CUSTOM CODE ENDS HERE

	// CUSTOM CODE STARTS HERE
	return gas
}
```

We have charged the base gas cost, topics gas cost and data gas cost for the old and new greeting. Topic gas cost includes 2 topics, one for the signature hash of the event and the other for the indexed sender argument.

Data gas cost is calculated according to the data type and size. If you're not using any arbitrary size data in your events, you can define it as a constant.

#### Durango Activation Check[​](#durango-activation-check "Direct link to heading")

After completing defining your custom events, you need to pack your events, charge your event gas and emit them in your precompile functions. Since this procedure is non-backward compatible, you need to ensure that this will only be activated after the Durango network upgrade.

You can use the `contract.IsDurangoActivated` function to check if the Durango network upgrade is activated. For Hello World example, we will be changing `setGreeting` function starting [here](https://github.com/ava-labs/subnet-evm/blob/helloworld-official-tutorial-v2/precompile/contracts/helloworld/contract.go#L187) via following:

```go
if contract.IsDurangoActivated(accessibleState) {
 ...
}
```

Note: this activation won't be needed if you plan to deploy your custom precompile after Durango.

#### Event Packers[​](#event-packers "Direct link to heading")

Event packers and unpackers will be automatically generated with the `precompilegen` tool. You can use these packers and unpackers to pack and unpack your custom events. For hello world example:

```go
if remainingGas, err = contract.DeductGas(remainingGas, contract.ReadGasCostPerSlot); err != nil {
  return nil, 0, err
}
oldGreeting := GetGreeting(stateDB)

eventData := GreetingChangedEventData{
  OldGreeting: oldGreeting,
  NewGreeting: inputStruct,
}
topics, data, err := PackGreetingChangedEvent(caller, eventData)
if err != nil {
  return nil, remainingGas, err
}
```

This will first charge gas for fetching the old greeting from the state fetch and then fetch it from the state. Then it will pack the event data with old and new greeting as non-indexed event data.

#### Emitting Events[​](#emitting-events "Direct link to heading")

After packing the event data, you can charge the event gas and emit your custom events using the `stateDB.AddLog` function. For hello world example it starts [here](https://github.com/ava-labs/subnet-evm/blob/helloworld-official-tutorial-v2/precompile/contracts/helloworld/contract.go#L203-L214):

```go
// Charge the gas for emitting the event.
eventGasCost := GetGreetingChangedEventGasCost(eventData)
if remainingGas, err = contract.DeductGas(remainingGas, eventGasCost); err != nil {
  return nil, 0, err
}

// Emit the event
stateDB.AddLog(
  ContractAddress,
  topics,
  data,
  accessibleState.GetBlockContext().Number().Uint64(),
)
```

Manager Role[​](#manager-role "Direct link to heading")
-------------------------------------------------------

Durango introduces a new role called the manager role. The manager role is a mid-role between `Admin` and `Enabled`. The manager role is considered as an `Enabled` account and perform restricted state-changing operations in precompiles. Manager role also can modify other `Enabled` accounts. It can appoint new `Enabled` accounts and remove existing `Enabled` accounts. Manager role cannot modify other `Manager` or `Admin` accounts. For more information about AllowList see [here](/docs/avalanche-l1s/upgrade/customize-avalanche-l1#allowlist-interface).

If you have any precompile using AllowList, you can issue a call to `setManager` in your precompile to appoint new Manager accounts. For upgrades or new precompiles with AllowList config you can use `managerAddresses` as follow:

```json
{
  "feeManagerConfig": {
    "blockTimestamp": 0,
    "adminAddresses": [<list of addresses>],
    "managerAddresses": [<list of addresses>],
    "enabledAddresses": [<list of addresses>],
  }
}
```

Non-Strict Mode[​](#non-strict-mode "Direct link to heading")
-------------------------------------------------------------

Strict mode unpacking prevents using extra padded bytes in inputs. This created some issue in few legacy contracts like Gnosis Multisig wallet. For more information about strict mode see [solidity docs](https://docs.soliditylang.org/en/latest/abi-spec.html#strict-encoding-mode).

For Hello world example we were using this `UnpackSetGreetingInput` with strict mode enabled before:

```go
func UnpackSetGreetingInput(input []byte) (string, error) {
  // This function was using strict mode unpacking by default.
	res, err := HelloWorldABI.UnpackInput("setGreeting", input)
	if err != nil {
		return "", err
	}
	unpacked := *abi.ConvertType(res[0], new(string)).(*string)
	return unpacked, nil
}
```

In order to handle extra padded bytes, Subnet-EVM will start using non-strict mode with Durango in `Input Unpackers`. However since this change will be non-backward compatible you need to ensure that this will only be activated after the Durango network upgrade.

You can use the `contract.IsDurangoActivated` function to check if the Durango network upgrade is activated. Now we will using this function to start using non-strict mode unpacking:

```go
// UnpackSetGreetingInput attempts to unpack [input] into the string type argument
// assumes that [input] does not include selector (omits first 4 func signature bytes)
// if [useStrictMode] is true, it will return an error if the length of [input] is not [common.HashLength]
func UnpackSetGreetingInput(input []byte, useStrictMode bool) (string, error) {
	// Initially we had this check to ensure that the input was the correct length.
	// However solidity does not always pack the input to the correct length, and allows
	// for extra padding bytes to be added to the end of the input. Therefore, we have removed
	// this check with the Durango. We still need to keep this check for backwards compatibility.
	if useStrictMode && len(input) > common.HashLength {
		return "", ErrInputExceedsLimit
	}
	res, err := HelloWorldABI.UnpackInput("setGreeting", input, useStrictMode)
	if err != nil {
		return "", err
	}
	unpacked := *abi.ConvertType(res[0], new(string)).(*string)
	return unpacked, nil
}
```

To call this function in `setGreeting` we should use Durango activation as follows [here](https://github.com/ava-labs/subnet-evm/blob/helloworld-official-tutorial-v2/precompile/contracts/helloworld/contract.go#L159-L167):

```go
// do not use strict mode after Durango
useStrictMode := !contract.IsDurangoActivated(accessibleState)
// attempts to unpack [input] into the arguments to the SetGreetingInput.
// Assumes that [input] does not include selector
// You can use unpacked [inputStruct] variable in your code
inputStruct, err := UnpackSetGreetingInput(input, useStrictMode)
if err != nil {
  return nil, remainingGas, err
}
```

This will ensure that non-strict mode unpacking is used after Durango activation.

This should not impose any critical issue for your custom precompiles. If you want to keep using the old strict mode and keep the backward compatibility you can use `true` for the `useStrictMode` parameter.

However if your precompile is mainly used from other deployed contracts (Solidity) you should do this transition in order to increase the compatibility of your precompile.


# Add Validator (/docs/avalanche-l1s/validator-manager/add-validator)

---
title: Add Validator
description: Learn how to add validators to your Avalanche L1 blockchain.
---


### Register a Validator

Validator registration is initiated with a call to `initializeValidatorRegistration`. The sender of this transaction is registered as the validator owner. Churn limitations are checked - only a certain (configurable) percentage of the total weight is allowed to be added or removed in a (configurable) period of time. The `ValidatorManager` then constructs a `RegisterL1ValidatorMessage` Warp message to be sent to the P-Chain. Each validator registration request includes all of the information needed to identify the validator and its stake weight, as well as an `expiry` timestamp before which the `RegisterL1ValidatorMessage` must be delivered to the P-Chain. If the validator is not registered on the P-Chain before the `expiry`, then the validator may be removed from the contract state by calling `completeEndValidation`.

The `RegisterL1ValidatorMessage` is delivered to the P-Chain as the Warp message payload of a `RegisterL1ValidatorTx`. Please see the transaction specification for validity requirements. The P-Chain then signs a `L1ValidatorRegistrationMessage` Warp message indicating that the specified validator was successfully registered on the P-Chain.

The `L1ValidatorRegistrationMessage` is delivered to the `ValidatorManager` via a call to `completeValidatorRegistration`. For PoS Validator Managers, staking rewards begin accruing at this time.

### (PoS only) Register a Delegator

`PoSValidatorManager` supports delegation to an actively staked validator as a way for users to earn staking rewards without having to validate the chain. Delegators pay a configurable percentage fee on any earned staking rewards to the host validator. A delegator may be registered by calling `initializeDelegatorRegistration` and providing an amount to stake. The delegator will be registered as long as churn restrictions are not violated. The delegator is reflected on the P-Chain by adjusting the validator's registered weight via a `SetL1ValidatorWeightTx`. The weight change acknowledgement is delivered to the `PoSValidatorManager` via an `L1ValidatorWeightMessage`, which is provided by calling `completeDelegatorRegistration`.

The P-Chain is only willing to sign an `L1ValidatorWeightMessage` for an active validator. Once a validator exit has been initiated (via a call to `initializeEndValidation`), the `PoSValidatorManager` must assume that the validator has been deactivated on the P-Chain, and will therefore not sign any further weight updates. Therefore, it is invalid to initiate adding or removing a delegator when the validator is in this state, though it may be valid to complete an already initiated delegator action, depending on the order of delivery to the P-Chain. If the delegator weight change was submitted (and a Warp signature on the acknowledgement retrieved) before the validator was removed, then the delegator action may be completed. Otherwise, the acknowledgement of the validation end must first be delivered before completing the delegator action.


# Validator Manager Contracts (/docs/avalanche-l1s/validator-manager/contract)

---
title: "Validator Manager Contracts"
description: "This page lists all available contracts for the Validator Manager."
edit_url: https://github.com/ava-labs/icm-contracts/edit/main/contracts/validator-manager/README.md
---

# Validator Manager Contracts

The contracts in this directory define the Validator Manager used to manage Avalanche L1 validators, as defined in [ACP-77](https://github.com/avalanche-foundation/ACPs/tree/main/ACPs/77-reinventing-subnets). They comply with [ACP-99](https://github.com/avalanche-foundation/ACPs/tree/main/ACPs/99-validatorsetmanager-contract), which specifies the standard minimal functionality that Validator Managers should implement. The contracts in this directory are are related as follows:

<Mermaid chart={`---
  config:
    class:
      hideEmptyMembersBox: true
---
classDiagram
class ACP99Manager {
    +initializeValidatorSet()
    +completeValidatorRegistration()
    +completeValidatorRemoval()
    +completeValidatorWeightUpdate()
    -_initiateValidatorRegistration()
    -_initiateValidatorRemoval()
    -_initiateValidatorWeightUpdate()
}
<<Abstract>> ACP99Manager

class ValidatorManager {
    +initializeValidatorSet()
    +completeValidatorRegistration() onlyOwner
    +completeValidatorRemoval() onlyOwner
    +completeValidatorWeightUpdate() onlyOwner
    +initiateValidatorRegistration() onlyOwner
    +initiateValidatorRemoval() onlyOwner
    +initiateValidatorWeightUpdate() onlyOwner
}

class PoAManager {
    +completeValidatorRegistration()
    +completeValidatorRemoval()
    +completeValidatorWeightUpdate()
    +initiateValidatorRegistration() onlyOwner
    +initiateValidatorRemoval() onlyOwner
    +initiateValidatorWeightUpdate() onlyOwner
    +transferValidatorManagerOwnership() onlyOwner
}

class StakingManager {
    +completeValidatorRegistration()
    +initiateValidatorRemoval()
    +completeValidatorRemoval()
    +completeDelegatorRegistration()
    +initiateDelegatorRemoval()
    +completeDelegatorRemoval()
    -_initiateValidatorRegistration()
    -_initiateDelegatorRegistration()
}
<<Abstract>> StakingManager
class ERC20TokenStakingManager {
    +initiateValidatorRegistration()
    +initiateDelegatorRegistration()
}
class NativeTokenStakingManager {
    +initiateValidatorRegistration() payable
    +initiateDelegatorRegistration() payable
}

ACP99Manager <|-- ValidatorManager
ValidatorManager --o PoAManager : owner
ValidatorManager --o StakingManager : owner
StakingManager <|-- ERC20TokenStakingManager
StakingManager <|-- NativeTokenStakingManager`} />

## A Note on Nomenclature

The contracts in this directory are only useful to L1s that have been converted from Subnets as described in ACP-77. As such, `l1`/`L1` is generally preferred over `subnet`/`Subnet` in the source code. The one major exception is that `subnetID` should be used to refer to both Subnets that have not been converted, and L1s that have. This is because an L1 must first be initialized as a Subnet by issuing a `CreateSubnetTx` on the P-Chain, the transaction hash of which becomes the `subnetID`. Rather than change the name and/or value of this identifier, it is simpler for both to remain static in perpetuity.

## Deploying

The validator manager system consists of a `ValidatorManager`, and one of `NativeTokenStakingManager`, `ERC20TokenStakingManager`, or `PoAManager`. `ValidatorManager` is `Ownable`, and its owner should be set to the address of the other contract.

All of these are implemented as [upgradeable](https://github.com/OpenZeppelin/openzeppelin-contracts-upgradeable/blob/3d6a15108b50491ec3c51c03b32802c33e092a0f/contracts/proxy/utils/Initializable.sol#L56) contracts. There are numerous [guides](https://blog.chain.link/upgradable-smart-contracts/) for deploying upgradeable smart contracts, but the general steps are as follows:

1. Deploy the implementation contract
2. Deploy the proxy contract
3. Call the implementation contract's `initialize` function

- Each deployed contract requires different settings. For example, `ValidatorManagerSettings` specifies the churn parameters, while `StakingManagerSettings` specifies the staking and rewards parameters.

4. Initialize the validator set by calling `initializeValidatorSet` on `ValidatorManager`

- When an L1 is first created on the P-Chain, it must be explicitly converted to an L1 via [`ConvertSubnetToL1Tx`](https://github.com/avalanche-foundation/ACPs/tree/main/ACPs/77-reinventing-subnets#convertsubnettol1tx). The resulting `SubnetToL1ConversionMessage` ICM [message](https://github.com/avalanche-foundation/ACPs/tree/main/ACPs/77-reinventing-subnets#subnettol1conversionmessage) is provided in the call to `initializeValidatorSet` to specify the starting validator set in the `ValidatorManager`. Regardless of the setup of the overall validator manager system, these initial validators are treated as PoA and are not eligible for staking rewards.

### Proof-of-Authority

PoA validator management is provided by `PoAManager` by providing an `owner` in the call to `initialize`. Only the `owner` may initiate validator set changes, but anybody can complete the validator set change by providing the corresponding ICM message signed by the P-Chain.

> [!NOTE]
> PoA validator management can also be implemented by `ValidatorManager` on its own, by setting the `owner` to the desired admin address. Unlike `PoAManager`, only the admin is able to initiate or complete validator set changes.

### Proof-of-Stake

PoS validator management is provided by the abstract contract `StakingManager`, which has two concrete implementations: `NativeTokenStakingManager` and `ERC20TokenStakingManager`. `StakingManager` supports uptime-based validation rewards, as well as delegation to a chosen validator. The `uptimeBlockchainID` used to initialize the `StakingManager` **must** be validated by the L1 validator set that the contract manages. **There is no way to verify this from within the contract, so take care when setting this value.** This [state transition diagram](https://github.com/ava-labs/icm-contracts/blob/main/contracts/validator-manager/StateTransition.md) illustrates the relationship between validators and delegators. After deploying `StakingManager` and a proxy, call the `initialize` function, which takes a `StakingManagerSettings` as well as any implementation-specific arguments.

> [!NOTE]
> The `weightToValueFactor` fields of `StakingManagerSettings` sets the factor used to convert between the weight that the validator is registered with on the P-Chain, and the value transferred to the contract as stake. This involves integer division, which may result in loss of precision. When selecting `weightToValueFactor`, it's important to make the following considerations:
>
> 1. If `weightToValueFactor` is near the denomination of the asset, then staking amounts on the order of 1 unit of the asset may cause the converted weight to round down to 0. This may impose a larger-than-expected minimum stake amount.
>    - Ex: If USDC (denomination of 6) is used as the staking token and `weightToValueFactor` is 1e9, then any amount less than 1,000 USDC will round down to 0 and therefore be invalid.
> 2. Staked amounts up to `weightValueFactor - 1` may be lost in the contract as dust, as the validator's registered weight is used to calculate the original staked amount.
>    - Ex: `value=1001` and `weightToValueFactor=1e3`. The resulting weight will be `1`. Converting the weight back to a value results in `value=1000`.
> 3. The validator's weight is represented on the P-Chain as a `uint64`. `StakingManager` restricts values such that the calculated weight does not exceed the maximum value for that type.

### Migrating from Proof-of-Authority to Proof-of-Stake

See the [migration guide](https://github.com/ava-labs/icm-contracts/blob/main/contracts/validator-manager/PoAMigration.md) for details.

#### NativeTokenStakingManager

`NativeTokenStakingManager` allows permissionless addition and removal of validators that post the L1's native token as stake. Staking rewards are minted via the Native Minter Precompile, which is configured with a set of addresses with minting privileges. As such, the address that `NativeTokenStakingManager` is deployed to must be added as an admin to the precompile. This can be done by either calling the precompile's `setAdmin` method from an admin address, or setting the address in the Native Minter precompile settings in the chain's genesis (`config.contractNativeMinterConfig.adminAddresses`). There are a couple of methods to get this address: one is to calculate the resulting deployed address based on the deployer's address and account nonce: `keccak256(rlp.encode(address, nonce))`. The second method involves manually placing the `NativeTokenStakingManager` bytecode at a particular address in the genesis, then setting that address as an admin.

```json
{
    "config" : {
        ...
        "contractNativeMinterConfig": {
            "blockTimestamp": 0,
            "adminAddresses": [
                "0xffffffffffffffffffffffffffffffffffffffff"
            ]
        }
    },
    "alloc": {
        "0xffffffffffffffffffffffffffffffffffffffff": {
            "balance": "0x0",
            "code": "<NativeTokenStakingManagerByteCode>",
            "nonce": 1
        }
    }
}
```

#### ERC20TokenStakingManager

`ERC20TokenStakingManager` allows permissionless addition and removal of validators that post the an ERC20 token as stake. The ERC20 is specified in the call to `initialize`, and must implement [`IERC20Mintable`](https://github.com/ava-labs/icm-contracts/blob/main/contracts/validator-manager/interfaces/IERC20Mintable.sol). Care should be taken to enforce that only authorized users are able to `mint` the ERC20 staking token.

## Usage


### Register a Validator

#### PoA

Validator registration is initiated with a call to `PoAManager.initiateValidatorRegistration`. Churn limitations are checked - only a certain (configurable) percentage of the total weight is allowed to be added or removed in a (configurable) period of time. The `ValidatorManager` then constructs a [`RegisterL1ValidatorMessage`](https://github.com/avalanche-foundation/ACPs/tree/main/ACPs/77-reinventing-subnets#registerl1validatormessage) ICM message to be sent to the P-Chain. Each validator registration request includes all of the information needed to identify the validator and its stake weight, as well as an `expiry` timestamp before which the `RegisterL1ValidatorMessage` must be delivered to the P-Chain. If the validator is not registered on the P-Chain before the `expiry`, then the validator may be removed from the contract state by calling `completeValidatorRemoval`.

The `RegisterL1ValidatorMessage` is delivered to the P-Chain as the ICM message payload of a `RegisterL1ValidatorTx`. Please see the transaction [specification](https://github.com/avalanche-foundation/ACPs/tree/main/ACPs/77-reinventing-subnets#registerl1validatortx) for validity requirements. The P-Chain then signs a [`L1ValidatorRegistrationMessage`](https://github.com/avalanche-foundation/ACPs/tree/main/ACPs/77-reinventing-subnets#l1validatorregistrationmessage) ICM message indicating that the specified validator was successfully registered on the P-Chain.

The `L1ValidatorRegistrationMessage` is delivered by calling `ValidatorManager.completeValidatorRegistration`.

#### PoS

When registering a PoS validator, the same steps as the PoA case apply, with the only difference being that `StakingManager.initiateValidatorRegistration` and `StakingManager.completeValidatorRegistration` must be called instead. 

The sender of the transaction that called `StakingManager.initiateValidatorRegistration` is registered as the validator owner. Only this owner can remove the validator. 

Staking rewards begin accruing once `StakingManager.completeValidatorRegistration` is called.

### Remove a Validator

### PoA

Validator exit is initiated with a call to `PoAManager.initiateValidatorRemoval`. The `ValidatorManager` contructs an [`L1ValidatorWeightMessage`](https://github.com/avalanche-foundation/ACPs/tree/main/ACPs/77-reinventing-subnets#l1validatorweightmessage) ICM message with the weight set to `0`. This is delivered to the P-Chain as the payload of a [`SetL1ValidatorWeightTx`](https://github.com/avalanche-foundation/ACPs/tree/main/ACPs/77-reinventing-subnets#setl1validatorweighttx). The P-Chain acknowledges the validator exit by signing an `L1ValidatorRegistrationMessage` with `valid=0`, which is delivered by calling `ValidatorManager.completeValidatorRemoval`. The validation is removed from the contract's state.

### PoS

PoS validator removal follows the same flow as the PoA case, except that `StakingManager.initiateValidatorRemoval` and `StakingManager.completeValidatorRemoval` must be called instead.

There are two additional considerations:

- A [`ValidationUptimeMessage`](https://github.com/ava-labs/icm-contracts/blob/main/contracts/validator-manager/UptimeMessageSpec.md) ICM message may optionally be provided in the call to `StakingManager.initiateValidatorRemoval` in order to calculate the staking rewards; otherwise the latest received uptime will be used (see [(PoS only) Submit and Uptime Proof](#pos-only-submit-an-uptime-proof)). This proof may be requested directly from the L1 validators, which will provide it in a `ValidationUptimeMessage` ICM message. If the uptime is not sufficient to earn validation rewards, the call to `initiateValidatorRemoval` will fail. `forceInitiateValidatorRemoval` acts the same as `initiateValidatorRemoval`, but bypasses the uptime-based rewards check. Once `initiateValidatorRemoval` or `forceInitiateValidatorRemoval` is called, staking rewards cease accruing for `StakingManagers`.

- Unlike with PoA, PoS validators are not able to decrease their weight. This can lead to a scenario in which a PoS validator manager with a high proportion of the L1's weight is not able to exit the validator set due to churn restrictions. Additional validators or delegators will need to first be registered to more evenly distribute weight across the L1's validator set.

Once acknowledgement from the P-Chain has been received via a call to  `StakingManager.completeValidatorRemoval`, staking rewards are disbursed and stake is returned.

#### Disable a Validator Directly on the P-Chain

ACP-77 also provides a method to disable a validator without interacting with the L1 directly. The P-Chain transaction [`DisableL1ValidatorTx`](https://github.com/avalanche-foundation/ACPs/tree/main/ACPs/77-reinventing-subnets#disablel1validatortx) disables the validator on the P-Chain. The disabled validator's weight will still count towards the L1's total weight.

Disabled L1 validators can re-activate at any time by increasing their balance with an `IncreaseBalanceTx`. Anyone can call `IncreaseBalanceTx` for any validator on the P-Chain. A disabled validator can only be completely and permanently removed from the validator set by a call to `initiateValidatorRemoval`.

### (PoS only) Register a Delegator

`StakingManager` supports delegation to an actively staked validator as a way for users to earn staking rewards without having to validate the chain. Delegators pay a configurable percentage fee on any earned staking rewards to the host validator. A delegator may be registered by calling `initiateDelegatorRegistration` and providing an amount to stake. The delegator will be registered as long as churn restrictions are not violated. The delegator is reflected on the P-Chain by adjusting the validator's registered weight via a [`SetL1ValidatorWeightTx`](https://github.com/avalanche-foundation/ACPs/tree/main/ACPs/77-reinventing-subnets#setl1validatorweighttx). The weight change acknowledgement is delivered to the `StakingManager` via an [`L1ValidatorWeightMessage`](https://github.com/avalanche-foundation/ACPs/tree/main/ACPs/77-reinventing-subnets#l1validatorweightmessage), which is provided by calling `completeDelegatorRegistration`.

> [!NOTE]
> The P-Chain is only willing to sign an `L1ValidatorWeightMessage` for a validator in the L1's validator set. Once a validator exit has been initiated (via a call to `initiateValidatorRemoval`), the `StakingManager` must assume that the validator has been removed from the L1's validator set on the P-Chain, and therefore that the P-Chain will not sign any further weight updates. The contracts prohibit _initiating_ adding or removing a delegator in between calls to `initiateValidatorRemoval` and `completeValidatorRemoval`. However, if the `L1ValidatorWeightMessage` pertaining to an already initiated delegator action is constructed _before_ the validator is removed on the P-Chain, then the delegator action may be completed. Otherwise, `completeValidatorRemoval` must be called before completing the delegator action.

### (PoS only) Remove a Delegator

Delegator removal may be initiated by calling `initiateDelegatorRemoval`, as long as churn restrictions are not violated. Similar to `initiateValidatorRemoval`, an uptime proof may be provided to be used to determine delegator rewards eligibility. If no proof is provided, the latest known uptime will be used (see [(PoS only) Submit and Uptime Proof](#pos-only-submit-an-uptime-proof)). The validator's weight is updated on the P-Chain by the same mechanism used to register a delegator. The `L1ValidatorWeightMessage` from the P-Chain is delivered to the `StakingManager` in the call to `completeDelegatorRemoval`.

Either the delegator owner or the validator owner may initiate removing a delegator. This is to prevent the validator from being unable to remove itself due to churn limitations if it is has too high a proportion of the Subnet's total weight due to delegator additions. The validator owner may only remove Delegators after the minimum stake duration has elapsed.

### (PoS only) Submit an Uptime Proof

The [rewards calculator](https://github.com/ava-labs/icm-contracts/blob/main/contracts/validator-manager/interfaces/IRewardCalculator.sol) is a function of uptime seconds since the validator's start time. In addition to doing so in the calls to `initiateValidatorRemoval` and `initiateDelegatorRemoval` as described above, uptime proofs may also be supplied by calling `submitUptimeProof`. Unlike `initiateValidatorRemoval` and `initiateDelegatorRemoval`, `submitUptimeProof` may be called by anyone, decreasing the likelihood of a validation or delegation not being able to claim rewards that it deserved based on its actual uptime.

### (PoS only) Collect Staking Rewards

#### Validation Rewards

Validation rewards are distributed in the call to `completeValidatorRemoval` on the `StakingManager`.

#### Delegation Rewards

Delegation rewards are distributed in the call to `completeDelegatorRemoval` on the `StakingManager`.

#### Delegation Fees

Delegation fees owed to validators are _not_ distributed when the validation ends as to bound the amount of gas consumed in the call to `completeValidatorRemoval`. Instead, `claimDelegationFees` on the `StakingManager` may be called after the validation is completed.

# Customize Validator Manager (/docs/avalanche-l1s/validator-manager/custom-validator-manager)

---
title: Customize Validator Manager
description: Learn how to implement a custom Validator Manager on your Avalanche L1 blockchain.
---

The Validator Manager contracts provide a framework for managing validators on an Avalanche L1 blockchain, as defined in [ACP-77](https://github.com/avalanche-foundation/ACPs/tree/main/ACPs/77-reinventing-subnets). `ValidatorManager.sol` is the top-level abstract contract that provides basic functionality. Developers can build upon it to implement custom logic for validator management tailored to their specific requirements.

## Building a Custom Validator Manager

To implement custom validator management logic, you can create a new contract that inherits from `ValidatorManager` or one of its derived contracts (`PoSValidatorManager`, `PoAValidatorManager`, etc.). By extending these contracts, you can override existing functions or add new ones to introduce your custom logic.

**Inherit from the Base Contract**

   Decide which base contract suits your needs. If you require Proof-of-Stake functionality, consider inheriting from `PoSValidatorManager`. For Proof-of-Authority, `PoAValidatorManager` might be appropriate. If you need basic functionality, you can inherit directly from `ValidatorManager`.

   ```solidity
   pragma solidity ^0.8.0;

   import "./ValidatorManager.sol";

   contract CustomValidatorManager is ValidatorManager {
       // Your custom logic here
   }
   ```

### Override Functions

Override existing functions to modify their behavior. Ensure that you adhere to the function signatures and access modifiers.

```solidity
function initializeValidatorRegistration() public override {
    // Custom implementation
}
```
### Add Custom Functions

Introduce new functions that implement the custom logic required for your blockchain.

```solidity
function customValidatorLogic(address validator) public {
    // Implement custom logic
}
```
### Modify Access Control

Adjust access control as needed using modifiers like onlyOwner or by implementing your own access control mechanisms.

```solidity
modifier onlyValidator() {
    require(isValidator(msg.sender), "Not a validator");
    _;
}
```

### Integrate with the P-Chain

Ensure that your custom contract correctly constructs and handles Warp messages for interaction with the P-Chain, following the specifications in ACP-77.

### Testing

Thoroughly test your custom Validator Manager contract to ensure it behaves as expected and adheres to the required protocols.

Example: Custom Reward Logic
Suppose you want to implement a custom reward distribution mechanism. You can create a new contract that inherits from PoSValidatorManager and override the reward calculation functions.

```solidity

pragma solidity ^0.8.0;

import "./PoSValidatorManager.sol";

contract CustomRewardValidatorManager is PoSValidatorManager {
    function calculateValidatorReward(address validator) internal view override returns (uint256) {
        // Implement custom reward calculation logic
        return super.calculateValidatorReward(validator) * 2; // Example: double the reward
    }

    function calculateDelegatorReward(address delegator) internal view override returns (uint256) {
        // Implement custom delegator reward calculation logic
        return super.calculateDelegatorReward(delegator) / 2; // Example: halve the reward
    }
}
```

### Considerations
**Security Audits**: Custom contracts should be audited to ensure security and correctness.

**Compliance with ACP-77**: Ensure your custom logic complies with the specifications of ACP-77 to maintain compatibility with Avalanche's protocols.

**Upgradeable Contracts**: If you plan to upgrade your contract in the future, follow best practices for upgradeable contracts.

### Conclusion
Building on top of `ValidatorManager.sol` allows you to customize validator management to fit the specific needs of your Avalanche L1 blockchain. By extending and modifying the base contracts, you can implement custom staking mechanisms, reward distribution, and access control tailored to your application.

# PoA vs PoS (/docs/avalanche-l1s/validator-manager/poa-vs-pos)

---
title: PoA vs PoS
description: Learn the differences between Proof of Authority and Proof of Stake Validator Manager contracts.
---
import { Steps, Step } from 'fumadocs-ui/components/steps';

## Overview

At a high level, the `ValidatorManager` abstract can be used to manage the validator set on the P-Chain.

<Steps>
<Step>
- Proof of Authority networks are secured by validators who can be added or removed from the `PoAValidatorManager` implementation by an owner address. 
- Proof of Stake networks are secured by validators who stake some type of tokens for a duration into an implementation of `PoSValidatorManager`.
</Step>
<Step>
Once the transaction confirms, the `ValidatorManager` (which both `PoAValidatorManager` and `PoSValidatorManager` inherit) emits a warp message.
</Step>
<Step>
The warp message is signed off by quorum of the current validator set and submitted to the P-Chain.
</Step>
<Step>
The P-Chain then adds, removes or modifies the validator in the registry using information from the warp message. 
</Step>
</Steps>


## Proof of Authority

There is one implementation of Proof of Authority based on the `ValidatorManager` abstract called `PoAValidatorManager`.

In the `PoAValidatorManager` implementation, the owner of the contract can add and remove validators from the set. The owner can also set the weight of the validator.
The owner can either be a smart contract or an EOA.

### Rewards

By default, no rewards are distributed to validators in the `PoAValidatorManager` implementation. However, rewards can be distributed to validators by extending the `PoAValidatorManager` contract and adding the desired functionality.   

### Parameters

The `PoAValidatorManager` has a couple of parameters that it can be initialized with to fit the needs of the network. These parameters include:
- `ChurnPeriodSeconds`: The time period in seconds that a validator must wait before being removed from the set.
- `MaximumChurnPercentage`: The maximum percentage of the validator set that can be removed in a single churn period.

## Proof of Stake

There are two implmentations offered of Proof of Stake based on the `PoSValidatorManager` abstract:

- `NativeTokenStakingManager`: This contract is used for staking native tokens.
- `ERC20TokenStakingManager`: This contract is used for staking ERC20 tokens.

These are both permissionless implementations, meaning that anyone can stake tokens and become a validator. 

<Callout>
The `PoSValidatorManager` abstract also comes with a notion of `delegation`. Delegators can delegate their tokens to a validator. This will increase the validator's weight and the delegator will receive a portion of the rewards.
</Callout>

### Rewards

Rewards are calculated using a `RewardCalculator` contract. The `PoSValidatorManager` will distribute rewards to the validator based off their node's liveliness in consensus and after the validator is removed from the set.

In the `NativeTokenStakingManager` implmentation, rewards are minted through use of the `NativeMinter` precompile. Which the address of `NativeTokenStakingManager` is enabled on.

In the `ERC20TokenStakingManager` implementation, rewards are minted through calling the ERC20 token's `mint` function.

### Parameters

The `PoSValidatorManager` has a number of parameters that it can be initialized with to fit the needs of the network. These parameters include:

- `MinimumStakeAmount`: The minimum amount of tokens required to stake.
- `MaximumStakeAmount`: The maximum amount of tokens required to stake.
- `MinimumStakeDuration`: The minimum duration that tokens must be staked for.
- `MinimumDelegationFeeBips`: The minimum fee charged to delegators for delegating their tokens.
- `MaximumStakeMultiplier`: The maximum multiplier that can be applied to a validator's weight.
- `WeightToValueFactor`: The factor used to convert a validator's weight to a value.
- `RewardCalculator`: The address of the reward calculator contract.



## Customization

The `ValidatorManager` abstract contract is designed to be flexible and can be easily extensible to fit the needs of the network.

For example, the `PoSValidatorManager` abstract could be extended to include additional parameters or functionality. This can be done by creating a new contract that inherits from the `PoSValidatorManager` abstract and adding the desired functionality such as NFT staking, slashing, or additional rewards for certain actions.







# Remove Validator (/docs/avalanche-l1s/validator-manager/remove-validator)

---
title: Remove Validator
description: Learn how to remove validators from your Avalanche L1 blockchain.
---

### Remove a Validator

Validator exit is initiated with a call to `initializeEndValidation` on the `ValidatorManager`. Only the validator owner may initiate exit. For `PoSValidatorManagers` a `ValidationUptimeMessage` Warp message may optionally be provided in order to calculate the staking rewards; otherwise the latest received uptime will be used (see [(PoS only) Submit an Uptime Proof](/docs/avalanche-l1s/validator-manager/contract#pos-only-submit-an-uptime-proof)). This proof may be requested directly from the L1 validators, which will provide it in a `ValidationUptimeMessage` Warp message. If the uptime is not sufficient to earn validation rewards, the call to `initializeEndValidation` will fail. `forceInitializeEndValidation` acts the same as `initializeEndValidation`, but bypasses the uptime-based rewards check. Once `initializeEndValidation` or `forceInitializeEndValidation` is called, staking rewards cease accruing for `PoSValidatorManagers`.

The `ValidatorManager` constructs an `L1ValidatorWeightMessage` Warp message with the weight set to `0`. This is delivered to the P-Chain as the payload of a `SetL1ValidatorWeightTx`. The P-Chain acknowledges the validator exit by signing an `L1ValidatorRegistrationMessage` with `valid=0`, which is delivered to the `ValidatorManager` by calling `completeEndValidation`. The validation is removed from the contract's state, and for `PoSValidatorManagers`, staking rewards are disbursed and stake is returned.

#### Disable a Validator Directly on the P-Chain

ACP-77 also provides a method to disable a validator without interacting with the L1 directly. The P-Chain transaction `DisableL1ValidatorTx` disables the validator on the P-Chain. The disabled validator's weight will still count towards the L1's total weight.

Disabled L1 validators can re-activate at any time by increasing their balance with an `IncreaseBalanceTx`. Anyone can call `IncreaseBalanceTx` for any validator on the P-Chain. A disabled validator can only be completely and permanently removed from the validator set by a call to `initializeEndValidation`.


### (PoS only) Remove a Delegator

Delegators removal may be initiated by calling `initializeEndDelegation`, as long as churn restrictions are not violated. Similar to `initializeEndValidation`, an uptime proof may be provided to be used to determine delegator rewards eligibility. If no proof is provided, the latest known uptime will be used (see [(PoS only) Submit an Uptime Proof](/docs/avalanche-l1s/validator-manager/contract#pos-only-submit-an-uptime-proof)). The validator's weight is updated on the P-Chain by the same mechanism used to register a delegator. The `L1ValidatorWeightMessage` from the P-Chain is delivered to the `PoSValidatorManager` in the call to `completeEndDelegation`.

Either the delegator owner or the validator owner may initiate removing a delegator. This is to prevent the validator from being unable to remove itself due to churn limitations if it has too high a proportion of the Subnet's total weight due to delegator additions. The validator owner may only remove Delegators after the minimum stake duration has elapsed.


### (PoS only) Collect Staking Rewards

#### Submit an Uptime Proof

The rewards calculator is a function of uptime seconds since the validator's start time. In addition to doing so in the calls to `initializeEndValidation` and `initializeEndDelegation` as described above, uptime proofs may also be supplied by calling `submitUptimeProof`. Unlike `initializeEndValidation` and `initializeEndDelegation`, `submitUptimeProof` may be called by anyone, decreasing the likelihood of a validation or delegation not being able to claim rewards that it deserved based on its actual uptime.

#### Validation Rewards

Validation rewards are distributed in the call to `completeEndValidation`.

#### Delegation Rewards

Delegation rewards are distributed in the call to `completeEndDelegation`.

#### Delegation Fees

Delegation fees owed to validators are _not_ distributed when the validation ends as to bound the amount of gas consumed in the call to `completeEndValidation`. Instead, `claimDelegationFees` may be called after the validation is completed.


# Upgrade Validator Manager (/docs/avalanche-l1s/validator-manager/upgrade)

---
title: Upgrade Validator Manager
description: Learn how to upgrade the Validator Manager on your Avalanche L1 blockchain from PoA to PoS.
---

## Convert PoA to PoS

A `PoAValidatorManager` can later be converted to a `PoSValidatorManager` by upgrading the implementation contract pointed to by the proxy. After performing the upgrade, the `PoSValidatorManager` contract should be initialized by calling `initialize` as described above. The validator set contained in the `PoAValidatorManager` will be tracked by the `PoSValidatorManager` after the upgrade, but these validators will neither be eligible to stake and earn staking rewards, nor support delegation.


# Add Network Programmatically (/docs/dapps/advanced-tutorials/add-network-programmatically)

---
title: Add Network Programmatically
description: This document shows how to integrate Avalanche Network with your dApp, either using Core or MetaMask.
---

## Core

Powered by Avalanche, [Core](https://core.app/en/) is an all-in-one operating system bringing together Avalanche apps, Avalanche L1s, bridges, and NFTs in one seamless, high-performance browser experience. Putting in another way, Core is more than a wallet. It is a curated web3 operating system combining Wallet, Explorer, Bridge, Avalanche L1s, dApps, and more.

Getting a Dapp ready to connect to Core is made simple with pre-built tools from the Core Team.

First download and install the Core browser extension from [here](https://chrome.google.com/webstore/detail/core/agoakfejjabomempkjlepdflaleeobhb).

[avalanche-dapp-sdks](https://github.com/ava-labs/avalanche-dapp-sdks) contains an example of how to connect via @web3-react/core to the Core extension specifically.

```rust
git clone https://github.com/ava-labs/avalanche-dapp-sdks.git
cd avalanche-dapp-sdks
yarn bootstrap
```

<Callout title="Note">
The repository cloning method used is HTTPS, but SSH can be used too:

`git clone git@github.com:ava-labs/avalanche-dapp-sdks.git`

You can find more about SSH and how to use it [here](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/about-ssh).   
</Callout>

Then check out [this sample project under `packages/avalanche-connector-example`](https://github.com/ava-labs/avalanche-dapp-sdks/tree/alpha-release/packages/web3-react-core-connector)

```rust
cd packages/avalanche-connector-example
npm start
```

If everything works as expected, you should be able to load \[http://localhost:3000/\] on your browser, click on the "Connect Avalanche" button on the page as below:

![connect core](/images/add-network1.jpeg)

Check out the [README](https://github.com/ava-labs/avalanche-dapp-sdks/tree/alpha-release/packages/web3-react-core-connector) to see details how this works and use it to fit your needs.

This [Google Drive](https://drive.google.com/drive/folders/1pQ98mIs65ET9JBGThzAAlGKv85BuQCAu?usp=sharing) has the assets needed to create a **Connect with Core** button.

## MetaMask

Adding new networks to MetaMask is not a trivial task for people that are not technically savvy, and it can be error prone. To help easier onboarding of users to your application it is useful to simplify that process as much as possible.

This tutorial will show how to build a simple button in your front-end application that will automate the process of adding the Avalanche network to MetaMask.

### EIP-3035

[EIP-3035](https://eips.ethereum.org/EIPS/eip-3085) is an [Ethereum Improvement Proposal](https://eips.ethereum.org/) that defines an RPC method for adding Ethereum-compatible chains to wallet applications.

Since March 2021 MetaMask has implemented that EIP as part of their MetaMask [Custom Networks API](https://consensys.net/blog/metamask/connect-users-to-layer-2-networks-with-the-metamask-custom-networks-api/).

Let's see how it works.

#### Data Structures

To add the Avalanche network to MetaMask, we need to prepare the data structures that will be contain all the necessary data.

Main network data:

```rust
export const AVALANCHE_MAINNET_PARAMS = {
  chainId: "0xA86A",
  chainName: "Avalanche Mainnet C-Chain",
  nativeCurrency: {
    name: "Avalanche",
    symbol: "AVAX",
    decimals: 18,
  },
  rpcUrls: ["https://api.avax.network/ext/bc/C/rpc"],
  blockExplorerUrls: ["https://snowtrace.io/"],
};
```

Test network data:

```rust
export const AVALANCHE_TESTNET_PARAMS = {
  chainId: "0xA869",
  chainName: "Avalanche Testnet C-Chain",
  nativeCurrency: {
    name: "Avalanche",
    symbol: "AVAX",
    decimals: 18,
  },
  rpcUrls: ["https://api.avax-test.network/ext/bc/C/rpc"],
  blockExplorerUrls: ["https://testnet.snowtrace.io/"],
};
```

### Adding the Network

To add the network to MetaMask, we need to call the `wallet_addEthereumChain` method, exposed by the web3 provider.

```rust
function addAvalancheNetwork() {
  injected.getProvider().then((provider) => {
    provider
      .request({
        method: "wallet_addEthereumChain",
        params: [AVALANCHE_MAINNET_PARAMS],
      })
      .catch((error: any) => {
        console.log(error);
      });
  });
}
```

Where `injected` is initialized as a `web3-react/injected-connector` used to interface with MetaMask APIs. Usage for other popular web frameworks is similar. Replace `AVALANCHE_MAINNET_PARAMS` with `AVALANCHE_TESTNET_PARAMS` if you want to add the test network.

Typical usage pattern would be to expose a button calling that method if you get `Wrong Network` or `Error connecting` errors when attempting to establish a connection to MetaMask.

### User Experience

When users first come to your dapp's website they need to approve connection to MetaMask. After they do that, if you don't detect successful web3 network connection, you can present them with a dialog asking them to confirm switch to a new network:

![wrong network](/images/add-network2.png)

If they press the button, they are shown a dialog from MetaMask asking for approval to add the new network:

![add a network](/images/add-network3.png)

If they approve, your app will be connected to the Avalanche network. Very easy, no need for any data entry, no chance of wrong data entry. And that's it, users are ready to interact with your dapp!

## Conclusion

Dapp users are often not very technically sophisticated and onboarding them needs to be as seamless and easy as possible. Manually adding a new network is a hurdle than a certain percentage of your potential users will not be able to clear. Removing that requirement is a simple step that will enhance their experience and enable more users to get to actually use your dapp.

If you have any questions, problems, or ideas on how to improve, or simply want to join our developer community, you can contact us on our [Discord](https://chat.avalabs.org/) server.


# Dynamic Gas Fees (/docs/dapps/advanced-tutorials/dynamic-gas-fees)

---
title: Dynamic Gas Fees
description: Learn how to send transactions with dynamic fees using JavaScript.
---

The objective of this document is to provide and explain sending transactions with dynamic fees using JavaScript. Make sure you have followed [the tutorial on adjusting the dynamic fees using MetaMask](/docs/dapps/advanced-tutorials/manually-adjust-gas-price). There, we have explained the key concepts related to dynamic fees and EIP1559 type of transactions.

## Prerequisites

- Basic familiarity with [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript).
- Basic familiarity with [Node.js](https://nodejs.org/en) and [npm](https://www.npmjs.com/).
- Basic familiarity with [the Avalanche C-Chain](/docs/api-reference/c-chain/api) network and [EVM compatibility](https://ethereum.org/en/developers/docs/evm/)
- Basic understanding of [dynamic fee transactions](/docs/dapps/advanced-tutorials/manually-adjust-gas-price#good-to-know-keywords-and-concepts)

## Installing Dependencies

Open the terminal and install the following dependencies in a new folder.

- Ethers
- avalanche
- dotenv

```bash
npm install ethers avalanche dotenv
```

## Setting up Environment and Project

To send a transaction we need to sign it using our private key. But private key should not be hard coded in the code, rather must be fetched through some environment variables. Make a `.env` file in the root folder with the following content.

```bash
PRIVATEKEY=<YOUR_PRIVATE_KEY>
```

Now make a new file `app.js` in the root folder, which will be our main and only file with the `sendAvax()` function. Follow the rest of the tutorial by understanding and pasting the provided snippets sequentially in the `app.js` file.

## Importing Dependencies and Private Key

```rust
const ethers = require("ethers");
const Avalanche = require("avalanche").Avalanche;
require("dotenv").config();

const privateKey = process.env.PRIVATEKEY;
```

## Setting up HTTP Provider

Using the HTTP provider, we will connect to one of the nodes on the Fuji network. Using this provider we will send the signed transaction to the network. You can also connect to Mainnet using the URL - `https://api.avax.network/ext/bc/C/rpc`

```rust
// For sending a signed transaction to the network
const nodeURL = "https://api.avax-test.network/ext/bc/C/rpc";
const HTTPSProvider = new ethers.providers.JsonRpcProvider(nodeURL);
```

## Setup C-Chain APIs to Estimate Fees

To estimate the max fee and max priority fee on the network, we will be using C-Chain APIs. We can use the C-Chain through an AvalancheJS instance connected to the network as shown below.

```rust
// For estimating max fee and priority fee using CChain APIs
const chainId = 43113;
const avalanche = new Avalanche(
  "api.avax-test.network",
  undefined,
  "https",
  chainId
);
const cchain = avalanche.CChain();
```

### Function for Estimating Max Fee and Max Priority Fee

The function `calcFeeData()` estimates the max fee and max priority fee per gas according to network activity using the C-Chain APIs. This function returns max fee and max priority fee per gas in units of `nAVAX` or `gwei` (1 AVAX = 10^9 gwei).

```rust
// Function to estimate max fee and max priority fee
const calcFeeData = async (
  maxFeePerGas = undefined,
  maxPriorityFeePerGas = undefined
) => {
  const baseFee = parseInt(await cchain.getBaseFee(), 16) / 1e9;
  maxPriorityFeePerGas =
    maxPriorityFeePerGas == undefined
      ? parseInt(await cchain.getMaxPriorityFeePerGas(), 16) / 1e9
      : maxPriorityFeePerGas;
  maxFeePerGas =
    maxFeePerGas == undefined ? baseFee + maxPriorityFeePerGas : maxFeePerGas;

  if (maxFeePerGas < maxPriorityFeePerGas) {
    throw "Error: Max fee per gas cannot be less than max priority fee per gas";
  }

  return {
    maxFeePerGas: maxFeePerGas.toString(),
    maxPriorityFeePerGas: maxPriorityFeePerGas.toString(),
  };
};
```

Actual API returns base fee and priority fee in units of `wei` which is one-billionth of a billionth of `AVAX` (1 AVAX = 10^18 wei).

## Setting up Wallet

A wallet is required for signing transactions with your private key and thus making it valid.

```javascript
// For signing an unsigned transaction
const wallet = new ethers.Wallet(privateKey);
const address = wallet.address;
```

## Function to Create, Sign and Send Transaction

The function `sendAvax()` takes 4 arguments -

- `amount` - Amount of AVAX to send in the transaction
- `address` - Destination address to which we want to send AVAX
- `maxFeePerGas` - Desired maximum fee per gas you want to pay in nAVAX
- `maxPriorityFeePerGas` - Desired maximum priority fee per gas you want to pay in nAVAX
- `nonce` - Used as a differentiator for more than 1 transaction with same signer

The last 3 arguments are optional, and if `undefined` is passed, then it will use the `calcFeeData()` function to estimate them. Each transaction with the same data and parameters is differentiated by a nonce value. If there are more than 1 transactions with the same nonce signed by the same address, then only 1 of them with the highest effective priority fee will be accepted. `nonce` parameter should only be used when you are either re-issuing or cancelling a stuck transaction.

```rust
// Function to send AVAX
const sendAvax = async (
  amount,
  to,
  maxFeePerGas = undefined,
  maxPriorityFeePerGas = undefined,
  nonce = undefined
) => {
  if (nonce == undefined) {
    nonce = await HTTPSProvider.getTransactionCount(address);
  }

  // If the max fee or max priority fee is not provided, then it will automatically calculate using CChain APIs
  ({ maxFeePerGas, maxPriorityFeePerGas } = await calcFeeData(
    maxFeePerGas,
    maxPriorityFeePerGas
  ));

  maxFeePerGas = ethers.utils.parseUnits(maxFeePerGas, "gwei");
  maxPriorityFeePerGas = ethers.utils.parseUnits(maxPriorityFeePerGas, "gwei");

  // Type 2 transaction is for EIP1559
  const tx = {
    type: 2,
    nonce,
    to,
    maxPriorityFeePerGas,
    maxFeePerGas,
    value: ethers.utils.parseEther(amount),
    chainId,
  };

  tx.gasLimit = await HTTPSProvider.estimateGas(tx);

  const signedTx = await wallet.signTransaction(tx);
  const txHash = ethers.utils.keccak256(signedTx);

  console.log("Sending signed transaction");

  // Sending a signed transaction and waiting for its inclusion
  await (await HTTPSProvider.sendTransaction(signedTx)).wait();

  console.log(
    `View transaction with nonce ${nonce}: https://testnet.snowtrace.io/tx/${txHash}`
  );
};
```

This function calculates transaction hash from the signed transaction and logs on the console, the URL for transaction status on the Snowtrace explorer.

## Calling the `sendAVAX()` Function

There are various ways to call this function. We may or may not pass the optional arguments like max fee and max priority fee. It is recommended to set the max fee as the maximum price per gas that you are willing to pay for a transaction, no matter how high or low the base fee will be, as at max you will only be charged the provided max fee, along with a small priority fee above the base fee.

If you do not pass these arguments, then it will automatically estimate the max fee and priority fee from the network. For example, let's say, I want to pay 100 nAVAX per gas for a transaction and a small tip of 2 nAVAX, then we will call the following function.

```rust
// setting max fee as 100 and priority fee as 2
sendAvax("0.01", "0x856EA4B78947c3A5CD2256F85B2B147fEBDb7124", 100, 2);
```

This function should not be used without a max fee per gas. As you will have to pay the estimated price, even if it is higher than your budget. There could be the following cases:

|    Max Fee    | Max Priority Fee |                                                                                                                  Comment                                                                                                                  |
|:-------------:|:----------------:|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------:|
| **undefined** | 2                | It will calculate the max fee by adding the provided priority fee with the estimated base fee. Take extra precaution here as the max fee will now be capped by `baseFee + priorityFee`, which can consume all the provided priority fees. |
| 100           | **undefined*-  | It will estimate the priority fee and use the provided max fee. If the estimated priority fee is more than the provided max fee, then it throws an error.                                                                                 |
| **undefined** | **undefined*-  | It will estimate the base fee and priority fee from the network, and will add both the values to calculate the max fee per gas. Again, you have to pay whatever will be estimated.                                                        |

You will get the following output on the successful submission of the signed transactions. Using this URL you can view the status of your transaction on Snowtrace.

```
View transaction with nonce 25: https://testnet.snowtrace.io/tx/0xd5b92b85beaf283fbaeeefb95c9a17a6b346a05b6f9687f2d6e421aa79243b35
```

## Reissuance of Stuck Transaction

Sometimes during high network activity, all transactions couldn't make it to the latest blocks for a long time, due to relatively lower effective tip than the other transactions in the pool. We can either re-issue the same transaction with a higher priority fee or cancel the transaction. To re-issue the stuck transaction, you can send a new one with same amount and data but higher priority fee and same nonce value as the stuck transaction. The transaction with lower effective tip will automatically be rejected (due to same nonce), and you do not need to worry about it. You can also cancel the stuck transaction, by keeping the amount to 0, with a higher priority fee and same nonce. Let's say, the above transaction with a nonce value of 25 has stuck. You can then re-issue a new transaction with same nonce, but higher priority fee this time.

```rust
// reissuing transaction with nonce 25
sendAvax("0.01", "0x856EA4B78947c3A5CD2256F85B2B147fEBDb7124", 100, 10, 25);

// cancelling transaction with nonce 25
sendAvax("0", "0x856EA4B78947c3A5CD2256F85B2B147fEBDb7124", 100, 10, 25);
```

## Conclusion

You have learned about creating, signing, and sending transactions with dynamic fee parameters to the C-Chain of Avalanche network using JavaScript. It also explained, how to re-issue or cancel a stuck transaction, by sending a transaction with the same nonce. This tutorial points out the recommended way for choosing max fee cap and max priority fee cap for transactions and can also work as a general guide for all the EVM-based chains.


# Exchange Integration (/docs/dapps/advanced-tutorials/exchange-integration)

---
title: Exchange Integration
description: Learn how to integrate your exchange with the EVM-Compatible Avalanche C-Chain.
---

## Overview

The objective of this document is to provide a brief overview of how to
integrate with the EVM-Compatible Avalanche C-Chain.

For teams that already
support ETH, supporting the C-Chain is as straightforward as spinning up an
Avalanche node (which has the [same API](https://ethereum.org/en/developers/docs/apis/json-rpc/) as
[`go-ethereum`](https://geth.ethereum.org/docs/rpc/server)) and populating
Avalanche's ChainID (43114) when constructing transactions.

Additionally, Ava Labs maintains an implementation of the [Rosetta
API](https://docs.cdp.coinbase.com/mesh/docs/welcome) for the C-Chain called
[avalanche-rosetta](https://github.com/ava-labs/avalanche-rosetta). You can
learn more about this standardized integration path on the attached Rosetta API
website.

## Integration Using EVM Endpoints

### Running an Avalanche Node

If you want to build your node form source or include it in a docker image,
reference the [AvalancheGo GitHub
repository](https://github.com/ava-labs/avalanchego). To quickly get up and
running, you can use the [node installation script](/docs/nodes/using-install-script/installing-avalanche-go) that automates installing
and updating AvalancheGo node as a `systemd` service on Linux, using prebuilt
binaries.

### Configuring an Avalanche Node

All configuration options and their default values are described [here](/docs/nodes/configure/configs-flags).

You can supply configuration options on the command line, or use a config file,
which can be easier to work with when supplying many options. You can specify
the config file location with `—config-file=config.json`, where `config.json` is
a JSON file whose keys and values are option names and values.

Individual chains, including the C-Chain, have their own configuration options
which are separate from the node-level options. These can also be specified in a
config file. For more details, see
[here](/docs/nodes/chain-configs/c-chain).

The C-Chain config file should be at
`$HOME/.avalanchego/configs/chains/C/config.json`. You can also tell AvalancheGo
to look somewhere else for the C-Chain config file with option
`--chain-config-dir`. An example C-Chain config file:

<Callout type="warn">
If you need Ethereum's [Archive
Node](https://ethereum.org/en/developers/docs/nodes-and-clients/#archive-node)
functionality, you need to disable C-Chain pruning, which has been enabled by
default since AvalancheGo v1.4.10. To disable pruning, include
`"pruning-enabled": false` in the C-Chain config file as shown below.
</Callout>

```json
{
  "snowman-api-enabled": false,
  "coreth-admin-api-enabled": false,
  "local-txs-enabled": true,
  "pruning-enabled": false,
  "eth-apis": [
    "internal-eth",
    "internal-blockchain",
    "internal-transaction",
    "internal-tx-pool",
    "internal-account",
    "internal-personal",
    "debug-tracer",
    "web3",
    "eth",
    "eth-filter",
    "admin",
    "net"
  ]
}
```

### Interacting with the C-Chain

Interacting with the C-Chain is identical to interacting with
[`go-ethereum`](https://geth.ethereum.org/). You can find the reference material
for C-Chain API [here](/docs/api-reference/c-chain/api).

Please note that `personal_` namespace is turned off by default. To turn it on,
you need to pass the appropriate command line switch to your node, like in the
above config example.

## Integration Using Rosetta

[Rosetta](https://docs.cdp.coinbase.com/mesh/docs/welcome) is an open-source specification and set
of tools that makes integrating with different blockchain networks easier by
presenting the same set of APIs for every network. The Rosetta API is made up of
2 core components, the [Data
API](https://docs.cdp.coinbase.com/mesh/docs/api-data) and the
[Construction
API](https://docs.cdp.coinbase.com/mesh/docs/api-construction).

Together, these APIs allow for anyone to read and write to blockchains in a
standard format over a standard communication protocol. The specifications for
these APIs can be found in the
[rosetta-specifications](https://github.com/coinbase/rosetta-specifications)
repository.

You can find the Rosetta server implementation for Avalanche C-Chain
[here](https://github.com/ava-labs/avalanche-rosetta), all you need to do is
install and run the server with proper configuration. It comes with a `Dockerfile`
that packages both the server and the Avalanche client. Detailed instructions
can be found in the linked repository.

## Constructing Transactions

Avalanche C-Chain transactions are identical to standard EVM transactions with 2 exceptions:

- They must be signed with Avalanche's ChainID (43114).
- The detailed dynamic gas fee can be found [here](/docs/api-reference/guides/txn-fees#c-chain-fees).

For development purposes, Avalanche supports all the popular tooling for
Ethereum, so developers familiar with Ethereum and Solidity can feel right at
home. We have tutorials and repositories for several popular development
environments:

- [Core and Remix](/docs/dapps/smart-contract-dev/deploy-with-remix-ide)
- [thirdweb](/docs/dapps/toolchains/thirdweb)
- [Hardhat](/docs/dapps/toolchains/hardhat)

## Ingesting On-Chain Data

You can use any standard way of ingesting on-chain data you use for Ethereum network.

### Determining Finality

Avalanche consensus provides fast and irreversible finality with 1-2 seconds. To
query the most up-to-date finalized block, query any value (that is block, balance,
state, etc) with the `latest` parameter. If you query above the last finalized
block (that is eth_blockNumber returns 10 and you query 11), an error will be
thrown indicating that unfinalized data cannot be queried (as of
`avalanchego@v1.3.2`).

### (Optional) Custom Golang SDK

If you plan on extracting data from the C-Chain into your own systems using
Golang, we recommend using our custom
[`ethclient`](https://github.com/ava-labs/coreth/tree/master/ethclient). The
standard `go-ethereum` Ethereum client does not compute block hashes correctly
(when you call `block.Hash()`) because it doesn't take into account the added
[ExtDataHash](https://github.com/ava-labs/coreth/blob/2c3cfac5f766ce5f32a2eddc43451bdb473b84f1/core/types/block.go#L98)
header field in Avalanche C-Chain blocks, which is used move AVAX between chains
(X-Chain and P-Chain). You can read more about our multi-chain abstraction
[here](/docs/quick-start/primary-network) (out of scope for a
normal C-Chain integration).

If you plan on reading JSON responses directly or use web3.js (doesn't recompute
hash received over the wire) to extract on-chain transaction data/logs/receipts,
you shouldn't have any issues!

## Support

If you have any problems or questions, reach out either directly to our
developers, or on our public [Discord](https://chat.avalabs.org/) server.


# Manually Adjust Gas Price (/docs/dapps/advanced-tutorials/manually-adjust-gas-price)

---
title: Manually Adjust Gas Price
description: Learn how to manually adjust gas price using MetaMask.
---

Sometimes during periods of high network activity, transactions either remain pending for a very long duration or instantly get a failed transaction notification. This may confuse and frustrate users, especially if they don't understand why their transactions are not getting accepted.

## Probable Reasons You Are Here

- Your transaction has stalled, and you don't know what to do
- Your transaction has failed, with an error - `transaction underpriced`
- It's your first transaction, and you want to be sure about any potential issues
- Just for general knowledge on adjusting dynamic fee settings

If these are your reasons for being here, then you can either go through this entire section, for a better understanding of the scenario or directly skip to the [solution](#adjusting-gas-fees-before-submitting-the-transaction).

## Good to Know Keywords and Concepts

The amount of computation used by a transaction is measured in units of `gas`. Each unit of gas is paid for in AVAX at the `gas price` for the transaction. The `gas price` of the transaction is determined by the parameters of the transaction and the `base fee` of the block that it is included in.

To avoid draining the user's wallet due to non-terminating execution through the EVM, transactions are submitted with a `gas limit`, which denotes the maximum units of gas that a particular transaction is allowed to consume.

If a transaction attempts to use more than this limit, then the transaction will revert and still consume and pay for the full `gas limit`. Total fees paid by the user can be calculated as `(gas consumed) * (gas price)`, and is known as `gas fees`. Similarly, maximum gas fees can be calculated as `(gas limit) * (gas price)`.

Originally, transactions could only set a single parameter to define how much they were willing to pay for gas: `gas price`. When dynamic fees were introduced, EIP-1559 style transactions were introduced as well which contain two parameters `maxFeeCap` and `maxPriorityFee` to determine the price a transaction is willing to pay.

With the introduction of dynamic fees, legacy style transactions that only have a single `gas price` parameter can lead to both delayed transactions and overpaying for transactions. Dynamic fee transactions are the solution! For more info, read [this](/docs/api-reference/standards/guides/txn-fees#dynamic-fee-transactions).

For the dynamic fee algorithm, when a block is produced or verified, we look over the past 10s to see how much gas has been consumed within that window (with an added charge for each block produced in that window) to determine the current network utilization. This window has a target utilization, which is currently set to `15M` gas units.

Lastly, there is an added charge if a block is produced faster than the target rate of block production. Currently, the target rate of block production is one block every two seconds, so if a new block is produced one second after its parent, then there is an additional surcharge added into the base fee calculation.

Base price could increase, decrease, or remain the same depending upon the amount of activity on the network in the most recent window. If the total gas in the last few blocks of the window is more, less or the same than the target gas, then the base price will increase, decrease, or remain the same, respectively.

When estimating the base fee for users, we simply look at the currently preferred block and calculate what the base fee would be for a block built on top of that block immediately.

Along with a gas limit, users can now pass 2 values in dynamic fee transactions: `gas fee cap` and `gas tip cap`.

The maximum price per unit of gas, that the user is willing to pay for their transaction is called `gas fee cap`. If the base price for a block is more than the gas fee cap, then the transaction will remain in the transaction pool until the base fee has been changed to be less than or equal to the provided gas fee cap.

<Callout title="Note">
The transaction pool limits the number of pending transactions, so if the number of pending transactions exceeds the configured cap then the transactions with the lowest fees may be evicted from the transaction pool and need to be re-issued.
</Callout>

`Gas tip cap` is the maximum price per unit of gas, that the user is willing to pay above the base price to prioritize their transaction. But the tip is capped by both the gas tip cap as well as the gas fee cap. The actual tip paid above the `base fee` of the block is known as the `effective gas tip`.

```
EffectiveTip = min(MaxFeeCap - BaseFee, GasTipCap)
```

Consider the following examples (here Gwei or nAVAX is one-billionth of AVAX) -

|Transaction|Max Fee Cap|Gas tip cap|Base price|Effective tip|Total price|
|-----------|-----------|-----------|----------|-------------|-----------|
|1          |50 Gwei    |0 Gwei     |25 Gwei   |0 Gwei       |25 Gwei    |
|2          |50 Gwei    |0 Gwei     |50 Gwei   |0 Gwei       |50 Gwei    |
|3          |50 Gwei    |0 Gwei     |60 Gwei   |0 Gwei       |PENDING    |
|A          |50 Gwei    |10 Gwei    |40 Gwei   |10 Gwei      |50 Gwei    |
|B          |40 Gwei    |40 Gwei    |40 Gwei   |0 Gwei       |40 Gwei    |

Look at transactions **A** and **B** (the bottom two transactions). In these scenarios, it looks like transaction B is paying a higher tip, however, this depends on the base fee of the block where the transactions are included.

The effective tip of A is more than that of B. So, if both of these transaction competes for being included in the next block, then the validators would prioritize transaction A since it pays a higher effective tip.

## Why My Transaction is on Hold or Failing?

If your transaction is failing and giving an error - `transaction underpriced`, then the max fee cap of your transaction must be less than the minimum base price that the network supports (as of now, it's 25 nAVAX or Gwei). Although the base fee is automatically estimated in wallets like Core or MetaMask, you can try increasing the max fee cap in the wallet.

During a period of heavy congestion on the network, all submitted transactions can't be included in the same block, due to the block's gas limit. So, validators choose transactions giving higher priority to transactions with the highest effective tips.

Another reason your transaction may get stuck in pending, is that the max fee cap may be below the current base fee that the network is charging. In this case, you need to increase the max fee cap of your transaction above the current base fee for it to be included in the block.

These fee adjustments can be made through wallets like Core or MetaMask.

## Adjusting Gas Fees Before Submitting the Transaction

You may not need to edit the gas fees on normal days. This is only required if there is heavy congestion on the network, and the base fees are frequently fluctuating.

1.  Let's create a sample transaction on Avalanche Mainnet, in which we will be sending 0.1 AVAX to a receiver using Core. Four predefined gas settings can be seen, which are Core's inbuilt gas estimation. To set a custom fee select “Custom” and enter the gas amount to use. By clicking on the **Settings** icon, we can review gas fees and the amount which we want to send.
    
    ![dynamic fees adjustment 1](/images/gas1.png)
    
2.  On this page, you can edit the priority fee (Max Priority Fee) and base fee (Max base fee). You can estimate the max fee as shown on [Snowtrace](https://snowtrace.io/gastracker), which represents the average max fee over the last 3 seconds. For more detailed statistics, you can have a look [here](https://stats.avax.network/dashboard/c-chain-activity/).
    
    ![dynamic fees adjustment 2](/images/gas2.png)
    
3.  If the network activity is high, you have to edit the priority and max fees accordingly, as given on Snowtrace. Consider the example below, where the average max fee is 26 Gwei (nAVAX).
    
    ![dynamic fees adjustment 3](/images/gas3.png)
    
4.  It is recommended to set the max fee cap as the maximum price that you are willing to pay for a transaction, no matter how high or low the base fee will be, as you will only be charged the minimum of base fee and the max fee cap, along with a small priority fee above the base fee. Now let's edit the max fee to 35 Gwei. This would ensure that our transaction would not fail until the base fee would exceed this amount. We can set a priority fee to anything between 0 and 35 Gwei. The higher the priority fee, the faster the transaction will be. For this example, let's set this to 2 Gwei. Now, save and send the transaction.
    
    ![dynamic fees adjustment 4](/images/gas4.png)
    
5.  After submitting the transaction, even if the base fee has decreased, you will only pay 2 Gwei above that fee as a priority fee. If this fee is one of the highest among the pending transactions, then it will be confirmed rapidly. We can see the confirmation of the transaction below.
    
    ![dynamic fees adjustment 5](/images/gas5.png)
    
    ![dynamic fees adjustment 6](/images/gas6.png)


# Deploy ERC-721 Contract (/docs/dapps/deploy-nft-collection/deploy-erc-721)

---
title: Deploy ERC-721 Contract
description: Learn how to deploy an ERC-721 contract on the Avalanche C-chain.
---

This tutorial will start you with a basic [ERC-721 (NFT)](https://eips.ethereum.org/EIPS/eip-721) smart contract on the Avalanche Network, regardless of your previous development experience. We'll deploy our NFT on the Avalanche Fuji Testnet and view it on the Snowtrace Testnet Explorer.

Note that these aren't transferable to the Mainnet. However, once you feel comfortable launching your project, you can do so on the Avalanche Mainnet and list it on an NFT marketplace.

The following tools will be used during this tutorial:

- [Pinata](https://www.pinata.cloud/): To store your NFT images and metadata.
- [OpenZeppelin's Wizard](https://wizard.openzeppelin.com/#erc721): to create the ERC-721 smart contract.
- [Remix IDE](https://remix-project.org/): To edit the code and deploy it to Fuji.
- [Avalanche Testnet Faucet](https://core.app/tools/testnet-faucet/): To fund the deployment.
- [Core browser Extension](https://chrome.google.com/webstore/detail/core-crypto-wallet-nft-ex/agoakfejjabomempkjlepdflaleeobhb): To process transactions related to funding and deploying the smart contract.
- [Snowtrace Testnet Explorer](https://testnet.snowtrace.io/): To view the deployed smart contract.

<Callout type="warn">
This Solidity smart contract tutorial is for demonstration purposes only. Users should consider proper precautions, error handling, and safeguards for production use. No one at Ava Labs is responsible for your development, and you must take full responsibility for ensuring your code is secure.
</Callout>

## Preparing Your NFT Files

The first step of setting up an NFT smart contract is having your NFT files ready to use. In this example, the files will get uploaded to Pinata, a pinning service that prevents files from being garbage collected on IPFS.

If you're unfamiliar with the process of uploading image and metadata files to an IPFS provider for NFT collection usage, please check out [this article on preparing NFT files](/docs/dapps/deploy-nft-collection/prep-nft-files). Ensure that your files are uploaded and your base URI is ready to plug into your smart contract.

Once the image and metadata files are ready, we can prepare to deploy a smart contract.

## Preparing Your Environment

### Core Extension

You'll need the Core Extension installed on whatever browser you're using to be able to fund the deployment of the smart contract. If you've not done so already, download Core and enable Testnet Mode. To do that, go to **Settings** and click on **Advanced**.

![Settings image 1](/images/nft-collection1.png)

Here, turn on the **Testnet Mode** feature. This will automatically make Core switch to Fuji Testnet.

![Settings image 2](/images/nft-collection2.png)

<Callout title="Note">
If you are using other wallets, like Core or MetaMask, you can add the Fuji Testnet using the following specs:

- **Network Name**: Avalanche C-Chain
- **New RPC URL**: `https://api.avax-test.network/ext/bc/C/rpc`
- **ChainID**: `43113`
- **Symbol**: AVAX
- **Explorer**: [`https://testnet.snowtrace.io`](https://testnet.snowtrace.io)
</Callout>

### Getting Testnet Funds

Because we're deploying on the Fuji Network, you'll need to get AVAX on the Fuji network.

**Option 1 (Recommended):** Create a [Builder Hub account](https://build.avax.network/login) and connect your wallet to receive testnet AVAX automatically.

**Option 2:** Use the [Avalanche Faucet](https://core.app/tools/testnet-faucet/). If you already have an AVAX balance greater than zero on Mainnet, paste your C-Chain address there, and request test tokens. Otherwise, please request a faucet coupon on [Guild](https://guild.xyz/avalanche). Admins and mods on the official [Discord](https://discord.com/invite/RwXY7P6) can provide testnet AVAX if developers are unable to obtain it from the other options.

![Avalanche Faucet](/images/nft-collection3.png)

## Creating the Smart Contract

To create the smart contract, we're going to use [Open Zeppelin](https://docs.openzeppelin.com/). Open Zeppelin is a key tool for building smart contracts quickly and easily. While we're only scratching the surface in this tutorial, ample documentation is available on their website for you to read when you want to build more complex contracts.

Open Zeppelin provides a [Contract Wizard](https://wizard.openzeppelin.com/#erc721) that will build out ERC contracts. To avoid any complex coding environments, we'll use this to create our ERC-721 contract.

![Contract Wizard](/images/nft-collection4.png)

Select `ERC-721` on the Contract Wizard to get started. This will create the contract in the [Solidity programming language](https://docs.soliditylang.org/en/v0.8.15/).

As you can see, the template contract is bare-boned. We'll fill out the information in the left panel to auto-populate it into our contract. Make sure you change to the ERC-721 tab as you get started to make the proper contract.

The Wizard auto-fills in a name and symbol for your NFT collection, which we'll modify here. I'm naming it `Photography` and giving it the symbol `FOTO`. If you chose your own files to use during this tutorial, you can choose a relevant name and symbol for your collection.

The Base URI field listed here is the URL of the metadata folder uploaded to Pinata(for example, ours is `https://gateway.pinata.cloud/ipfs/QmYdWxbiwsfsYcW1CYQPgYujAc9FMLPG3fgFcxFskbSsFa`). Paste that into the Base URI field. After the Wizard adds our variables to the template, our contract should look like this:

![Contract Wizard Populated](/images/nft-collection5.png)

Next, we'll want to check the `Mintable` and `Auto Increment Ids` boxes. This will populate a mint function into our template that would handle the incrementing of token Ids on mint if we had more than one NFT in our collection. We still want it to auto-assign our 1 NFT, so we'll check it.

This automatically checks the `Ownable` button, which gives the `safeMint` function the `onlyOwner` modifier. This modifier indicates that only the owner of the smart contract will be able to successfully call the function.

<Callout title="Note">
This modifier should be removed when creating a smart contract for a public mint. Otherwise, users wouldn't be able to successfully mint the NFTs when calling the `safeMint` function. This tutorial only handles the owner's wallet address, so it is being left in.
</Callout>

Now, our contract is a little more populated:

![Contract Wizard SafeMint](/images/nft-collection6.png)

For this simple example, we'll not add any additional functionality to the `safeMint` function. Currently, it mints one NFT to the address specified in the function call. There is no cost to mint the NFT other than the gas fee for the transaction itself.

This `safeMint` function currently doubles as an airdrop function because the address the NFT is minted to does not need to be the function owner. This functionality becomes very useful when NFT collection owners want to give away NFTs for free outside of the normal minting window.

At this point, our smart contract is ready. At the top, you can click `Open in Remix` to get ready to deploy your smart contract.

![Contract Wizard Open Remix](/images/nft-collection7.png)

## Deploying the Smart Contract with Remix

[Remix IDE](https://remix.ethereum.org/) is a solidity compiler that allows you to edit, compile, and deploy your smart contract. This will prevent you from needing to download any other coding environments at this stage.

Once you've imported your contract, the first thing you need to do is compile it. Hit the `Compile` button on the left-hand side. You could also use the keyboard shortcut `Ctrl / Command + S`.

![Remix Compile](/images/nft-collection8.png)

Once completed, you'll get a green checkmark on the far left tab and will see options to Publish on IPFS or Swarm. Those aren't important to our tutorial. Next, you'll click on the bottom tab on the left-hand side to move to the deployment page.

![Remix Deploy Page](/images/nft-collection9.png)

Now, we need to change the environment that Remix will try to use to deploy the smart contract. Click on the `Environment` drop-down, and select `Injected web3`.

![Remix Web3](/images/nft-collection10.png)

This should prompt you to connect with your Core account. Once connected, you can verify the correct connection by checking that the Account number matches your Core address.

![Remix account](/images/nft-collection11.png)

![Core account](/images/nft-collection12.png)

Now click on the `Contract` drop-down and select the contract you created and compiled. It should show up with the name you gave it in the Open Zeppelin Wizard.

![Remix Contract](/images/nft-collection13.png)

Now, click deploy. This will open Core and ask you to confirm the transaction. Click `Confirm`.

![Core Accept](/images/nft-collection14.png)

It may take a second, but once completed, your newly deployed contract will appear underneath the `Transactions Recorded` field.

![Remix Record](/images/nft-collection15.png)

Copy your contract's address and open the [Snowtrace Testnet Explorer](https://testnet.snowtrace.io/). Paste your contract address in the search bar, and click `Search`.

You'll now see [your contract information on Snowtrace](https://testnet.snowtrace.io/address/0xa03e85f4411e37cbaff635975bf38cb2737f0015). The first transaction you see should be the contract deployment you just did in the Remix IDE.

![Snowtrace](/images/nft-collection16.png)

## Minting an NFT

Now that you've deployed the contract, you can mint the NFT. Go back to the Remix IDE tab and click on your contract to expand its information. A list of functions will appear that you can interact with.

![Remix Functions](/images/nft-collection17.png)

The only function you're interested in is the `safeMint` function. Click the drop-down arrow for the function to expand the address field.

![](/images/nft-collection18.png)

Now, copy your Core address and paste it into this address field. This will send the NFT to your address when the mint function is called. After, hit `transact`.

This will reopen Core and ask you to verify the transaction. Click `Confirm` to mint your NFT.

Once the transaction has been confirmed, you'll see a green checkmark in the terminal at the bottom of the Remix IDE.

![Remix Confirm Mint](/images/nft-collection19.png)

Head back to the Snowtrace Testnet explorer page for your contract and refresh it. You should now see a second transaction, your call to `safeMint`.

![Snowtrace Mint](/images/nft-collection20.png)

By clicking on the [TX Hash](https://testnet.snowtrace.io/tx/0x8b698ac72bd20b2a640167c5d9bacdcbb3d86fd696eb8cde6f28347f6f99a2c9), you see that your NFT was created!

![Snowtrace Transaction](/images/nft-collection21.png)

## On Mainnet

All of the above steps can be used on Mainnet except the following changes:

- Make sure that you switch to the Avalanche C-Chain in Core.
- Make sure that you have AVAX tokens in your account to cover transaction costs.
- You should use the Mainnet version of [Snowtrace Explorer](https://snowtrace.io/) to view transactions.



# Deploy NFT Collection (/docs/dapps/deploy-nft-collection)

---
title: Deploy NFT Collection
description: Learn how to deploy an NFT collection on the Avalanche C-chain.
index: true
---


# Prepare NFT Files (/docs/dapps/deploy-nft-collection/prep-nft-files)

---
title: Prepare NFT Files
description: Learn how to prepare your NFT files.
---

The first step of setting up an NFT smart contract is having your NFT files ready to use. In this example, the files will get uploaded to [Pinata](https://www.pinata.cloud/), a pinning service that prevents files from being garbage collected on IPFS. If you don't already have an account, please create one.

Preparing the Images[​](#preparing-the-images "Direct link to heading")
-----------------------------------------------------------------------

This tutorial will create only 1 NFT, however, if you're interested in creating more, you're more than welcome to do so. The image I'm using is linked here if you'd like to use it.

![Original NFT Photo](/images/nft-files1.jpeg)

Place your image file in a folder on your computer. Name this image `0`, so it'll be the first image pulled from the smart contract. it'll be the first (and only) NFT in this collection, however, if you're adding more images you'd continue naming them in sequential numeric order. you'll upload this folder to Pinata once your images are organized and named correctly.

info

NOTE: Some projects start file names with `0`, and others with `1`. That choice will need to be consistent with the smart contract code. To be consistent with [this ERC-721 tutorial](/docs/dapps/deploy-nft-collection/deploy-erc-721), we'll name this file `0`.

![Image Folder](/images/nft-files2.png)

After you log into Pinata, you'll see your dashboard. you'll see the upload button on the left. Click `Upload`, and then `Folder`.

![Pinata Dashboard](/images/nft-files3.png)

![Folder Button](/images/nft-files4.png)

You'll then select the folder that the image is in. You may get a pop-up from your browser confirming you want to upload the folder and the files in it. If you do, confirm by clicking `Upload`.

![Confirm Upload](/images/nft-files5.png)

You'll then be prompted to name the folder you've uploaded. This is beneficial when you have several sets of folders uploaded to Pinata and are trying to keep them organized. After giving it a name, click `Upload` and wait for your file to upload. The quantity and size of the images could affect the upload time, but if you're starting small, it should only take a few seconds.

Once the upload is complete, you'll see your folder in your dashboard.

![Uploaded Image Folder](/images/nft-files6.png)

If you click on the folder name, it'll redirect you to the Pinata gateway to be able to view your newly uploaded files. If you have a paid Pinata account, it'll open the folder through your own gateway. Having a paid plan and personal gateway is NOT required for this tutorial but is recommended to have for larger collection sizes and hosting multiple folders.

If you right-click on the image, you can copy the image's url. This URL is important. Copy this down to use in the next step as we set up the metadata. For this example, my URL is `https://gateway.pinata.cloud/ipfs/QmPWbixyMsaNkR9v612bBFbncKGmgXDKz9CgMtDDD7Bymw/0.png`

Now that we have the image uploaded and its URL, we can create the matching metadata file for it.

Where this NFT is going to be an ERC-721, we know we can use metadata standards often found on Marketplaces such as [Joepegs.com](https://joepegs.com/). The .json file below is an example of what the [metadata](https://docs.opensea.io/docs/metadata-standards#metadata-structure) should look like.

```json
{
  "name": "",
  "tokenId": 0,
  "image": "",
  "description": "",
  "attributes": []
}
```

Now, we'll populate the values into the metadata file. You can choose any `name` and `description` that you want.

The `tokenId` here will be `0` so that it corresponds to the image we just uploaded. If uploading multiple files, this needs to be incremented in each file.

The `image` link is the URL we saved from the last step of the previous section. Paste that link here so the smart contract knows where to find the image file for your NFT. If uploading multiple files, the end of the URL (the specific image) needs to increment in each file.

The `attributes` field isn't quite as important here, but if you were uploading NFTs with several layers, the attributes would be the information of those specific layers. This is often used when calculating the rarity of NFTs to be able to rank them by how frequently their layers appear throughout the entire collection. it'll be erased in this tutorial.

Below is an example of how you'd fill out the fields in the metadata file.

```json
{
  "name": "Cool Photography",
  "tokenId": 0,
  "image": "https://gateway.pinata.cloud/ipfs/QmPWbixyMsaNkR9v612bBFbncKGmgXDKz9CgMtDDD7Bymw/0.png",
  "description": "A cool image"
}
```

When saving this file, you want it to share the same name as the image it corresponds to. In this case, it is 0.

Once the metadata file is uploaded to Pinata, the file extension will actually not be needed. it'll search for the file as a directory and be able to pull its information from there. To remove the file extension, follow these steps for a [Mac](https://support.apple.com/guide/mac-help/show-or-hide-filename-extensions-on-mac-mchlp2304/mac) environment, or these for a [Windows](https://www.techwalla.com/articles/how-to-remove-file-extensions) environment.

Now that the file extension has been removed, place it in another folder as you did with the image file. They need to be SEPARATE folders.

![Metadata Folder](/images/nft-files7.png)

You'll now repeat the folder upload process to add the metadata to Pinata. Follow the same steps as above. Once completed, you'll have both folders available on your dashboard.

![Uploaded Folders](/images/nft-files8.png)

Click on the metadata folder to be directed to the IPFS gateway and save the URL. This URL will be your base URL and won't need the direct file links. The smart contract will append the necessary file information for each NFT as needed. For example, my URL is `https://gateway.pinata.cloud/ipfs/QmYdWxbiwsfsYcW1CYQPgYujAc9FMLPG3fgFcxFskbSsFa`.

Now that the image and metadata files are ready, we can prepare to deploy a smart contract by following this [ERC-721 tutorial](/docs/dapps/deploy-nft-collection/deploy-erc-721).


# Fuji Workflow (/docs/dapps/end-to-end/fuji-workflow)

---
title: Fuji Workflow
description: Learn how to use the Fuji Testnet.
---

## Introduction

Fuji is the Avalanche network's test network. You can use it to test your dapp
or smart contract after you've developed it locally. Fuji is
typically on the same version as the Avalanche Mainnet, but sometimes it is
running an unreleased version of AvalancheGo.

In general, you can expect Fuji's behavior to be about the same as Avalanche Mainnet. Tools such as a explorers
and wallets should work with the Fuji Testnet.

In this tutorial, we'll go through an example Fuji workflow to show how it can
be used. We'll do the following:

1. Set up Fuji network on Core (optional)
2. Generate a 24 word english mnemonic via AvalancheJS
3. Derive external C-Chain addresses via AvalancheJS
4. Get AVAX from the Fuji faucet
5. Send AVAX via ethersJS
6. Examine the resulting transaction on the Avalanche Explorer
7. Use a private key derived from a mnemonic to sign into the Core extension (wallet)

## Set up Fuji Network on Core (optional)

To access the Fuji test network, Testnet Mode needs to be enabled.
In order to do that, go to **Settings** and click on **Advanced**.

![Settings image 1](/images/fuji1.png)

Here, turn on the **Testnet Mode** feature. This will automatically make Core switch to
Fuji Testnet.

![Settings image 2](/images/fuji2.png)

<Callout title="Note">
If you are using other wallets, like MetaMask, you can add the Fuji Testnet
using the following details:

- **Network Name**: Avalanche C-Chain
- **New RPC URL**: `https://api.avax-test.network/ext/bc/C/rpc`
- **ChainID**: `43113`
- **Symbol**: AVAX
- **Explorer**: [`https://testnet.snowtrace.io`](https://testnet.snowtrace.io/)
</Callout>

## Generate a Mnemonic

To begin, we'll create a mnemonic phrase with
[AvalancheJS](/docs/tooling/avalanche-js). Mnemonics enable us to encode
strong security into a human-readable phrase. AvalancheJS supports 10 languages
including English, Japanese, Spanish, Italian, French, Korean, Czech,
Portuguese, Chinese Simplified and Chinese Traditional.

First, generate a 24 word english
[BIP39](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki)-compliant
mnemonic via AvalancheJS.

```ts
import { Mnemonic } from "avalanche";
const mnemonic: Mnemonic = Mnemonic.getInstance();
const strength: number = 256;
const wordlist = mnemonic.getWordlists("english") as string[];
const m: string = mnemonic.generateMnemonic(strength, randomBytes, wordlist);
console.log(m);
// "chimney asset heavy ecology accuse window gold weekend annual oil emerge alley retreat rabbit seed advance define off amused board quick wealth peasant disorder"
```

## Derive Addresses

After generating a mnemonic we can use AvalancheJS to derive
[BIP32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki)-compliant
hierarchical deterministic (HD) Keypairs.

```ts
import HDNode from "avalanche/dist/utils/hdnode";
import { Avalanche, Mnemonic, Buffer } from "avalanche";
import { EVMAPI, KeyChain } from "avalanche/dist/apis/evm";
import { ethers } from "ethers";

const ip: string = "api.avax-test.network";
const port: number = 443;
const protocol: string = "https";
const networkID: number = 5;
const avalanche: Avalanche = new Avalanche(ip, port, protocol, networkID);
const cchain: EVMAPI = avalanche.CChain();

const mnemonic: Mnemonic = Mnemonic.getInstance();
const m: string = "chimney asset heavy ecology accuse window gold weekend annual oil emerge alley retreat rabbit seed advance define off amused board quick wealth peasant disorder";
const seed: Buffer = mnemonic.mnemonicToSeedSync(m);
const hdnode: HDNode = new HDNode(seed);

const keyChain: KeyChain = cchain.newKeyChain();

const cAddresses: string[] = [];

for (let i: number = 0; i <= 2; i++) {
  const child: HDNode = hdnode.derive(`m/44'/60'/0'/0/${i}`);
  keyChain.importKey(child.privateKey);
  const cchainAddress = ethers.utils.computeAddress(child.privateKey);
  cAddresses.push(cchainAddress);
}
console.log(cAddresses);
// [
//   '0x2d1d87fF3Ea2ba6E0576bCA4310fC057972F2559',
//   '0x25d83F090D842c1b4645c1EFA46B15093d4CaC7C',
//   '0xa14dFb7d8593c44a47A07298eCEA774557036ff3'
// ]
```

### Generate Private Keys from a Mnemonic

As long as you have the mnemonic phrase, you can re-generate your private keys
and the addresses they control.

For example, if you want to generate the private keys for the first 3 address in the C Chain keychain:

- [0x2d1d87fF3Ea2ba6E0576bCA4310fC057972F2559](https://testnet.snowtrace.io/address/0x2d1d87fF3Ea2ba6E0576bCA4310fC057972F2559)
- [0x25d83F090D842c1b4645c1EFA46B15093d4CaC7C](https://testnet.snowtrace.io/address/0x25d83F090D842c1b4645c1EFA46B15093d4CaC7C)
- [0xa14dFb7d8593c44a47A07298eCEA774557036ff3](https://testnet.snowtrace.io/address/0xa14dFb7d8593c44a47A07298eCEA774557036ff3)

you might update the example script above to the following:

```ts
const cAddresses: string[] = [];
const privateKeys: string[] = [];
for (let i: number = 0; i <= 2; i++) {
  // Deriving the _i_th external BIP44 C-Chain address
  const child: HDNode = hdnode.derive(`m/44'/60'/0'/0/${i}`);
  keyChain.importKey(child.privateKey);
  // Converting the BIP44 addresses to hexadecimal addresses
  const cchainAddress = ethers.utils.computeAddress(child.privateKey);
  privateKeys.push(child.privateKey.toString("hex"));
  cAddresses.push(cchainAddress);
}
console.log({ cAddresses, privateKeys });
// {
//   cAddresses: [
//     '0x2d1d87fF3Ea2ba6E0576bCA4310fC057972F2559',
//     '0x25d83F090D842c1b4645c1EFA46B15093d4CaC7C',
//     '0xa14dFb7d8593c44a47A07298eCEA774557036ff3'
//   ],
//   privateKeys: [
//     'cd30aef1af167238c627593537e162ecf5aad1d4ab4ea98ed2f96ad4e47006dc',
//     'b85479b26bc8fbada4737e90ab2133204f2fa2a9ea33c1e0de4452cbf8fa3be4',
//     'c72e18ea0f9aa5457396e3bf810e9de8df0177c8e4e5bf83a85f871512d645a9'
//   ]
// }
```

## Get a Drip from the Fuji Faucet

**Option 1 (Recommended):** Create a [Builder Hub account](https://build.avax.network/login) and connect your wallet to receive testnet AVAX automatically.

**Option 2:** Use the external faucet at [core.app/tools/testnet-faucet](https://core.app/tools/testnet-faucet/). If you already have an AVAX balance greater than zero on Mainnet, paste your C-Chain address there, and request test tokens. Otherwise, please request a faucet coupon on [Guild](https://guild.xyz/avalanche).

Admins and mods on the official [Discord](https://discord.com/invite/RwXY7P6)
can provide testnet AVAX if developers are unable to obtain it from the other two options.
These AVAX are for the Fuji Testnet and have no monetary value.

![Requesting AVAX](/images/fuji3.png)

The faucet will send some AVAX to the address and return a transaction ID
(txID). This txID can be used with the Fuji Testnet Explorer to learn more about
the transaction.

![Receiving AVAX](/images/fuji4.png)

### Check the Transaction Details

The txID, `0x1419b04559bf140ab82216f7696110936fb7d4bc1f147e3b85fef7ca1008a19e`,
can be seen on the [Fuji Testnet
Explorer](https://subnets-test.avax.network/c-chain/tx/0x86eef1a01b0a5fd45f2a71c217f99d63d427230a271d3319004f17fc26d7fb26).
Avalanche also has a [Mainnet Explorer](https://explorer.avax.network).

![Transaction details](/images/fuji5.png)

### Get the Balance

We can also use the Fuji Explorer to get the balance for the 1st address—[0x2d1d87fF3Ea2ba6E0576bCA4310fC057972F2559](https://explorer.avax-test.network/address/0x2d1d87fF3Ea2ba6E0576bCA4310fC057972F2559).

![1st derived address balance](/images/fuji6.png)

Alternatively, we can use [ethersJS](https://docs.ethers.io/v5/) to get the balance.

```ts
const ethers = require("ethers");
const network = "https://api.avax-test.network/ext/bc/C/rpc";
const provider = ethers.getDefaultProvider(network);
const address = "0x2d1d87fF3Ea2ba6E0576bCA4310fC057972F2559";

const main = async (): Promise<any> => {
  provider.getBalance(address).then((balance) => {
    // convert a currency unit from wei to ether
    const balanceInAvax = ethers.utils.formatEther(balance);
    console.log(`balance: ${balanceInAvax} AVAX`);
    // balance: 2 AVAX
  });
};

main();
```

## Sending AVAX

The faucet sent 2 AVAX to the first address we generated. Let's send AVAX from
the 1st address to the 2nd address.

```ts
// import ethers.js
import { ethers } from "ethers";
// network: using the Fuji testnet
const network = "https://api.avax-test.network/ext/bc/C/rpc";
// provider: establish and RPC connection to the network
const provider = new ethers.providers.JsonRpcProvider(network);

// Sender private key:
// corresponding address 0x0x2d1d87fF3Ea2ba6E0576bCA4310fC057972F2559
let privateKey =
  "cd30aef1af167238c627593537e162ecf5aad1d4ab4ea98ed2f96ad4e47006dc";
// Create a wallet instance
let wallet = new ethers.Wallet(privateKey, provider);
// Receiver Address
let receiverAddress = "0x25d83F090D842c1b4645c1EFA46B15093d4CaC7C";
// AVAX amount to send
let amountInAvax = "0.01";
// Create a transaction object
let tx = {
  to: receiverAddress,
  // Convert currency unit from ether to wei
  value: ethers.utils.parseEther(amountInAvax),
};
// Send a transaction
wallet.sendTransaction(tx).then((txObj) => {
  console.log(`"tx, https://testnet.snowtrace.io/tx/${txObj.hash}`);
  // A transaction result can be checked in a snowtrace with a transaction link which can be obtained here.
});
```

### Verify Success

We can verify that the transaction,
`0x3a5f4198b3be8d24b272f8255912aae4dcf2fb1f97f70d1787434de7b3097aac`, was
successful using the Fuji Testnet Explorer. The transaction can be seen
[here](https://testnet.snowtrace.io/tx/0x3a5f4198b3be8d24b272f8255912aae4dcf2fb1f97f70d1787434de7b3097aac).

![Transaction details](/images/fuji7.png)

#### Get the Balance

We can also use the Fuji Explorer to get the balance for the 2nd address—[0x25d83F090D842c1b4645c1EFA46B15093d4CaC7C](https://testnet.snowtrace.io/address/0x25d83F090D842c1b4645c1EFA46B15093d4CaC7C).

Alternatively, we can use ethersJS to get the balance.

```ts
const ethers = require("ethers");
const network = "https://api.avax-test.network/ext/bc/C/rpc";
const provider = ethers.getDefaultProvider(network);
const address = "0x25d83F090D842c1b4645c1EFA46B15093d4CaC7C";

const main = async (): Promise<any> => {
  provider.getBalance(address).then((balance) => {
    // convert a currency unit from wei to ether
    const balanceInAvax = ethers.utils.formatEther(balance);
    console.log(`balance: ${balanceInAvax} AVAX`);
    // balance: 0.02 AVAX
  });
};

main();
```

### Sign in to Core Extension

Lastly, we can [use the mnemonic to generate a private
key](#generate-private-keys-from-a-mnemonic) to access that account in
[Core extension](https://core.app/en/). 
We'll see that it has the AVAX balance and
that it derives the hexadecimal address from the private key.

Use the private key to access the account in Core Extension.

![Access the wallet](/images/fuji8.png)

The balance is correct and the address is the 1st derived address.

![Core extension balance](/images/fuji9.png) ![3rd derived BIP44 address](/images/fuji10.png)

We can repeat this login process using the private keys from the remaining 2
addresses in the [script above](#generate-private-keys-from-a-mnemonic).

![Wallet derived addresses](/images/fuji11.png)
![Wallet derived addresses2](/images/fuji12.png)  
![Wallet derived addresses3](/images/fuji13.png)

## Summary

The Fuji Testnet plays a critical role in testing dapps, smart
contracts and financial products before deploying to the Mainnet. Tooling like
AvalancheJS, the public API, faucet, and explorer helps to ensure that your
testing and QA environment is close to Mainnet so that you can be confident when
you launch on Mainnet.

## Resources

For additional and valuable resources please see below.

### Faucet

You can get testnet AVAX in two ways:
- **Recommended:** Create a [Builder Hub account](https://build.avax.network/login) and connect your wallet to receive testnet AVAX automatically
- **Alternative:** Use the [Fuji Faucet](https://core.app/tools/testnet-faucet/) which sends AVAX to X-Chain or C-Chain addresses. (This testnet AVAX has no value.)

### Wallet

[Core extension](https://core.app/en/) and
[Core mobile](https://support.avax.network/en/articles/6066926-core-mobile-how-do-i-create-a-new-wallet)
are simple, secure, non-custodial wallets for storing Avalanche assets. 
They support Mainnet, Fuji and custom networks.

### Explorer

The Avalanche Explorer allows you to explore the network on
[Mainnet](https://explorer.avax.network) and
[Fuji](https://explorer.avax-test.network).

### RPC Endpoints - Public API Server

See [here.](/docs/tooling/rpc-providers)


# Ethereum dApp → Avalanche (/docs/dapps/end-to-end/launch-ethereum-dapp)

---
title: Ethereum dApp → Avalanche
description: Learn how to port a decentralized application from Ethereum to Avalanche.
---

## Overview

The purpose of this document is to help you with launching your existing dapp on
Avalanche. It contains a series of resources designed to help you get the basics
of Avalanche Platform and how it works, show how to connect to the network, how
to use your existing tools and environments in developing and deploying on
Avalanche, as well as some common pitfalls you need to consider when running
your dapp on Avalanche.

## Accessing Avalanche C-Chain

C-Chain exposes the [same API](/docs/api-reference/c-chain/api) as
`go-ethereum`, so you can use all the familiar APIs that are available on Ethereum
for interaction with the platform.

There are multiple ways of working with the C-Chain.

### Through Core

Powered by Avalanche,
[Core](https://core.app/en/)
is an all-in-one operating system bringing together Avalanche apps, Avalanche L1s,
bridges, and NFTs in one seamless, high-performance browser experience. Putting
in another way, Core is more than a wallet. It is a curated web3 operating
system combining Wallet, Explorer, Bridge, Avalanche L1s, dApps, and more.

In your application's web interface, follow [this to add Avalanche programmatically](/docs/dapps/advanced-tutorials/add-network-programmatically#core).

### Through MetaMask

You can access C-Chain through MetaMask, by defining a custom network. Go to
MetaMask, log in, click the network dropdown, and select 'Custom RPC'. Data for
Avalanche is as follows.

#### **Avalanche Mainnet Settings:**

- **Network Name**: Avalanche Mainnet C-Chain
- **New RPC URL**: `https://api.avax.network/ext/bc/C/rpc`
- **ChainID**: `43114`
- **Symbol**: `AVAX`
- **Explorer**: [https://snowtrace.io/](https://snowtrace.io/)

#### **Fuji Testnet Settings:**

- **Network Name**: Avalanche Fuji C-Chain
- **New RPC URL**: `https://api.avax-test.network/ext/bc/C/rpc`
- **ChainID**: `43113`
- **Symbol**: `AVAX`
- **Explorer**: [https://testnet.snowtrace.io/](https://testnet.snowtrace.io/)

In your application's web interface, you can
[add Avalanche programmatically](/docs/dapps/advanced-tutorials/add-network-programmatically#metamask)
so your users don't have to enter the network data manually.

### Using the Public API Nodes or RPC Endpoints

Instead of proxying network operations through MetaMask, you can use the public
API, which consists of a number of AvalancheGo nodes behind a load balancer.

The C-Chain API endpoint is
`https://api.avax.network/ext/bc/C/rpc`
for the Mainnet and
`https://api.avax-test.network/ext/bc/C/rpc`
for the testnet.

For more information, see [documentation](/docs/tooling/rpc-providers).

However, public API does not expose all the APIs that are available on the node,
as some of them would not make sense on a publicly accessible service, and some
would present a security risk. If you need to use an API that is not available
publicly, you can run your own node.

## Running Your Own Node

If you don't want your dapp to depend on a centralized service you don't
control, or have specific needs that cannot be met through the public API, you
can run your own node and access the network that way. Running your own node
also avoids potential issues with public API congestion and rate-limiting.

For development and experimental purposes,
[here](/docs/nodes/run-a-node/from-source) is a tutorial that shows
how to download, build, and install AvalancheGo. Simpler solution is to use the
prebuilt binary, available on
[GitHub](https://github.com/ava-labs/avalanchego/releases).

If you're going to run a node on a Linux machine, you can use the
[installer script](/docs/nodes/using-install-script/installing-avalanche-go) to install the node as a
`systemd` service. Script also handles node upgrading.

If you want to run a node in a docker container, there are [build
scripts](https://github.com/ava-labs/avalanchego/tree/master/scripts) in the
AvalancheGo repo for various Docker configs.

### Node Configuration

Node configuration options are explained
[here](/docs/nodes/configure/configs-flags). But unless you have
specific needs, you can mostly leave the main node config options at their
default values.

On the other hand, you will most likely need to adjust C-Chain configuration to
suit your intended use. You can look up complete configuration options for
C-Chain [here](/docs/nodes/chain-configs/c-chain) as well
as the default configuration. Note that only the options that are different from
their default values need to be included in the config file.

By default, the C-Chain config file is located at
`$HOME/.avalanchego/configs/chains/C/config.json`. We will go over how to adjust
the config to cover some common use cases in the following sections.

#### Running an Archival Node

If you need Ethereum's [Archive
Node](https://ethereum.org/en/developers/docs/nodes-and-clients/#archive-node)
functionality, you need to disable C-Chain pruning, which is enabled by default
to conserve disk space. To preserve full historical state, include
`"pruning-enabled": false` in the C-Chain config file.

<Callout title="Note">
After changing the flag to disable the database pruning, you will need to run
the bootstrap process again, as the node will not backfill any already pruned
and missing data.

To re-bootstrap the node, stop it, delete the database (by default stored in
`~/.avalanchego/db/`) and start the node again.
</Callout>

#### Running a Node in Debug Mode

By default, debug APIs are disabled. To enable them, you need to enable the
appropriate EVM APIs in the config file by including the `eth-apis` value in
your C-Chain config file to include the `debug`, `debug-tracer`, and
`internal-debug` APIs.

<Callout title="Note">
Including the `eth-apis` in the config flag overrides the defaults, so you need
to include the default APIs as well!
</Callout>

#### Example C-Chain Config File

An example C-Chain config file that includes the archival mode, enables debug
APIs as well as default EVM APIs:

```json
{
  "eth-apis": [
    "eth",
    "eth-filter",
    "net",
    "web3",
    "internal-eth",
    "internal-blockchain",
    "internal-transaction",
    "debug-tracer"
  ],
  "pruning-enabled": false
}
```

Default config values for the C-Chain can be seen [here](/docs/nodes/chain-configs/c-chain).

### Running a Local Test Network

If you need a private test network to test your dapp, [Avalanche Network
Runner](https://github.com/ava-labs/avalanche-network-runner) is a shell client
for launching local Avalanche networks, similar to Ganache on Ethereum.

For more information, see [documentation](/docs/tooling/avalanche-network-runner/introduction).

## Developing and Deploying Contracts

Being an Ethereum-compatible blockchain, all of the usual Ethereum developer
tools and environments can be used to develop and deploy dapps for Avalanche's
C-Chain.

### Remix

There is a
[tutorial](/docs/dapps/smart-contract-dev/deploy-with-remix-ide)
for using Remix to deploy smart contracts on Avalanche. It relies on Core
for access to the Avalanche network.

### thirdweb

You can also use thirdweb to test and deploy smart contracts on Avalanche. Find out how in this [tutorial](/docs/dapps/toolchains/thirdweb).

### Hardhat

Hardhat is the newest development and testing environment for Solidity smart
contracts, and the one our developers use the most. Due to its superb testing
support, it is the recommended way of developing for Avalanche.

For more information see [this doc](/docs/dapps/toolchains/hardhat).

## Avalanche Explorer

An essential part of the smart contract development environment is the explorer,
which indexes and serves blockchain data. Mainnet C-Chain explorer is available
at [https://snowtrace.io/](https://snowtrace.io/) and testnet explorer at
[https://testnet.snowtrace.io/](https://testnet.snowtrace.io/). Besides the web
interface, it also exposes the standard [Ethereum JSON RPC
API](https://eth.wiki/json-rpc/API).

## Avalanche Faucet

For development purposes, you will need test tokens. Avalanche has a
[Faucet](https://core.app/tools/testnet-faucet/) that drips test tokens to the address of
your choice. If you already have an AVAX balance greater than zero on Mainnet,
paste your C-Chain address there, and request test tokens. Otherwise,
please request a faucet coupon on
[Guild](https://guild.xyz/avalanche). Admins and mods on the official [Discord](https://discord.com/invite/RwXY7P6)
can provide testnet AVAX if developers are unable to obtain it from the other two options.

If you need, you can also run a faucet locally, but building it from the [repository](https://github.com/ava-labs/avalanche-faucet).

## Contract Verification

Smart contract verification provides transparency for users interacting with
smart contracts by publishing the source code, allowing everyone to attest that
it really does what it claims to do. You can verify your smart contracts using
the [C-Chain explorer](https://snowtrace.io/). The procedure is simple:

- navigate to your published contract address on the explorer
- on the `code` tab select `verify & publish`
- copy and paste the flattened source code and enter all the build parameters exactly as they are on the published contract
- click `verify & publish`

If successful, the `code` tab will now have a green checkmark, and your users
will be able to verify the contents of your contract. This is a strong positive
signal that your users can trust your contracts, and it is strongly recommended
for all production contracts.

See
[this](/docs/dapps/verify-contract/hardhat)
for a detailed tutorial with Hardhat.

## Contract Security Checks

Due to the nature of distributed apps, it is very hard to fix bugs once the
application is deployed. Because of that, making sure your app is running
correctly and securely before deployment is of great importance. Contract
security reviews are done by specialized companies and services. They can be
very expensive, which might be out of reach for single developers and startups.
But, there are also automated services and programs that are free to use.

Most popular are:

- [Slither](https://github.com/crytic/slither), here's a [tutorial](https://blog.trailofbits.com/2018/10/19/slither-a-solidity-static-analysis-framework/)
- [MythX](https://mythx.io/)
- [Mythril](https://github.com/ConsenSys/mythril)

We highly recommend using at least one of them if professional contract security
review is not possible. A more comprehensive look into secure development
practices can be found
[here](https://github.com/crytic/building-secure-contracts/blob/master/development-guidelines/workflow.md).

## Gotchas and Things to Look out For

Avalanche Platform's C-Chain is EVM-compatible, but it is not identical. There
are some differences you need to be aware of, otherwise, you may create subtle
bugs or inconsistencies in how your dapps behave.

Here are the main differences you should be aware of.

### Measuring Time

Avalanche does not use the same mechanism to measure time as Ethereum which uses
consistent block times. Instead, Avalanche supports asynchronous block issuance,
block production targets a rate of every 2 seconds. If there is sufficient
demand, a block can be produced earlier. If there is no demand, a block will not
be produced until there are transactions for the network to process.

Because of that, you should not measure the passage of time by the number of
blocks that are produced. The results will not be accurate, and your contract
may be manipulated by third parties.

Instead of block rate, you should measure time simply by reading the timestamp
attribute of the produced blocks. Timestamps are guaranteed to be monotonically
increasing and to be within 30 seconds of the real time.

### Finality

On Ethereum, the blockchain can be reorganized and blocks can be orphaned, so
you cannot rely on the fact that a block has been accepted until it is several
blocks further from the tip (usually, it is presumed that blocks 6 places deep
are safe). That is not the case on Avalanche. Blocks are either accepted or
rejected within a second or two. And once the block has been accepted, it is
final, and cannot be replaced, dropped, or modified. So the concept of 'number
of confirmations' on Avalanche is not used. As soon as a block is accepted and
available in the explorer, it is final.

### Using `eth_newFilter` and Related Calls with the Public API

If you're using the
[`eth_newFilter`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_newfilter) API method on the
public API server, it may not behave as you expect because the public API is
actually several nodes behind a load balancer. If you make an `eth_newFilter`
call, subsequent calls to
[`eth_getFilterChanges`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getfilterchanges) may
not end up on the same node as the first call, and you will end up with
undefined results.

If you need the log filtering functionality, you should use a websocket
connection, which ensures that your client is always talking to the same node
behind the load balancer. Alternatively, you can use
[`eth_getLogs`](https://ethereum.org/en/developers/docs/apis/json-rpc/#eth_getlogs), or run your own node
and make API calls to it.

## Support

Using this tutorial you should be able to quickly get up to speed on Avalanche,
deploy, and test your dapps. If you have questions, problems, or just want to
chat with us, you can reach us on our public
[Discord](https://chat.avalabs.org/) server. We'd love to hear from you and find
out what you're building on Avalanche!



# Deploy with Remix IDE (/docs/dapps/smart-contract-dev/deploy-with-remix-ide)

---
title: Deploy with Remix IDE
description: Learn how to deploy smart contracts on Avalanche using Remix and Core Wallet.
---

Avalanche's Primary Network is an Avalanche L1 that has three chains: P-Chain, X-Chain, and C-Chain. The C-Chain is an instance of the Ethereum Virtual Machine powered by Avalanche's Snowman consensus protocol. The [C-Chain RPC](/docs/api-reference/c-chain/api) can do anything a typical Ethereum client can by using the Ethereum-standard RPC calls.

The immediate benefits of using the C-Chain rather than Ethereum are all of the benefits of using Avalanche. These properties that could considerably improve the performance of Dapps and the user experience.

Today, we will deploy and test a smart contract on Avalanche using Remix and Core Wallet.

## Setting up Core

If you don't already have a Core wallet, follow this [guide](https://support.avax.network/en/articles/6100129-core-extension-how-do-i-create-a-new-wallet) to create a new wallet.

If you want to use the **Avalanche C-Chain**, it can be selected from the networks list.

To switch to the **Fuji test network**, go to **Settings**, select **Advanced**, and then toggle Testnet Mode to **ON**.

![](/images/remix1.png)

### Local Testnet Settings

- **Network Name**: Avalanche Local C-Chain
- **New RPC URL**: http://127.0.0.1:34890/ext/bc/C/rpc (Note: the port number should match your local setting which can be different from 34890.)
- **ChainID**: `43112`
- **Symbol**: `AVAX`
- **Explorer**: N/A

## Funding Your C-Chain Address

### Using Core Web

On the Mainnet, you can use [Core web](https://core.app/) to transfer funds from the X-Chain to your C-Chain address. The process is simple, as explained in this [tutorial](https://support.avax.network/en/articles/8133713-core-web-how-do-i-make-cross-chain-transfers-in-core-stake). Please note that you will need [Core wallet](https://core.app/en/) connected to Core web for making cross-chain transfers. Core wallet can be used on test and local networks, too. This wallet is available for [mobile](https://support.avax.network/en/articles/6114992-what-is-the-core-extension) too.

### Using Testnet Faucet

**Option 1 (Recommended):** Create a [Builder Hub account](https://build.avax.network/login) and connect your wallet to receive testnet AVAX automatically.

**Option 2:** Use the [Avalanche Faucet](https://core.app/tools/testnet-faucet/). If you already have an AVAX balance greater than zero on Mainnet, paste your C-Chain address there, and request test tokens. Otherwise, please request a faucet coupon on [Guild](https://guild.xyz/avalanche). Admins and mods on the official [Discord](https://discord.com/invite/RwXY7P6) can provide testnet AVAX if developers are unable to obtain it from the other options.

### Funding on Local Testnet

On a local network, you can easily fund your addresses by following [this](/docs/tooling/create-deploy-avalanche-l1s/deploy-locally#importing-the-test-private-key) guide.

## Connect Core & Deploy Smart Contract Using Remix

Open [Remix](https://remix.ethereum.org/) &rarr; Select Solidity

![](/images/remix2.png)

Load or create the smart contracts that we want to compile and deploy using Remix file explorer.

For this example, we will deploy a simple Hello World contract from [here](https://blog.chain.link/how-to-create-a-hello-world-smart-contract-with-solidity/).

![](/images/remix3.png)

Select the Solidity compiler tab and compile the contract.

![](/images/remix4.png)

Navigate to Deploy & Run transactions Tab -> Open the "ENVIRONMENT" drop-down and select Injected Provider (make sure Core is loaded).

![](/images/remix5.png)

A pop up will ask which wallet to use. Select Core.

![](/images/remix6.png)

Now, the smart contract is compiled, Core is injected, and we are ready to deploy our Hello world contract. Click "Deploy."

![](/images/remix7.png)

Confirm the transaction on the Core pop up.

![](/images/remix8.png)

Our contract is successfully deployed!

![](/images/remix9.png)

Now, we can expand it by selecting it from the "Deployed Contracts" tab and test it out.

![](/images/remix10.png)

The contract ABI and Bytecode are available on the Solidity compiler tab.

![](/images/remix11.png)

If you had any difficulties following this tutorial or simply want to discuss Avalanche with us, you can join our community at [Discord](https://chat.avalabs.org/)!


# Create an ERC-20 Token (/docs/dapps/smart-contract-dev/erc-20-token)

---
title: Create an ERC-20 Token
description: Create an ERC-20 Token
---

[ERC-20 tokens](https://ethereum.org/en/developers/docs/standards/tokens/erc-20/) are the most fundamental and essential concept in Ethereum. As the Avalanche community and the ecosystem are growing, new use cases and projects that are running on Ethereum or different chains would be implemented to Avalanche.

Therefore, we will be creating our own mintable ERC-20 token and will mint it to any address we want. The token will be generated on Avalanche C-Chain and will be accessible on that chain. We are using Fuji Testnet in this tutorial.

The article focuses on deploying a smart contract written with Solidity to Avalanche. This is the feature that Avalanche provides us - to be able to deploy any smart contract to the chain and no requirement for a new language specific contract concept to interact. Let's look at how to create an ERC-20 contract and deploy it to avalanche C-Chain.

## Setup Core Wallet

The first thing we should do is to enable Testnet mode on Core. To do that, go to **Settings** and click on **Advanced**.

![Settings image 1](/images/erc1.png)

Here, turn on the **Testnet Mode** feature. This will automatically make Core switch to Fuji Testnet.

![Settings image 2](/images/erc2.png)

<Callout title="Note">
If you are using other wallets, like MetaMask, you can add the Fuji Testnet using the following specs:

- **Network Name**: Avalanche C-Chain
- **New RPC URL**: https://api.avax-test.network/ext/bc/C/rpc
- **ChainID**: `43113`
- **Symbol**: AVAX
- **Explorer**: https://testnet.snowtrace.io
</Callout>

The setup is done. For now, we have 0 AVAX.

## Fund Your C-Chain Address

**Option 1 (Recommended):** Create a [Builder Hub account](https://build.avax.network/login) and connect your wallet to receive testnet AVAX automatically.

**Option 2:** Use the [Avalanche Faucet](https://core.app/tools/testnet-faucet/). If you already have an AVAX balance greater than zero on Mainnet, paste your C-Chain address there, and request test tokens. Otherwise, please request a faucet coupon on [Guild](https://guild.xyz/avalanche). Admins and mods on the official [Discord](https://discord.com/invite/RwXY7P6) can provide testnet AVAX if developers are unable to obtain it from the other options.

## Create Mintable Token

Now, we can create our mintable token on Remix. Open Remix on your browser or go to [this link](https://remix.ethereum.org/#optimize=false&evmVersion=null&version=soljson-v0.8.29+commit.ab55807c.js).

![Image for post](/images/erc3.png)

You should view this page. On this page, first, click the "Create new file" button. When you click the New File button, you have to choose a name.

Since we will use an ERC-20 contract from [OpenZeppelin](https://openzeppelin.com/contracts/), just paste this line to the file and save.

```solidity
import "https://github.com/OpenZeppelin/openzeppelin-contracts/blob/release-v4.9/contracts/token/ERC20/presets/ERC20PresetMinterPauser.sol";
```

![Image for post](/images/erc4.png)

After saving the file, we will see a bunch of files that are imported to remix. This is a remix feature that allows us to import a GitHub contract repository to remix by just giving the URL-link with an import statement.

![Image for post](/images/erc5.png)

We have ERC20PresetMinterPauser.sol file in the presets. This file is written by OpenZeppelin according to ERC20 standards with minter functionality. After deploying this file, we will be the owner of the contract and thus have the authority and ability to mint the tokens.

![Image for post](/images/erc6.png)

## Deploy the Contract

Open the tab with label `Solidity compiler` and select the solidity version that matches with the solidity version written in file as `pragma solidity …..`. The version should be equal to or higher than the file's version. For example, in my file, `pragma solidity ^0.8.0` is written so the required version is 0.8.0 or higher. As shown, in the compiler the solidity version is 0.8.29, which is OK. After checking the solidity version click the compile button. If you did not change anything in the file, or the solidity version is not wrong, the contract should compile without any errors.

![Image for post](/images/erc7.png)

Then, let's jump to the tab with label `Deploy & run transactions`. Here before deploying our contract, we should change the environment. Click to the environment and select "Injected Web3." If a pop-up shows up and asks you to connect the account, click to connect. After, you should see the account address in the "ACCOUNT" text box.

The last thing before the deployment process is to set the contract that will be deployed as a token. Above the Deploy Button, there is a drop-down menu to select a contract. Select the contract named `ERC20PresetMinterPauser.sol`.

![Image for post](/images/erc8.png)

Now, here enter the name and symbol of your token. I will name it "test" and the symbol will be `tst`. You can give it a and click to transact button.

![Image for post](/images/erc9.png)

After clicking the button, a pop-up will show up and just confirm it.

![Core confirmation](/images/erc10.png)

And then another pop-up, a Core confirmation, appears. Confirm it.

After confirming all these pop-ups we have deployed our token to avalanche C-Chain. So we can start to interact with it.

## Interact with Token

We can see our transaction that deployed on avalanche C-Chain via this [c-chain explorer](https://testnet.snowtrace.io/).

But firstly, let's see our transaction hash from the remix console.

![Image for post](/images/erc11.png)

After deploying the contract, we should see a log in remix console. When you click to arrow and expand it, a transaction hash will come up. Copy it.

![Image for post](/images/erc12.png)

Just paste the transaction hash to the [explorer](https://testnet.snowtrace.io/) I shared above and press enter.

![Image for post](/images/erc13.png)

Here we can see all details about the transaction and token contract.

![Image for post](/images/erc14.png)

The first one is my wallet address that creates token and the second address is my token contract address which is named `test`. Now, let's mint some token to our own address.

![Image for post](/images/erc15.png)

Come back to the remix and after deploying, you should be able to see the contract in "Deployed Contracts" section.

Here, we have a bunch of functions that we can use to interact with our token contract. You can check all these methods from OpenZeppelin documentation to learn how to use them. But we will only use the mint method.

Click to arrow beside the mint method to read it.

![Image for post](/images/erc16.png)

Enter your address and an amount in wei. For example, I will mint 1000 `tst` token so, I entered "1000000000000000000000"

## Add Token to Core Wallet

Now we minted 1000 token to our contract, but you should not be able to see the tokens in your Core wallet. In order to see our own token, we have to add it. On Core, click on the Avalanche C-Chain, and then select Manage:

![Add token 1](/images/erc17.png)

![Add token 2](/images/erc18.png)

Click on Add custom token. Here,enter the token address that you can see from the explorer, as showed above. Copy and paste it here. Then click on the Add token button, you should see 1000 token that you named in your Core wallet. Also, you can send it to another account via either remix or Core.

![Add token 3](/images/erc19.png)


# Get Test Funds (/docs/dapps/smart-contract-dev/get-test-funds)

---
title: Get Test Funds
description: Learn how to get test funds for Avalanche from Faucet.
---

## Automated Testnet Tokens (Recommended)

The easiest way to get testnet AVAX is through [Builder Hub](https://build.avax.network/):

1. **[Create a Builder Hub account](https://build.avax.network/login)** (free)
2. **Connect your Core wallet** to Builder Hub
3. **Tokens are automatically sent** to your wallet on C-Chain, P-Chain, and supported L1s

No coupon codes, no manual claims - just connect and go! This automated drip system ensures you always have enough testnet tokens for development.

## Alternative: External Faucet

If you prefer not to create a Builder Hub account, you can use the [Fuji Testnet Faucet](https://core.app/tools/testnet-faucet/). (This testnet AVAX has no value.)

Paste your address into the [Fuji faucet website](https://core.app/tools/testnet-faucet/):

![Requesting AVAX](/images/test-fund1.png)

If you already have an AVAX balance greater than zero on Mainnet, paste your C-Chain address there, and request test tokens. The faucet will send some AVAX to the address and return a transaction ID (txID).

![Requesting AVAX](/images/test-fund2.png)

Otherwise, please request a faucet coupon on [Guild](https://guild.xyz/avalanche). Admins and mods on the official [Discord](https://discord.com/invite/RwXY7P6) can provide testnet AVAX if developers are unable to obtain it from the other options.

![Requesting Coupon](/images/test-fund3.png)



# Interact from Golang App (/docs/dapps/smart-contract-dev/interact-golang-app)

---
title: Interact from Golang App
description: Interact with a smart contract from your Golang-based application.
---

`abigen` is a tool provided by the Go Ethereum (Geth) client that generates Go bindings for Solidity smart contracts. Developers would need to use Abigen when they want to interact with a smart contract written in Solidity from a Go programming language application. It enables developers to easily call functions and access data from Solidity contracts in a Go application. This tutorial demonstrates how to compile a solidity contract into Golang to deploy and call contracts programmatically.

## How to Build

Download the solidity compiler from [solc-bin](https://github.com/ethereum/solc-bin).

Copy the appropriate compiler into your current path. ~/bin/ is a common path in most Linux distributions.

```bash
cp linux-amd64/solc-linux-amd64-v0.8.9+commit.e5eed63a ~/bin
```

Ensure solc is properly installed by checking its version.

```bash
solc --version
```

Clone Coreth and Build Abigen.

```bash
git clone [email protected]:ava-labs/coreth.git
cd coreth/
go build -o abigen cmd/abigen/*.go
cp abigen ~/bin
```

Compile a contract.

```bash
abigen --sol counter.sol --pkg main --out counter.go
```

This will produce `counter.go` suitable to interact with contract.

## Example Code

Setup the connection to `avalanchego`, then deploy, call, and fetch values from the contract.

Abigen offers more features for complicated contracts, the following is provided as an example to get started using the basic contract

```solidity
package main

import (
	"context"
	"log"
	"math/big"
	"strings"
	"time"

	"github.com/ava-labs/avalanchego/utils/constants"
	"github.com/ava-labs/avalanchego/utils/formatting"
	"github.com/ava-labs/coreth/accounts/abi/bind"
	"github.com/ava-labs/coreth/core/types"
	"github.com/ava-labs/coreth/ethclient"
	"github.com/ava-labs/coreth/params"
	"github.com/ava-labs/coreth/rpc"
	"github.com/decred/dcrd/dcrec/secp256k1/v3"
	"github.com/ethereum/go-ethereum/common"
	"github.com/ethereum/go-ethereum/crypto"
)

func main() {
	// setup client
	rc, err := rpc.Dial("http://localhost:9650/ext/bc/C/rpc")
	if err != nil {
		log.Fatal(err)
	}
	ec := ethclient.NewClient(rc)

	ctx := context.Background()

	// fetch networkid
	networkId, err := ec.ChainID(ctx)
	if err != nil {
		log.Fatal(err)
	}

	// parse key
	privateKeyString := "PrivateKey-ewoqjP7PxY4yr3iLTpLisriqt94hdyDFNgchSxGGztUrTXtNN"
	privateKeyBytes, err := formatting.Decode(formatting.CB58, strings.TrimPrefix(privateKeyString, constants.SecretKeyPrefix))
	if err != nil {
		log.Fatal(err)
	}
	privateKey := secp256k1.PrivKeyFromBytes(privateKeyBytes)
	privateKeyECDSA := privateKey.ToECDSA()

	// derive 'c' address
	cAddress := crypto.PubkeyToAddress(privateKeyECDSA.PublicKey)

	// setup signer and transaction options.
	signer := types.LatestSignerForChainID(networkId)
	to := &bind.TransactOpts{
		Signer: func(address common.Address, transaction *types.Transaction) (*types.Transaction, error) {
			return types.SignTx(transaction, signer, privateKeyECDSA)
		},
		From:     cAddress,
		Context:  ctx,
		GasLimit: params.ApricotPhase1GasLimit,
	}

	// deploy the contract
	storageAddress, storageTransaction, storageContract, err := DeployStorage(to, ec)
	if err != nil {
		log.Fatal(err)
	}

	// wait for the transaction to be accepted
	for {
		r, err := ec.TransactionReceipt(ctx, storageTransaction.Hash())
		if err != nil {
			if err.Error() != "not found" {
				log.Fatal(err)
			}
			time.Sleep(1 * time.Second)
			continue
		}
		if r.Status != 0 {
			break
		}
		time.Sleep(1 * time.Second)
	}

	log.Println("storageAddress", storageAddress)
	log.Println("storageTransaction", storageTransaction)

	// Call store on the contract
	storeTransaction, err := storageContract.Store(to, big.NewInt(1), common.BytesToAddress([]byte("addr1")))
	if err != nil {
		log.Fatal(err)
	}

	// wait for the transaction
	for {
		r, err := ec.TransactionReceipt(ctx, storeTransaction.Hash())
		if err != nil {
			if err.Error() != "not found" {
				log.Fatal(err)
			}
			time.Sleep(1 * time.Second)
			continue
		}
		if r.Status != 0 {
			break
		}
		time.Sleep(1 * time.Second)
	}

	log.Println("storeTransaction", storeTransaction)

	// setup call options for storage
	co := &bind.CallOpts{
		Accepted: true,
		Context:  ctx,
		From:     storageAddress,
	}

	// retrieve the value of the contract
	storageValue, err := storageContract.Retrieve(co)
	if err != nil {
		log.Fatal(err)
	}

	log.Println("storageValue", storageValue)
}
```



# Foundry (/docs/dapps/toolchains/foundry)

---
title: Foundry
description: Deploy and interact with smart contracts using foundry on a local Avalanche Network and the Fuji C-Chain.
---

[Foundry toolchain](https://github.com/foundry-rs/foundry) is a smart contract development toolchain written in Rust. It manages your dependencies, compiles your project, runs tests, deploys, and lets you interact with the chain from the command-line.

## Recommended Knowledge

- Basic understanding of [Solidity](https://docs.soliditylang.org/) and Avalanche.
- You are familiar with [Avalanche Smart Contract Quickstart](https://github.com/ava-labs/avalanche-smart-contract-quickstart).
- Basic understanding of the [Avalanche's architecture](/docs/quick-start/primary-network)
- performed a cross-chain swap via this [this tutorial](https://support.avax.network/en/articles/8133713-core-web-how-do-i-make-cross-chain-transfers-in-core-stake) to get funds to your C-Chain address.

## Requirements

- You have [installed Foundry](https://github.com/foundry-rs/foundry#installation) and run `foundryup`. This installation includes the `forge` and `cast` binaries used in this walk-through.
- [NodeJS](https://nodejs.org/en) version `16.x`

### AvalancheGo and Avalanche Network Runner

[AvalancheGo](https://github.com/ava-labs/avalanchego) is an Avalanche node implementation written in Go.

[Avalanche Network Runner](/docs/tooling/avalanche-network-runner/introduction) is a tool to quickly deploy local test networks. Together, you can deploy local test networks and run tests on them.

Start a local five node Avalanche network:

```bash
cd /path/to/avalanche-network-runner
# start a five node staking network
./go run examples/local/fivenodenetwork/main.go
```

A five node Avalanche network is running on your machine. Network will run until you press `Ctrl + C` to exit.

## Getting Started

This section will walk you through creating an [ERC721](https://eips.ethereum.org/EIPS/eip-721).

### Clone Avalanche Smart Contract Quick Start

Clone the [quickstart repository](https://github.com/ava-labs/avalanche-smart-contract-quickstart) and install the necessary packages via `yarn`.

```bash
git clone https://github.com/ava-labs/avalanche-smart-contract-quickstart.git
cd avalanche-smart-contract-quickstart
yarn install
```

<Callout title="Note">
The repository cloning method used is HTTPS, but SSH can be used too:

`git clone git@github.com:ava-labs/avalanche-smart-contract-quickstart.git`

You can find more about SSH and how to use it [here](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/about-ssh).
</Callout>

In order to deploy contracts, you need to have some AVAX. 

**Getting testnet AVAX:**
- **Recommended:** Create a [Builder Hub account](https://build.avax.network/login) and connect your wallet to receive testnet AVAX automatically
- **Alternative:** Use the [Avalanche Faucet](https://core.app/tools/testnet-faucet/). If you already have an AVAX balance greater than zero on Mainnet, paste your C-Chain address there, and request test tokens. Otherwise, please request a faucet coupon on [Guild](https://guild.xyz/avalanche). Admins and mods on the official [Discord](https://discord.com/invite/RwXY7P6) can provide testnet AVAX if developers are unable to obtain it from the other options.

After getting comfortable with your code, you can run it on Mainnet after making the necessary changes to your workflow.

## Write Contracts

We will use our example ERC721 smart contract, [`NFT.sol`](https://github.com/ava-labs/avalanche-smart-contract-quickstart/blob/3fbba0ac28f6420e9be5d2635d5f23693f80127a/contracts/NFT.sol) found in `./contracts` of our project.

```solidity
//SPDX-License-Identifier: MIT
// contracts/ERC721.sol

pragma solidity >=0.6.2;

import "@openzeppelin/contracts/token/ERC721/ERC721.sol";
import "@openzeppelin/contracts/utils/Counters.sol";

contract NFT is ERC721 {
  using Counters for Counters.Counter;
  Counters.Counter private _tokenIds;

  constructor() ERC721("GameItem", "ITM") {}

  // commented out unused variable
  // function awardItem(address player, string memory tokenURI)
  function awardItem(address player)
    public
    returns (uint256)
  {
    _tokenIds.increment();

    uint256 newItemId = _tokenIds.current();
    _mint(player, newItemId);
    // _setTokenURI(newItemId, tokenURI);

    return newItemId;
  }
}
```

Let's examine this implementation of an NFT as a Game Item. We start by importing to contracts from our node modules. We import OpenZeppelin's open source implementation of the [ERC721 standard](https://docs.openzeppelin.com/contracts/2.x/api/token/erc721) which our NFT contract will inherit from. Our constructor takes the `_name` and `_symbol` arguments for our NFT and passes them on to the constructor of the parent ERC721 implementation. Lastly we implement the `awardItem` function which allows anyone to mint an NFT to a player's wallet address. This function increments the `currentTokenId` and makes use of the `_mint` function of our parent contract.

## Compile, Deploy, and Verify with Forge

[Forge](https://book.getfoundry.sh/reference/forge/forge-build.html) is a command-line tool that ships with Foundry. Forge tests, builds, and deploys your smart contracts.

It requires some initial project configuration in the form of a [foundry.toml](https://github.com/foundry-rs/foundry#configuration) which can be generated by running:

```bash
forge init --no-git --no-commit --force
```

The `foundry.toml` by default points to the folders it added. We will want to change this to make sure the `src` points to the `contracts` directory. Change your `foundry.toml` to look like the following:

```toml title="foundry.toml"
[profile.default]
src = 'contracts'
out = 'out'
libs = ["node_modules", "lib"]
remappings = [
    '@ensdomains/=node_modules/@ensdomains/',
    '@openzeppelin/=node_modules/@openzeppelin/',
    'hardhat/=node_modules/hardhat/',
]
```

By default, the contract artifacts will be in the `out` directory, as specified in the `foundry.toml`. To deploy our compiled contract with Forge, we have to set environment variables for the RPC endpoint and the private key we want to use to deploy.

Set your environment variables by running:

```bash
export RPC_URL=<YOUR-RPC-ENDPOINT>
export PRIVATE_KEY=<YOUR-PRIVATE-KEY>
```

Since we are deploying to Fuji testnet, our `RPC_URL` export should be:

```bash
export RPC_URL=https://api.avax-test.network/ext/bc/C/rpc
```

If you would like to verify you contracts during the deployment process (fastest and easiest way), get a [Snowtrace API Key](https://docs.snowtrace.io/getting-started/viewing-api-usage-statistics). Add this as an environment variable:

```bash
export ETHERSCAN_API_KEY=<YOUR-SNOWTRACE-API-KEY>
```

Once set, you can [deploy your NFT with Forge](https://book.getfoundry.sh/reference/forge/forge-create.html) by running the command below while adding the values for `_name` and `_symbol`, the relevant [constructor arguments](https://github.com/ava-labs/avalanche-smart-contract-quickstart/blob/3ad93abf50fba65e3aab68f23382bcace73968be/contracts/NFT.sol#L13) of the NFT contract. You can verify the contracts with Snowtrace by adding `--verify` before the `--constructor-args`:

```bash
forge create NFT --rpc-url=$RPC_URL --private-key=$PRIVATE_KEY --verify --constructor-args GameItem ITM
```

Upon successful deployment, you will see the deploying wallet's address, the contract's address as well as the transaction hash printed to your terminal.

Here's an example output from an NFT deployment and verification.

```bash
[⠔] Compiling...
No files changed, compilation skipped
Deployer: 0x8db97c7cece249c2b98bdc0226cc4c2a57bf52fc
Deployed to: 0x52c84043cd9c865236f11d9fc9f56aa003c1f922
Transaction hash: 0xf35c40dbbdc9e4298698ad1cb9937195e5a5e74e557bab1970a5dfd42a32f533
```

Upon successful verification, after your deployment you will see the contract verification status as `successfully verified`:

```bash
Starting contract verification...
Waiting for etherscan to detect contract deployment...
Start verifying contract `0x8e982a4ef70430f8317b5652bd5c28f147fbf912` deployed on fuji

Submitting verification for [contracts/NFT.sol:NFT] "0x8e982a4Ef70430f8317B5652Bd5C28F147FBf912".

Submitting verification for [contracts/NFT.sol:NFT] "0x8e982a4Ef70430f8317B5652Bd5C28F147FBf912".
Submitted contract for verification:
	Response: `OK`
	GUID: `cfkyqwvjjauafirepxt8qhks2zhptczzccqege9uefu9ma8wiz`
	URL:
        https://testnet.snowtrace.io/address/0x8e982a4ef70430f8317b5652bd5c28f147fbf912
Contract verification status:
Response: `NOTOK`
Details: `Pending in queue`
Contract verification status:
Response: `OK`
Details: `Pass - Verified`
Contract successfully verified
```

Note: Please store your `Deployed to` address for use in the next sections.

## Verifying After Deployment

If you did not verify within the deployment process, you can still verify a deployed contract with foundry, using [`forge verify-contract`](https://book.getfoundry.sh/reference/forge/forge-verify-contract). The `foundry.toml` and environment variables will have to be set like they were in the previous section.

For example, if we were to verify the NFT contract we just deployed in the previous section it would look this:

```bash
forge verify-contract --chain-id 43113 --watch --constructor-args $(cast abi-encode "constructor(string,string)" "GameItem" "ITM") 0x8e982a4ef70430f8317b5652bd5c28f147fbf912 NFT
```

Upon successful verification, you will see the contract verification status as `successfully verified`:

```bash
Starting contract verification...
Waiting for etherscan to detect contract deployment...
Start verifying contract `0x8e982a4ef70430f8317b5652bd5c28f147fbf912` deployed on fuji

Submitting verification for [contracts/NFT.sol:NFT] "0x8e982a4Ef70430f8317B5652Bd5C28F147FBf912".

Submitting verification for [contracts/NFT.sol:NFT] "0x8e982a4Ef70430f8317B5652Bd5C28F147FBf912".
Submitted contract for verification:
	Response: `OK`
	GUID: `cfkyqwvjjauafirepxt8qhks2zhptczzccqege9uefu9ma8wiz`
	URL:
        https://testnet.snowtrace.io/address/0x8e982a4ef70430f8317b5652bd5c28f147fbf912
Contract verification status:
Response: `NOTOK`
Details: `Pending in queue`
Contract verification status:
Response: `OK`
Details: `Pass - Verified`
Contract successfully verified
```

## Using Cast to Interact with the Smart Contract

We can call functions on our NFT contract with [Cast](https://book.getfoundry.sh/reference/cast/cast-send.html), Foundry's command-line tool for interacting with smart contracts, sending transactions, and getting chain data. In this scenario, we will mint a Game Item to a player's wallet using the [`awardItem` function](https://github.com/ava-labs/avalanche-smart-contract-quickstart/blob/0f29cbb6375a1a452579213f688609c880d52c01/contracts/NFT.sol#L17) in our smart contract.

Mint an NFT from your contract by replacing `<NFT-CONTRACT-ADDRESS>` with your `Deployed to` address and `<NFT-RECIPIENT-ADDRESS>` with an address of your choice.

_Note: This section assumes that you have already set your RPC and private key env variables during deployment_

```bash
cast send --rpc-url=$RPC_URL  <NFT-CONTRACT-ADDRESS> "awardItem(address)" <NFT-RECIPIENT-ADDRESS> --private-key=$PRIVATE_KEY
```

Upon success, the command line will display the [transaction data](https://testnet.snowtrace.io/tx/0x4651ae041a481a6eeb852e5300e9be48e66a1d2332733df22d8e75cf460b0c2c).

```bash
blockHash               0x1d9b0364fe002eeddd0e32be0c27d6797c63dffb51fe555ea446357759e6a6f8
blockNumber             10714448
contractAddress
cumulativeGasUsed       90837
effectiveGasPrice       28000000000
gasUsed                 90837
logs                    [{"address":"0x45857b942723fff8ee7acd2b1d6515d9965c16e5","topics":["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef","0x0000000000000000000000000000000000000000000000000000000000000000","0x000000000000000000000000845095a03a6686e24b90fed55e11f4ec808b1ab3","0x0000000000000000000000000000000000000000000000000000000000000001"],"data":"0x","blockHash":"0x1d9b0364fe002eeddd0e32be0c27d6797c63dffb51fe555ea446357759e6a6f8","blockNumber":"0xa37d50","transactionHash":"0x4651ae041a481a6eeb852e5300e9be48e66a1d2332733df22d8e75cf460b0c2c","transactionIndex":"0x0","logIndex":"0x0","removed":false}]
logsBloom               0x00000000000000000000000000000000000000000000000000000000000000040000000000000000000000000000000000000000000000000000000000040000000000000000000000000008010000000000000000040000000000000000000000000000020000040000000000000800000000002000000000000010000000000000000000000000000000000000000000000000000000000000000000000000000800000000000000000000000000000000000000000000000000000000000000000002000000000000000000000000000000000000000000000000000060080000000000000000000000000000000000000000000000000000000000000000
root
status                  1
transactionHash         0x4651ae041a481a6eeb852e5300e9be48e66a1d2332733df22d8e75cf460b0c2c
transactionIndex        0
type                    2
```

Well done! You just minted your first NFT from your contract. You can check the owner of `tokenId` 1 by running the `cast call` command below:

```bash
cast call --rpc-url=$RPC_URL --private-key=$PRIVATE_KEY <NFT-CONTRACT-ADDRESS> "ownerOf(uint256)" 1
```

The address you provided above should be returned as the owner.

```bash
0x000000000000000000000000845095a03a6686e24b90fed55e11f4ec808b1ab3
```

## Mainnet Workflow

The Fuji workflow above can be adapted to Mainnet with the following modifications to the environment variables:

```bash
export RPC_URL=https://api.avax.network/ext/bc/C/rpc
export PRIVATE_KEY=<YOUR-PRIVATE-KEY>
```

## Local Workflow

The Fuji workflow above can be adapted to a Local Network by doing following:

In a new terminal navigate to your [Avalanche Network Runner](/docs/tooling/avalanche-network-runner/introduction) directory.

```bash
cd /path/to/Avalanche-Network-Runner
```

Next, deploy a new Avalanche Network with five nodes (a Cluster) locally.

```bash
go run examples/local/fivenodenetwork/main.go
```

Next, modify the environment variables in your Foundry project:

```bash
export RPC_URL=http://localhost:9650/ext/bc/C/rpc
export PRIVATE_KEY=56289e99c94b6912bfc12adc093c9b51124f0dc54ac7a766b2bc5ccf558d8027
```

<Callout type="warn">
The example PRIVATE_KEY variable above provides a pre-funded account on Avalanche Network Runner and should be used for LOCAL DEVELOPMENT ONLY.
</Callout>

## Summary

Now you have the tools you need to launch a local Avalanche network, create a Foundry project, as well as create, compile, deploy and interact with Solidity contracts.

Join our [Discord Server](https://discord.gg/avax/) to learn more and ask any questions you may have.


# Hardhat (/docs/dapps/toolchains/hardhat)

---
title: Hardhat
description: Learn how to write, test and deploy smart contracts to Avalanche's C-Chain with Hardhat.
---

The goal of this guide is to lay out best practices regarding writing, testing and deployment of smart contracts to Avalanche's C-Chain. We'll be building smart contracts with [Hardhat](https://hardhat.org/).

## Prerequisites

### NodeJS and Yarn

First, install the LTS (long-term support) version of [NodeJS](https://nodejs.org/en). This is `18.x` at the time of writing. NodeJS bundles `npm`.

Next, install [yarn](https://yarnpkg.com/).

### AvalancheGo and Avalanche Network Runner

[AvalancheGo](https://github.com/ava-labs/avalanchego) is an Avalanche node implementation written in Go. [Avalanche Network Runner](/docs/tooling/avalanche-network-runner/introduction) is a tool to quickly deploy local test networks. Together, you can deploy local test networks and run tests on them.

### Solidity and Avalanche

It is also helpful to have a basic understanding of [Solidity](https://docs.soliditylang.org/) and Avalanche.

## Dependencies

Clone the [quickstart repository](https://github.com/ava-labs/avalanche-smart-contract-quickstart) and install the necessary packages via `yarn`.

```bash
git clone https://github.com/ava-labs/avalanche-smart-contract-quickstart.git
cd avalanche-smart-contract-quickstart
yarn install
```

<Callout title="Note">
The repository cloning method used is HTTPS, but SSH can be used too:

`git clone git@github.com:ava-labs/avalanche-smart-contract-quickstart.git`

You can find more about SSH and how to use it [here](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/about-ssh).
</Callout>

## Write Contracts

Edit the `ExampleERC20.sol` contract in `contracts/`. `ExampleERC20.sol` is an [Open Zeppelin](https://openzeppelin.com/) [ERC20](https://eips.ethereum.org/EIPS/eip-20) contract. ERC20 is a popular smart contract interface. You can also add your own contracts.

## Hardhat Config

Hardhat uses `hardhat.config.js` as the configuration file. You can define tasks, networks, compilers and more in that file. For more information see [here](https://hardhat.org/config/).

Here is an example pre-configured `hardhat.config.ts`.

```ts title="hardhat.config.ts"
import { task } from "hardhat/config";
import { SignerWithAddress } from "@nomiclabs/hardhat-ethers/signers";
import { BigNumber } from "ethers";
import "@nomiclabs/hardhat-waffle";

// When using the hardhat network, you may choose to fork Fuji or Avalanche Mainnet
// This will allow you to debug contracts using the hardhat network while keeping the current network state
// To enable forking, turn one of these booleans on, and then run your tasks/scripts using ``--network hardhat``
// For more information go to the hardhat guide
// https://hardhat.org/hardhat-network/
// https://hardhat.org/guides/mainnet-forking.html
const FORK_FUJI = false;
const FORK_MAINNET = false;
const forkingData = FORK_FUJI
  ? {
      url: "https://api.avax-test.network/ext/bc/C/rpc",
    }
  : FORK_MAINNET
  ? {
      url: "https://api.avax.network/ext/bc/C/rpc",
    }
  : undefined;

export default {
  solidity: {
    compilers: [
      {
        version: "0.5.16",
      },
      {
        version: "0.6.2",
      },
      {
        version: "0.6.4",
      },
      {
        version: "0.7.0",
      },
      {
        version: "0.8.0",
      },
    ],
  },
  networks: {
    hardhat: {
      gasPrice: 225000000000,
      chainId: !forkingData ? 43112 : undefined, //Only specify a chainId if we are not forking
      forking: forkingData,
    },
    local: {
      url: "http://localhost:9650/ext/bc/C/rpc",
      gasPrice: 225000000000,
      chainId: 43112,
      accounts: [
        "0x56289e99c94b6912bfc12adc093c9b51124f0dc54ac7a766b2bc5ccf558d8027",
        "0x7b4198529994b0dc604278c99d153cfd069d594753d471171a1d102a10438e07",
        "0x15614556be13730e9e8d6eacc1603143e7b96987429df8726384c2ec4502ef6e",
        "0x31b571bf6894a248831ff937bb49f7754509fe93bbd2517c9c73c4144c0e97dc",
        "0x6934bef917e01692b789da754a0eae31a8536eb465e7bff752ea291dad88c675",
        "0xe700bdbdbc279b808b1ec45f8c2370e4616d3a02c336e68d85d4668e08f53cff",
        "0xbbc2865b76ba28016bc2255c7504d000e046ae01934b04c694592a6276988630",
        "0xcdbfd34f687ced8c6968854f8a99ae47712c4f4183b78dcc4a903d1bfe8cbf60",
        "0x86f78c5416151fe3546dece84fda4b4b1e36089f2dbc48496faf3a950f16157c",
        "0x750839e9dbbd2a0910efe40f50b2f3b2f2f59f5580bb4b83bd8c1201cf9a010a",
      ],
    },
    fuji: {
      url: "https://api.avax-test.network/ext/bc/C/rpc",
      gasPrice: 225000000000,
      chainId: 43113,
      accounts: [],
    },
    mainnet: {
      url: "https://api.avax.network/ext/bc/C/rpc",
      gasPrice: 225000000000,
      chainId: 43114,
      accounts: [],
    },
  },
};
```

This configures necessary network information to provide smooth interaction with Avalanche. There are also some pre-defined private keys for testing on a local test network.

<Callout title="Note">
The port in this tutorial uses 9650. Depending on how you start your local network, it could be different.
</Callout>

## Hardhat Tasks

You can define custom hardhat tasks in `hardhat.config.ts`. There are two tasks included as examples: `accounts` and `balances`.

```ts title="hardhat.config.ts"
task(
  "accounts",
  "Prints the list of accounts",
  async (args, hre): Promise<void> => {
    const accounts: SignerWithAddress[] = await hre.ethers.getSigners();
    accounts.forEach((account: SignerWithAddress): void => {
      console.log(account.address);
    });
  }
);

task(
  "balances",
  "Prints the list of AVAX account balances",
  async (args, hre): Promise<void> => {
    const accounts: SignerWithAddress[] = await hre.ethers.getSigners();
    for (const account of accounts) {
      const balance: BigNumber = await hre.ethers.provider.getBalance(
        account.address
      );
      console.log(`${account.address} has balance ${balance.toString()}`);
    }
  }
);
```

- `npx hardhat accounts` prints the list of accounts.
- `npx hardhat balances` prints the list of AVAX account balances.

As with other `yarn` scripts, you can pass in a `--network` flag to hardhat tasks.

### Accounts

Prints a list of accounts on the local Avalanche Network Runner network.

```bash
npx hardhat accounts --network local
0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC
0x9632a79656af553F58738B0FB750320158495942
0x55ee05dF718f1a5C1441e76190EB1a19eE2C9430
0x4Cf2eD3665F6bFA95cE6A11CFDb7A2EF5FC1C7E4
0x0B891dB1901D4875056896f28B6665083935C7A8
0x01F253bE2EBF0bd64649FA468bF7b95ca933BDe2
0x78A23300E04FB5d5D2820E23cc679738982e1fd5
0x3C7daE394BBf8e9EE1359ad14C1C47003bD06293
0x61e0B3CD93F36847Abbd5d40d6F00a8eC6f3cfFB
0x0Fa8EA536Be85F32724D57A37758761B86416123
```

### Balances

Prints a list of accounts and their corresponding AVAX balances on the local Avalanche Network Runner network.

```bash
npx hardhat balances --network local
0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC has balance 50000000000000000000000000
0x9632a79656af553F58738B0FB750320158495942 has balance 0
0x55ee05dF718f1a5C1441e76190EB1a19eE2C9430 has balance 0
0x4Cf2eD3665F6bFA95cE6A11CFDb7A2EF5FC1C7E4 has balance 0
0x0B891dB1901D4875056896f28B6665083935C7A8 has balance 0
0x01F253bE2EBF0bd64649FA468bF7b95ca933BDe2 has balance 0
0x78A23300E04FB5d5D2820E23cc679738982e1fd5 has balance 0
0x3C7daE394BBf8e9EE1359ad14C1C47003bD06293 has balance 0
0x61e0B3CD93F36847Abbd5d40d6F00a8eC6f3cfFB has balance 0
0x0Fa8EA536Be85F32724D57A37758761B86416123 has balance 0
```

Notice that the first account is already funded. This is because this address is pre-funded in the local network genesis file.

### ERC20 Balances

```ts title="hardhat.config.ts"
task(
  "check-erc20-balance",
  "Prints out the ERC20 balance of your account"
).setAction(async function (taskArguments, hre) {
  const genericErc20Abi = require("./erc20.abi.json");
  const tokenContractAddress = "0x...";
  const provider = ethers.getDefaultProvider(
    "https://api.avax.network/ext/bc/C/rpc"
  );
  const contract = new ethers.Contract(
    tokenContractAddress,
    genericErc20Abi,
    provider
  );
  const balance = await contract.balanceOf("0x...");
  console.log(`Balance in wei: ${balance}`);
});
```

This will return the result in wei. If you want to know the exact amount of token with its token name then you need to divide it with its decimal. `erc20.abi.json` can be [found here](https://gist.github.com/veox/8800debbf56e24718f9f483e1e40c35c).

The example uses the [C-Chain Public API](/docs/api-reference/c-chain/api#endpoints) for the provider. For a local Avalanche network use `http://127.0.0.1:9650/ext/bc/C/rpc` and for Fuji Testnet use `https://api.avax-test.network/ext/bc/C/rpc`.

## Hardhat Help

Run `yarn hardhat` to list Hardhat's version, usage instructions, global options and available tasks.

## Typical Avalanche Network Runner Workflow

### Run Avalanche Network Runner

First confirm you have the latest AvalancheGo built.

```bash
cd /path/to/avalanchego
git fetch -p
git checkout master
./scripts/build.sh
```

(Note that you can also [download pre-compiled AvalancheGo binaries](https://github.com/ava-labs/avalanchego/releases) rather than building from source.)

Confirm you have Avalanche Network Runner installed by following the steps listed [here](/docs/tooling/avalanche-network-runner/introduction)

Start Avalanche Network Runner and run a script to start a new local network.

### Start the Server

```bash
cd /path/to/Avalanche-Network-Runner

# next command
avalanche-network-runner server \
--log-level debug \
--port=":8080" \
--grpc-gateway-port=":8081"
```

### Start a New Avalanche Network with Five Nodes

```bash
# replace execPath with the path to AvalancheGo on your machine
# e.g., ${HOME}/go/src/github.com/ava-labs/avalanchego/build/avalanchego

AVALANCHEGO_EXEC_PATH="avalanchego"
```

```bash
avalanche-network-runner control start \
--log-level debug \
--endpoint="0.0.0.0:8080" \
--number-of-nodes=5 \
--avalanchego-path ${AVALANCHEGO_EXEC_PATH}
```

Now you're running a local Avalanche network with 5 nodes.

### Fund Accounts

Transfer 1,000 AVAX from the X-Chain to each of the 10 accounts in `hardhat.config.ts` with the script [`fund-cchain-addresses`](https://github.com/ava-labs/avalanche-smart-contract-quickstart/blob/main/scripts/fund-cchain-addresses.js). Funding these accounts is a prerequisite for deploying and interacting with smart contracts.

Note: If you see `Error: Invalid JSON RPC response: "API call rejected because chain is not done bootstrapping"`, you need to wait until network is bootstrapped and ready to use. It should not take too long.

```bash
cd /path/to/avalanche-smart-contract-quickstart
yarn fund-cchain-addresses
```

Confirm each of the accounts are funded with 1000 AVAX.

```bash
yarn balances --network local

# output
yarn run v1.22.4
npx hardhat balances --network local
0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC has balance 50000001000000000000000000
0x9632a79656af553F58738B0FB750320158495942 has balance 1000000000000000000
0x55ee05dF718f1a5C1441e76190EB1a19eE2C9430 has balance 1000000000000000000
0x4Cf2eD3665F6bFA95cE6A11CFDb7A2EF5FC1C7E4 has balance 1000000000000000000
0x0B891dB1901D4875056896f28B6665083935C7A8 has balance 1000000000000000000
0x01F253bE2EBF0bd64649FA468bF7b95ca933BDe2 has balance 1000000000000000000
0x78A23300E04FB5d5D2820E23cc679738982e1fd5 has balance 1000000000000000000
0x3C7daE394BBf8e9EE1359ad14C1C47003bD06293 has balance 1000000000000000000
0x61e0B3CD93F36847Abbd5d40d6F00a8eC6f3cfFB has balance 1000000000000000000
0x0Fa8EA536Be85F32724D57A37758761B86416123 has balance 1000000000000000000
✨  Done in 0.72s.
```

Send each of the accounts some AVAX from the first account.

```bash
yarn send-avax-wallet-signer --network local

# output
yarn run v1.22.4
npx hardhat run scripts/sendAvaWalletSigner.ts --network local
Seeding addresses with AVAX
✨  Done in 1.33s.
```

Confirm that the balances are updated

```bash
yarn balances --network local

# output
yarn run v1.22.4
npx hardhat balances --network local
0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC has balance 49999999995275000000000000
0x9632a79656af553F58738B0FB750320158495942 has balance 1000010000000000000000
0x55ee05dF718f1a5C1441e76190EB1a19eE2C9430 has balance 1000010000000000000000
0x4Cf2eD3665F6bFA95cE6A11CFDb7A2EF5FC1C7E4 has balance 1000010000000000000000
0x0B891dB1901D4875056896f28B6665083935C7A8 has balance 1000010000000000000000
0x01F253bE2EBF0bd64649FA468bF7b95ca933BDe2 has balance 1000010000000000000000
0x78A23300E04FB5d5D2820E23cc679738982e1fd5 has balance 1000010000000000000000
0x3C7daE394BBf8e9EE1359ad14C1C47003bD06293 has balance 1000010000000000000000
0x61e0B3CD93F36847Abbd5d40d6F00a8eC6f3cfFB has balance 1000010000000000000000
0x0Fa8EA536Be85F32724D57A37758761B86416123 has balance 1000010000000000000000
```

Note: If you see `Error HH108: Cannot connect to the network local. Please make sure your node is running, and check your internet connection and networks config`, ensure that you are using a valid Node Port. See which ports the Nodes are using by running the command:

```bash
cd /path/to/avalanche-network-runner

# next command
avalanche-network-runner control uris \
--log-level debug \
--endpoint="0.0.0.0:8080"
```

### Compile Smart Contracts

In [`package.json`](https://github.com/ava-labs/avalanche-smart-contract-quickstart/blob/main/package.json) there's a `compile` script.

```json title="package.json"
"compile": "npx hardhat compile",
```

Run `yarn compile` to make sure your project compiles.

```bash
yarn compile

# output
yarn run v1.22.4
rimraf ./build/
npx hardhat compile
Compiling 1 file with 0.6.4
Compilation finished successfully
✨  Done in 2.13s.
```

## Deploy Smart Contracts

Hardhat enables deploying to multiple environments. In [package.json](https://github.com/ava-labs/avalanche-smart-contract-quickstart/blob/main/package.json) there is a script for deploying.

Edit the deployment script in `scripts/deploy.ts`

```ts
"deploy": "npx hardhat run scripts/deploy.ts"
```

You can choose which environment that you want to deploy to by passing in the `--network` flag with `local` (for example a local network created with Avalanche Network Runner), `fuji`, or `mainnet` for each respective environment. If you don't pass in `--network` then it will default to the hardhat network. For example, if you want to deploy to Mainnet:

```bash
yarn deploy --network mainnet
```

Deploy the contract to your local network:

```bash
yarn deploy --network local

# output
yarn run v1.22.4
npx hardhat run scripts/deploy.ts --network local
Coin deployed to: 0x17aB05351fC94a1a67Bf3f56DdbB941aE6
✨  Done in 1.28s.
```

We now have a token deployed at `0x17aB05351fC94a1a67Bf3f56DdbB941aE6`.

### Interact with Smart Contract

Hardhat has a developer console to interact with contracts and the network. For more information about Hardhat's console see [here](https://hardhat.org/guides/hardhat-console.html). Hardhat console is a NodeJS-REPL, and you can use different tools in it. [Ethers](https://docs.ethers.io/v5/) is the library that we'll use to interact with our network.

You can open console with:

```bash
yarn console --network local

# output
yarn run v1.22.11
npx hardhat console --network local
Welcome to Node.js v16.2.0.
Type ".help" for more information.
```

Get the contract instance with factory and contract address to interact with our contract:

```js
> const Coin = await ethers.getContractFactory('ExampleERC20');
undefined
> const coin = await Coin.attach('0x17aB05351fC94a1a67Bf3f56DdbB941aE6')
undefined
```

The first line retrieves contract factory with ABI & bytecode. The second line retrieves an instance of that contract factory with given contract address. Recall that our contract was already deployed to `0x17aB05351fC94a1a67Bf3f56DdbB941aE6` in the previous step.

Fetch the accounts:

```js
> let accounts = await ethers.provider.listAccounts()
undefined
> accounts
[
  '0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC',
  '0x9632a79656af553F58738B0FB750320158495942',
  '0x55ee05dF718f1a5C1441e76190EB1a19eE2C9430',
  '0x4Cf2eD3665F6bFA95cE6A11CFDb7A2EF5FC1C7E4',
  '0x0B891dB1901D4875056896f28B6665083935C7A8',
  '0x01F253bE2EBF0bd64649FA468bF7b95ca933BDe2',
  '0x78A23300E04FB5d5D2820E23cc679738982e1fd5',
  '0x3C7daE394BBf8e9EE1359ad14C1C47003bD06293',
  '0x61e0B3CD93F36847Abbd5d40d6F00a8eC6f3cfFB',
  '0x0Fa8EA536Be85F32724D57A37758761B86416123'
]
```

This is exactly the same account list as in `yarn accounts`.

Now we can interact with our `ERC-20` contract:

```js
> let value = await coin.balanceOf(accounts[0])
undefined
> value.toString()
'123456789'
> value = await coin.balanceOf(accounts[1])
BigNumber { _hex: '0x00', _isBigNumber: true }
> value.toString()
'0'
```

`account[0]` has a balance because `account[0]` is the default account. The contract is deployed with this account. The constructor of [ERC20.sol](https://github.com/ava-labs/avalanche-smart-contract-quickstart/blob/main/contracts/ExampleERC20.sol) mints `TOTAL_SUPPLY` of 123456789 token to the deployer of the contract.

`accounts[1]` currently has no balance. Send some tokens to `accounts[1]`, which is `0x9632a79656af553F58738B0FB750320158495942`.

```js
> let result = await coin.transfer(accounts[1], 100)
undefined
> result
{
  hash: '0x35eec91011f9089ba7689479617a90baaf8590395b5c80bb209fa7000e4848a5',
  type: 0,
  accessList: null,
  blockHash: null,
  blockNumber: null,
  transactionIndex: null,
  confirmations: 0,
  from: '0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC',
  gasPrice: BigNumber { _hex: '0x34630b8a00', _isBigNumber: true },
  gasLimit: BigNumber { _hex: '0x8754', _isBigNumber: true },
  to: '0x17aB05351fC94a1a67Bf3f56DdbB941aE6c63E25',
  value: BigNumber { _hex: '0x00', _isBigNumber: true },
  nonce: 3,
  data: '0xa9059cbb0000000000000000000000009632a79656af553f58738b0fb7503201584959420000000000000000000000000000000000000000000000000000000000000064',
  r: '0xc2b9680771c092a106eadb2887e5bff41fcda166c8e00f36ae79b196bbc53d36',
  s: '0x355138cb5e2b9f20c15626638750775cfc9423881db374d732a8549d05ebf601',
  v: 86260,
  creates: null,
  chainId: 43112,
  wait: [Function (anonymous)]
}
```

Note: Since this is a local network, we did not need to wait until transaction is accepted. However for other networks like `fuji` or `mainnet` you need to wait until transaction is accepted with: `await result.wait()`.

Now we can ensure that tokens are transferred:

```js
> value = await coin.balanceOf(accounts[0])
BigNumber { _hex: '0x075bccb1', _isBigNumber: true }
> value.toString()
'123456689'
> value = await coin.balanceOf(accounts[1])
BigNumber { _hex: '0x64', _isBigNumber: true }
> value.toString()
'100'
```

As you might noticed there was no "sender" information in `await coin.transfer(accounts[1], 100)`; this is because `ethers` uses the first signer as the default signer. In our case this is `account[0]`. If we want to use another account we need to connect with it first.

```js
> let signer1 = await ethers.provider.getSigner(1)
> let contractAsSigner1 = coin.connect(signer1)
```

Now we can call the contract with `signer1`, which is `account[1]`.

```js
> await contractAsSigner1.transfer(accounts[0], 5)
{
  hash: '0x807947f1c40bb723ac312739d238b62764ae3c3387c6cdbbb6534501577382dd',
  type: 0,
  accessList: null,
  blockHash: null,
  blockNumber: null,
  transactionIndex: null,
  confirmations: 0,
  from: '0x9632a79656af553F58738B0FB750320158495942',
  gasPrice: BigNumber { _hex: '0x34630b8a00', _isBigNumber: true },
  gasLimit: BigNumber { _hex: '0x8754', _isBigNumber: true },
  to: '0x17aB05351fC94a1a67Bf3f56DdbB941aE6c63E25',
  value: BigNumber { _hex: '0x00', _isBigNumber: true },
  nonce: 2,
  data: '0xa9059cbb0000000000000000000000008db97c7cece249c2b98bdc0226cc4c2a57bf52fc0000000000000000000000000000000000000000000000000000000000000005',
  r: '0xcbf126dd0b109491d037c5f3af754ef2d0d7d06149082b13d0e27e502d3adc5b',
  s: '0x5978521804dd15674147cc6b532b8801c4d3a0e94f41f5d7ffaced14b9262504',
  v: 86259,
  creates: null,
  chainId: 43112,
  wait: [Function (anonymous)]
}
```

Let's check balances now:

```js
> value = await coin.balanceOf(accounts[0])
BigNumber { _hex: '0x075bccb6', _isBigNumber: true }
> value.toString()
'123456694'
> value = await coin.balanceOf(accounts[1])
BigNumber { _hex: '0x5f', _isBigNumber: true }
> value.toString()
'95'
```

We've successfully transferred 5 tokes from `accounts[1]` to `accounts[0]`

## Summary

Now you have the tools you need to launch a local Avalanche network, create a Hardhat project, as well as create, compile, deploy and interact with Solidity contracts.

Join our [Discord Server](https://discord.gg/avax/) to learn more and ask any questions you may have.


# Toolchains (/docs/dapps/toolchains)

---
title: Toolchains
description: Learn about different toolchains available on the Avalanche C-chain.
index: true
---


# ThirdWeb (/docs/dapps/toolchains/thirdweb)

---
title: ThirdWeb
description: Learn how to deploy a smart contract using thirdweb's command line interface.
---

This tutorial walks through creating and deploying a smart contract using thirdweb's command line interface.

Alternatively, you can deploy a prebuilt contract for NFTs, tokens, or marketplace directly from the thirdweb Explore page:

1. Go to the thirdweb Explore page: [https://thirdweb.com/explore](https://thirdweb.com/explore)
2. Choose the type of contract you want to deploy from the available options: NFTs, tokens, marketplace, and more.
3. Follow the on-screen prompts to configure and deploy your contract.

> For more information on different contracts available on Explore, check out [thirdweb's documentation.](https://portal.thirdweb.com/pre-built-contracts)

## Creating Contracts

To create a new smart contract using thirdweb CLI, follow these steps:

1. In your CLI run the following command:
   ```bash
   npx thirdweb create contract
   ```

2. Input your preferences for the command line prompts:
   1. Give your project a name.
   2. Choose your preferred framework: Hardhat or Foundry.
   3. Name your smart contract.
   4. Choose the type of base contract: Empty, [ERC20](https://portal.thirdweb.com/solidity/base-contracts/erc20base), [ERC721](https://portal.thirdweb.com/solidity/base-contracts/erc721base), or [ERC1155](https://portal.thirdweb.com/solidity/base-contracts/erc1155base).
   5. Add any desired [extensions](https://portal.thirdweb.com/solidity/extensions).

3. Once created, navigate to your project's directory and open in your preferred code editor.

4. In the `contracts` folder, you will find the smart contract written in Solidity.

    The following is code for an ERC721Base contract without specified extensions. It implements all of the logic inside the [`ERC721Base.sol`](https://github.com/thirdweb-dev/contracts/blob/main/contracts/base/ERC721Base.sol) 
    contract; which implements [`ERC721A`](https://github.com/thirdweb-dev/contracts/blob/main/contracts/eip/ERC721A.sol) standard.
    
    ```solidity
    // SPDX-License-Identifier: MIT
    pragma solidity ^0.8.x;

    import "@third-web/dev/contracts/base/ERC721Base.sol";

    contract Contract is ERC721Base {
        constructor(
            string memory _name,
            string memory _symbol,
            address _royaltyRecipient,
            uint128 _royaltyBps
        ) ERC721Base(_name,_symbol,_royaltyRecipient,_royaltyBps){}
     }
     ```
     
     This contract inherits functionality of ERC721Base through following steps:
     
     - Importing the ERC721Base contract.
     - Inheriting the contract by declaring that our contract is an ERC721Base contract.
     - Implementing any required methods such as constructor.

5. After modifying your contract with your desired custom logic, you may deploy it on Avalanche with the following command:
    ```
    npx thirdweb deploy
    ```

## Deploying Contracts

Deploy allows you to deploy a smart contract to any EVM compatible network without configuring RPC URLs, exposing your private keys, writing scripts, and other additional setup such as verifying your contract.

1. To deploy your smart contract using `deploy`, navigate to the root directory of your project and execute the following command:
    ```
    npx thirdweb deploy
    ```

    Executing this command will trigger the following actions:

    - Compiling all the contracts in the current directory.
    - Providing the option to select which contracts you wish to deploy.
    - Uploading your contract source code (ABI) to IPFS.

2. When it is completed, it will open a dashboard interface to finish filling out the parameters.

    - `_name`: contract name
    - `_symbol`: symbol or "ticker"
    - `_royaltyRecipient`: wallet address to receive royalties from secondary sales
    - `_royaltyBps`: basis points that will be given to royalty recipient for each secondary sale. For example: 500 = 5%.

3. Select "Avalanche" as the network.

4. Manage additional settings on your contract's dashboard as needed such as uploading NFTs, configuring permissions, and more.

For additional information on deploying smart contracts with thirdweb, please reference [thirdweb's documentation](https://portal.thirdweb.com/deploy).

If you have any further questions or encounter any issues during the process, please reach out to thirdweb support at [support.thirdweb.com](http://support.thirdweb.com/).



# Using Explorer (/docs/dapps/verify-contract/explorer)

---
title: Using Explorer
description: Learn how to verify a smart contract using the official Avalanche Explorer.
---

This document outlines the process of verifying a Smart Contract deployed on the Avalanche Network using the official explorer.

## Contract Deployment

1. Compile the smart contract using the tooling of your choice.

2. Deploy the compiled smart contract to the Avalanche network.
   - This can be done on either the mainnet or testnet (depending on your RPC configuration)

3. Upon successful deployment, you will receive:
   - A transaction hash
   - A contract address

<Callout title="Note">
Ensure you save the contract address as it will be required for the verification process.
</Callout>

## Contract Verification

1. Navigate to the official [Avalanche Explorer](https://subnets.avax.network/) and click on **Tools** dropdown menu to select **Smart Contract Verification** interface. You may need to open the [Testnet Explorer](https://subnets-test.avax.network/) in case the contract is deployed on Fuji Testnet.

![](/images/verification-portal.png)

2. Prepare the following files:
   - The contract's Solidity file (`.sol`)
   - The `metadata.json` file containing the ABI and metadata

3. Upload the required files:
   - Upload the contract's Solidity file
   - Upload the `metadata.json` file

4. Enter the contract address:
   - Paste the contract address obtained from the deployment step into the designated input field.

![](/images/contract-addr-input.png)

5. Initiate verification:
   - Click on the **Submit Contract** button to start the verification process.

## Next Steps

After submitting the contract for verification, your request will be processed shortly and you will see the below message.

![](/images/verification-success.png)

For any issues during deployment or verification, please reach out to the DevRel/Support team on Discord/Telegram/Slack.

# Using HardHat (/docs/dapps/verify-contract/hardhat)

---
title: Using HardHat
description: Learn how to verify a smart contract using Hardhat.
---

This tutorial assumes that the contract was deployed using Hardhat and that all Hardhat dependencies are properly installed.

After deploying a smart contract one can verify the smart contract on Snowtrace in three steps:

1.  Flatten the Smart Contract
2.  Clean up the flattened contract
3.  Verify using the Snowtrace GUI

## Flatten Smart Contract using Hardhat

To flatten the contract, run the command: `npx hardhat flatten <path-to-contract> >> <flat-contract-name>.sol`

## Cleanup the Flattened Smart Contract

Some clean-up may be necessary to get the code to compile properly in the Snowtrace Contract Verifier

- Remove all but the top SPDX license.
- If the contract uses multiple SPDX licenses, use both licenses by adding **AND**: `SPDX-License-Identifier: MIT AND BSD-3-Clause`

## Verify Smart Contract using Snowtrace UI

Snowtrace is currently working on a new user interface (UI) for smart contract verification. Meanwhile, you may consider using their API for a seamless smart contract verification experience.

## Verify Smart Contract Programmatically Using APIs

Ensure you have Postman or any other API platform installed on your computer (or accessible through online services), along with your contract's source code and the parameters utilized during deployment.

Here is the API call URL to use for a POST request: `https://api.snowtrace.io/api?module=contract&action=verifysourcecode`

Please note that this URL is specifically configured for verifying contracts on the Avalanche C-Chain Mainnet. If you intend to verify on the Fuji Testnet, use: `https://api-testnet.snowtrace.io/api?module=contract&action=verifysourcecode`

Here's the body of the API call with the required parameters:

```json
{
  "contractaddress": "YOUR_CONTRACT_ADDRESS",
  "sourceCode": "YOUR_FLATTENED_SOURCE_CODE",
  "codeformat": "solidity-single-file",
  "contractname": "YOUR_CONTRACT_NAME",
  "compilerversion": "YOUR_COMPILER_VERSION",
  "optimizationUsed": "YOUR_OPTIMIZATION_VALUE",  // 0 if not optimized, 1 if optimized
  "runs": "YOUR_OPTIMIZATION_RUNS",  // remove if not applicable
  "licenseType": "YOUR_LICENSE_TYPE",  // 1 if not specified
  "apikey": "API_KEY_PLACEHOLDER", // you don't need an API key, use a placeholder
  "evmversion": "YOUR_EVM_VERSION_ON_REMIX",
  "constructorArguments": "YOUR_CONSTRUCTOR_ARGUMENTS"  // Remove if not applicable
}
```

## Verifying with Hardhat-Verify

This part of the tutorial assumes that the contract was deployed using Hardhat and that all Hardhat dependencies are properly installed to include `'@nomiclabs/hardhat-etherscan'`.

You will need to create a `.env.json` with your _Wallet Seed Phrase_. You don't need an API key to verify on Snowtrace.

Example `.env.json`:

```json title=".env.json"
{
  "MNEMONIC": "your-wallet-seed-phrase",
}
```

Below is a sample `hardhat.config.ts` used for deployment and verification:

```ts title="hardhat.config.ts"
import { task } from "hardhat/config"
import { SignerWithAddress } from "@nomiclabs/hardhat-ethers/signers"
import { BigNumber } from "ethers"
import "@typechain/hardhat"
import "@nomiclabs/hardhat-ethers"
import "@nomiclabs/hardhat-waffle"
import "hardhat-gas-reporter"
import "@nomiclabs/hardhat-etherscan"
import { MNEMONIC, APIKEY } from "./.env.json"

// When using the hardhat network, you may choose to fork Fuji or Avalanche Mainnet
// This will allow you to debug contracts using the hardhat network while keeping the current network state
// To enable forking, turn one of these booleans on, and then run your tasks/scripts using ``--network hardhat``
// For more information go to the hardhat guide
// https://hardhat.org/hardhat-network/
// https://hardhat.org/guides/mainnet-forking.html
const FORK_FUJI = false
const FORK_MAINNET = false
const forkingData = FORK_FUJI
  ? {
      url: "https://api.avax-test.network/ext/bc/C/rpc",
    }
  : FORK_MAINNET
  ? {
      url: "https://api.avax.network/ext/bc/C/rpc",
    }
  : undefined

task(
  "accounts",
  "Prints the list of accounts",
  async (args, hre): Promise<void> => {
    const accounts: SignerWithAddress[] = await hre.ethers.getSigners()
    accounts.forEach((account: SignerWithAddress): void => {
      console.log(account.address)
    })
  }
)

task(
  "balances",
  "Prints the list of AVAX account balances",
  async (args, hre): Promise<void> => {
    const accounts: SignerWithAddress[] = await hre.ethers.getSigners()
    for (const account of accounts) {
      const balance: BigNumber = await hre.ethers.provider.getBalance(
        account.address
      )
      console.log(`${account.address} has balance ${balance.toString()}`)
    }
  }
)
export default {
  etherscan: {
    // Your don't need an API key for Snowtrace
  },

  solidity: {
    compilers: [
      {
        version: "0.8.0",
      },
      {
        version: "0.8.10",
      },
    ],
  },
  networks: {
    hardhat: {
      gasPrice: 225000000000,
      chainId: 43114, //Only specify a chainId if we are not forking
      // forking: {
      //   url: 'https://api.avax.network/ext/bc/C/rpc',
      // },
    },
    fuji: {
      url: "https://api.avax-test.network/ext/bc/C/rpc",
      gasPrice: 225000000000,
      chainId: 43113,
      accounts: { mnemonic: MNEMONIC },
    },
    mainnet: {
      url: "https://api.avax.network/ext/bc/C/rpc",
      gasPrice: 225000000000,
      chainId: 43114,
      accounts: { mnemonic: MNEMONIC },
    },
  },
}
```

Once the contract is deployed, verify with hardhat verify by running the following:

```bash
npx hardhat verify <contract address> <arguments> --network <network>
```

Example:

```bash
npx hardhat verify 0x3972c87769886C4f1Ff3a8b52bc57738E82192D5 MockNFT Mock ipfs://QmQ2RFEmZaMds8bRjZCTJxo4DusvcBdLTS6XuDbhp5BZjY 100 --network fuji
```

You can also verify contracts programmatically via script. Example:

```ts title="verify.ts"
import console from "console"
const hre = require("hardhat")

// Define the NFT
const name = "MockNFT"
const symbol = "Mock"
const _metadataUri = "ipfs://QmQ2RFEmZaMds8bRjZCTJxo4DusvcBdLTS6XuDbhp5BZjY"
const _maxTokens = "100"

async function main() {
  await hre.run("verify:verify", {
    address: "0x3972c87769886C4f1Ff3a8b52bc57738E82192D5",
    constructorArguments: [name, symbol, _metadataUri, _maxTokens],
  })
}

main()
  .then(() => process.exit(0))
  .catch((error) => {
    console.error(error)
    process.exit(1)
  })
```

First create your script, then execute it via hardhat by running the following:

```bash
npx hardhat run scripts/verify.ts --network fuji
```

Verifying via terminal will not allow you to pass an array as an argument, however, you can do this when verifying via script by including the array in your _Constructor Arguments_. Example: 

```ts
import console from "console"
const hre = require("hardhat")

// Define the NFT
const name = "MockNFT"
const symbol = "Mock"
const _metadataUri =
  "ipfs://QmQn2jepp3jZ3tVxoCisMMF8kSi8c5uPKYxd71xGWG38hV/Example"
const _royaltyRecipient = "0xcd3b766ccdd6ae721141f452c550ca635964ce71"
const _royaltyValue = "50000000000000000"
const _custodians = [
  "0x8626f6940e2eb28930efb4cef49b2d1f2c9c1199",
  "0xf39fd6e51aad88f6f4ce6ab8827279cfffb92266",
  "0xdd2fd4581271e230360230f9337d5c0430bf44c0",
]
const _saleLength = "172800"
const _claimAddress = "0xcd3b766ccdd6ae721141f452c550ca635964ce71"

async function main() {
  await hre.run("verify:verify", {
    address: "0x08bf160B8e56899723f2E6F9780535241F145470",
    constructorArguments: [
      name,
      symbol,
      _metadataUri,
      _royaltyRecipient,
      _royaltyValue,
      _custodians,
      _saleLength,
      _claimAddress,
    ],
  })
}

main()
  .then(() => process.exit(0))
  .catch((error) => {
    console.error(error)
    process.exit(1)
  })
```



# Using Snowtrace (/docs/dapps/verify-contract/snowtrace)

---
title: Using Snowtrace
description: Learn how to verify a contract on the Avalanche C-chain using Snowtrace.
---

The C-Chain Explorer supports verifying smart contracts, allowing users to review it. The Mainnet C-Chain Explorer is [here](https://snowtrace.io/) and the Fuji Testnet Explorer is [here.](https://testnet.snowtrace.io/)

If you have issues, contact us on [Discord](https://chat.avalabs.org/).

## Steps

Navigate to the _Contract_ tab at the Explorer page for your contract's address.

![verify and publish](/images/snowtrace1.png)

Click _Verify & Publish_ to enter the smart contract verification page.

![SRC](/images/snowtrace2.png)

[Libraries](https://docs.soliditylang.org/en/v0.8.4/contracts.html?highlight=libraries#libraries) can be provided. If they are, they must be deployed, independently verified and in the _Add Contract Libraries_ section.

![libraries](/images/snowtrace3.png)

The C-Chain Explorer can fetch constructor arguments automatically for simple smart contracts. More complicated contracts might require you to pass in special constructor arguments. Smart contracts with complicated constructors [may have validation issues](/docs/dapps/verify-contract/snowtrace#caveats). You can try this [online ABI encoder](https://abi.hashex.org/).

## Requirements

- **IMPORTANT** Contracts should be verified on Testnet before being deployed to Mainnet to ensure there are no issues.
- Contracts must be flattened. Includes will not work.
- Contracts should be compile-able in [Remix](https://remix.ethereum.org/). A flattened contract with `pragma experimental ABIEncoderV2` (as an example) can create unusual binary and/or constructor blobs. This might cause validation issues.
- The C-Chain Explorer **only** validates [solc JavaScript](https://github.com/ethereum/solc-bin) and only supports [Solidity](https://docs.soliditylang.org/) contracts.

## Libraries

The compile bytecode will identify if there are external libraries. If you released with Remix, you will also see multiple transactions created.

```
{
  "linkReferences": {
    "contracts/Storage.sol": {
      "MathUtils": [
        {
          "length": 20,
          "start": 3203
        }
        ...
      ]
    }
  },
  "object": "....",
  ...
}
```

This requires you to add external libraries in order to verify the code.

A library can have dependent libraries. To verify a library, the hierarchy of dependencies will need to be provided to the C-Chain Explorer. Verification may fail if you provide more than the library plus any dependencies (that is you might need to prune the Solidity code to exclude anything but the necessary classes).

You can also see references in the byte code in the form `__$75f20d36....$__`. The keccak256 hash is generated from the library name.

Example [online converter](https://emn178.github.io/online-tools/keccak_256.html): `contracts/Storage.sol:MathUtils` => `75f20d361629befd780a5bd3159f017ee0f8283bdb6da80805f83e829337fd12`

## Examples

- [SwapFlashLoan](https://testnet.snowtrace.io/address/0x12DF75Fed4DEd309477C94cE491c67460727C0E8/contract/43113/code)

SwapFlashLoan uses `swaputils` and `mathutils`:

- [SwapUtils](https://testnet.snowtrace.io/address/0x6703e4660E104Af1cD70095e2FeC337dcE034dc1/contract/43113/code)

SwapUtils requires mathutils:

- [MathUtils](https://testnet.snowtrace.io/address/0xbA21C84E4e593CB1c6Fe6FCba340fa7795476966/contract/43113/code)

## Caveats

### SPDX License Required

An SPDX must be provided.

```solidity
// SPDX-License-Identifier: ...
```

### `keccak256` Strings Processed

The C-Chain Explorer interprets all keccak256(...) strings, even those in comments. This can cause issues with constructor arguments.

```solidity
/// keccak256("1");
keccak256("2");
```

This could cause automatic constructor verification failures. If you receive errors about constructor arguments they can be provided in ABI hex encoded form on the contract verification page.

### Solidity Constructors

Constructors and inherited constructors can cause problems verifying the constructor arguments. Example:

```solidity
abstract contract Parent {
  constructor () {
    address msgSender = ...;
    emit Something(address(0), msgSender);
  }
}
contract Main is Parent {
  constructor (
          string memory _name,
          address deposit,
          uint fee
  ) {
    ...
  }
}
```

If you receive errors about constructor arguments, they can be provided in ABI hex encoded form on the contract verification page.


# Deep Dive into ICM (/docs/cross-chain/avalanche-warp-messaging/deep-dive)

---
title: "Deep Dive into ICM"
description: "Learn about Avalanche Warp Messaging, a cross-Avalanche L1 communication protocol on Avalanche."
edit_url: https://github.com/ava-labs/avalanchego/edit/master/vms/platformvm/warp/README.md
---

# Avalanche Interchain Messaging

Avalanche Interchain Messaging (ICM) provides a primitive for cross-chain communication on the Avalanche Network.

The Avalanche P-Chain provides an index of every network's validator set on the Avalanche Network, including the BLS public key of each validator (as of the [Banff Upgrade](https://github.com/ava-labs/avalanchego/releases/v1.9.0)). ICM utilizes the weighted validator sets stored on the P-Chain to build a cross-chain communication protocol between any two networks on Avalanche.

Any Virtual Machine (VM) on Avalanche can integrate Avalanche Interchain Messaging to send and receive messages cross-chain.

## Background

This README assumes familiarity with:

- Avalanche P-Chain / [PlatformVM](https://github.com/ava-labs/avalanchego/tree/master/vms/platformvm/)
- [ProposerVM](https://github.com/ava-labs/avalanchego/tree/master/vms/proposervm/README.md)
- Basic familiarity with [BLS Multi-Signatures](https://crypto.stanford.edu/~dabo/pubs/papers/BLSmultisig.html)

## BLS Multi-Signatures with Public-Key Aggregation

Avalanche Interchain Messaging utilizes BLS multi-signatures with public key aggregation in order to verify messages signed by another network. When a validator joins a network, the P-Chain records the validator's BLS public key and NodeID, as well as a proof of possession of the validator's BLS private key to defend against [rogue public-key attacks](https://crypto.stanford.edu/~dabo/pubs/papers/BLSmultisig.html#mjx-eqn-eqaggsame).

ICM utilizes the validator set's weights and public keys to verify that an aggregate signature has sufficient weight signing the message from the source network.

BLS provides a way to aggregate signatures off chain into a single signature that can be efficiently verified on chain.

## ICM Serialization

Unsigned Message:

```
+---------------+----------+--------------------------+
|      codecID  :  uint16  |                 2 bytes  |
+---------------+----------+--------------------------+
|     networkID :  uint32  |                 4 bytes  |
+---------------+----------+--------------------------+
| sourceChainId : [32]byte |                32 bytes  |
+---------------+----------+--------------------------+
|       payload :   []byte |       4 + size(payload)  |
+---------------+----------+--------------------------+
                           |  42 + size(payload) bytes|
                           +--------------------------+
```

- `codecID` is the codec version used to serialize the payload and is hardcoded to `0x0000`
- `networkID` is the unique ID of an Avalanche Network (Mainnet/Testnet) and provides replay protection for BLS Signers across different Avalanche Networks
- `sourceChainID` is the hash of the transaction that created the blockchain on the Avalanche P-Chain. It serves as the unique identifier for the blockchain across the Avalanche Network so that each blockchain can only sign a message with its own id.
- `payload` provides an arbitrary byte array containing the contents of the message. VMs define their own message types to include in the `payload`

BitSetSignature:

```
+-----------+----------+---------------------------+
|   type_id :   uint32 |                   4 bytes |
+-----------+----------+---------------------------+
|   signers :   []byte |          4 + len(signers) |
+-----------+----------+---------------------------+
| signature : [96]byte |                  96 bytes |
+-----------+----------+---------------------------+
                       | 104 + size(signers) bytes |
                       +---------------------------+
```

- `typeID` is the ID of this signature type, which is `0x00000000`
- `signers` encodes a bitset of which validators' signatures are included (a bitset is a byte array where each bit indicates membership of the element at that index in the set)
- `signature` is an aggregated BLS Multi-Signature of the Unsigned Message

BitSetSignatures are verified within the context of a specific P-Chain height. At any given P-Chain height, the PlatformVM serves a canonically ordered validator set for the source network (validator set is ordered lexicographically by the BLS public key's byte representation). The `signers` bitset encodes which validator signatures were included. A value of `1` at index `i` in `signers` bitset indicates that a corresponding signature from the same validator at index `i` in the canonical validator set was included in the aggregate signature.

The bitset tells the verifier which BLS public keys should be aggregated to verify the interchain message.

Signed Message:

```
+------------------+------------------+-------------------------------------------------+
| unsigned_message :  UnsignedMessage |                          size(unsigned_message) |
+------------------+------------------+-------------------------------------------------+
|        signature :        Signature |                                 size(signature) |
+------------------+------------------+-------------------------------------------------+
                                      |  size(unsigned_message) + size(signature) bytes |
                                      +-------------------------------------------------+
```

## Sending an Avalanche Interchain Message

A blockchain on Avalanche sends an Avalanche Interchain Message by coming to agreement on the message that every validator should be willing to sign. As an example, the VM of a blockchain may define that once a block is accepted, the VM should be willing to sign a message including the block hash in the payload to attest to any other network that the block was accepted. The contents of the payload, how to aggregate the signature (VM-to-VM communication, off-chain relayer, etc.), is left to the VM.

Once the validator set of a blockchain is willing to sign an arbitrary message `M`, an aggregator performs the following process:

1. Gather signatures of the message `M` from `N` validators (where the `N` validators meet the required threshold of stake on the destination chain)
2. Aggregate the `N` signatures into a multi-signature
3. Look up the canonical validator set at the P-Chain height where the message will be verified
4. Encode the selection of the `N` validators included in the signature in a bitset
5. Construct the signed message from the aggregate signature, bitset, and original unsigned message

## Verifying / Receiving an Avalanche Interchain Message

Avalanche Interchain Messages are verified within the context of a specific P-Chain height included in the [ProposerVM](https://github.com/ava-labs/avalanchego/tree/master/vms/proposervm/README.md)'s header. The P-Chain height is provided as context to the underlying VM when verifying the underlying VM's blocks (implemented by the optional interface [WithVerifyContext](https://github.com/ava-labs/avalanchego/tree/master/snow/engine/snowman/block/block_context_vm.go)).

To verify the message, the underlying VM utilizes this `warp` package to perform the following steps:

1. Lookup the canonical validator set of the network sending the message at the P-Chain height
2. Filter the canonical validator set to only the validators claimed by the signature
3. Verify the weight of the included validators meets the required threshold defined by the receiving VM
4. Aggregate the public keys of the claimed validators into a single aggregate public key
5. Verify the aggregate signature of the unsigned message against the aggregate public key

Once a message is verified, it is left to the VM to define the semantics of delivering a verified message.

## Design Considerations

### Processing Historical Avalanche Interchain Messages

Verifying an Avalanche Interchain Message requires a lookup of validator sets at a specific P-Chain height. The P-Chain serves lookups maintaining validator set diffs that can be applied in-order to reconstruct the validator set of any network at any height.

As the P-Chain grows, the number of validator set diffs that needs to be applied in order to reconstruct the validator set needed to verify an Avalanche Interchain Messages increases over time.

Therefore, in order to support verifying historical Avalanche Interchain Messages, VMs should provide a mechanism to determine whether an Avalanche Interchain Message was treated as valid or invalid within a historical block.

When nodes bootstrap in the future, they bootstrap blocks that have already been marked as accepted by the network, so they can assume the block was verified by the validators of the network when it was first accepted.

Therefore, the new bootstrapping node can assume the block was valid to determine whether an Avalanche Interchain Message should be treated as valid/invalid within the execution of that block.

Two strategies to provide that mechanism are:

- Require interchain message validity for transaction inclusion. If the transaction is included, the interchain message must have passed verification.
- Include the results of interchain message verification in the block itself. Use the results to determine which messages passed verification.

# Integration with EVM (/docs/cross-chain/avalanche-warp-messaging/evm-integration)

---
title: "Integration with EVM"
description: "Avalanche Warp Messaging provides a basic primitive for signing and verifying messages between Avalanche L1s."
edit_url: https://github.com/ava-labs/coreth/edit/master/precompile/contracts/warp/README.md
---

# Integrating Avalanche Warp Messaging into the EVM

Avalanche Warp Messaging offers a basic primitive to enable Cross-L1 communication on the Avalanche Network.

It is intended to allow communication between arbitrary Custom Virtual Machines (including, but not limited to Subnet-EVM and Coreth).

## How does Avalanche Warp Messaging Work?

Avalanche Warp Messaging uses BLS Multi-Signatures with Public-Key Aggregation where every Avalanche validator registers a public key alongside its NodeID on the Avalanche P-Chain.

Every node tracking an Avalanche L1 has read access to the Avalanche P-Chain. This provides weighted sets of BLS Public Keys that correspond to the validator sets of each L1 on the Avalanche Network. Avalanche Warp Messaging provides a basic primitive for signing and verifying messages between L1s: the receiving network can verify whether an aggregation of signatures from a set of source L1 validators represents a threshold of stake large enough for the receiving network to process the message.

For more details on Avalanche Warp Messaging, see the AvalancheGo [Warp README](https://github.com/ava-labs/avalanchego/blob/master/vms/platformvm/warp/README.md).

### Flow of Sending / Receiving a Warp Message within the EVM

The Avalanche Warp Precompile enables this flow to send a message from blockchain A to blockchain B:

1. Call the Warp Precompile `sendWarpMessage` function with the arguments for the `UnsignedMessage`
2. Warp Precompile emits an event / log containing the `UnsignedMessage` specified by the caller of `sendWarpMessage`
3. Network accepts the block containing the `UnsignedMessage` in the log, so that validators are willing to sign the message
4. An off-chain relayer queries the validators for their signatures of the message and aggregates the signatures to create a `SignedMessage`
5. The off-chain relayer encodes the `SignedMessage` as the [predicate](#predicate-encoding) in the AccessList of a transaction to deliver on blockchain B
6. The transaction is delivered on blockchain B, the signature is verified prior to executing the block, and the message is accessible via the Warp Precompile's `getVerifiedWarpMessage` during the execution of that transaction

### Warp Precompile

The Warp Precompile is broken down into three functions defined in the Solidity interface file [here](https://github.com/ava-labs/coreth/blob/master/contracts/contracts/interfaces/IWarpMessenger.sol).

#### sendWarpMessage

`sendWarpMessage` is used to send a verifiable message. Calling this function results in sending a message with the following contents:

- `SourceChainID` - blockchainID of the sourceChain on the Avalanche P-Chain
- `SourceAddress` - `msg.sender` encoded as a 32 byte value that calls `sendWarpMessage`
- `Payload` - `payload` argument specified in the call to `sendWarpMessage` emitted as the unindexed data of the resulting log

Calling this function will issue a `SendWarpMessage` event from the Warp Precompile. Since the EVM limits the number of topics to 4 including the EventID, this message includes only the topics that would be expected to help filter messages emitted from the Warp Precompile the most.

Specifically, the `payload` is not emitted as a topic because each topic must be encoded as a hash. Therefore, we opt to take advantage of each possible topic to maximize the possible filtering for emitted Warp Messages.

Additionally, the `SourceChainID` is excluded because anyone parsing the chain can be expected to already know the blockchainID. Therefore, the `SendWarpMessage` event includes the indexable attributes:

- `sender`
- The `messageID` of the unsigned message (sha256 of the unsigned message)

The actual `message` is the entire [Avalanche Warp Unsigned Message](https://github.com/ava-labs/avalanchego/blob/master/vms/platformvm/warp/unsigned_message.go#L14) including an [AddressedCall](https://github.com/ava-labs/avalanchego/tree/master/vms/platformvm/warp/payload#addressedcall). The unsigned message is emitted as the unindexed data in the log.

#### getVerifiedMessage

`getVerifiedMessage` is used to read the contents of the delivered Avalanche Warp Message into the expected format.

It returns the message if present and a boolean indicating if a message is present.

To use this function, the transaction must include the signed Avalanche Warp Message encoded in the [predicate](#predicate-encoding) of the transaction. Prior to executing a block, the VM iterates through transactions and pre-verifies all predicates. If a transaction's predicate is invalid, then it is considered invalid to include in the block and dropped.

This leads to the following advantages:

1. The EVM execution does not need to verify the Warp Message at runtime (no signature verification or external calls to the P-Chain)
2. The EVM can deterministically re-execute and re-verify blocks assuming the predicate was verified by the network (e.g., in bootstrapping)

This pre-verification is performed using the ProposerVM Block header during [block verification](https://github.com/ava-labs/coreth/blob/master/plugin/evm/block.go#L355) & [block building](https://github.com/ava-labs/coreth/blob/master/miner/worker.go#L200).

#### getBlockchainID

`getBlockchainID` returns the blockchainID of the blockchain that the VM is running on.

This is different from the conventional Ethereum ChainID registered to [ChainList](https://chainlist.org/).

The `blockchainID` in Avalanche refers to the txID that created the blockchain on the Avalanche P-Chain ([docs](https://docs.avax.network/specs/platform-transaction-serialization#unsigned-create-chain-tx)).

### Predicate Encoding

Avalanche Warp Messages are encoded as a signed Avalanche [Warp Message](https://github.com/ava-labs/avalanchego/blob/master/vms/platformvm/warp/message.go) where the [UnsignedMessage](https://github.com/ava-labs/avalanchego/blob/master/vms/platformvm/warp/unsigned_message.go)'s payload includes an [AddressedPayload](https://github.com/ava-labs/avalanchego/blob/master/vms/platformvm/warp/payload/payload.go).

Since the predicate is encoded into the [Transaction Access List](https://eips.ethereum.org/EIPS/eip-2930), it is packed into 32 byte hashes intended to declare storage slots that should be pre-warmed into the cache prior to transaction execution.

Therefore, we use the [Predicate Utils](https://github.com/ava-labs/coreth/blob/master/predicate/Predicate.md) package to encode the actual byte slice of size N into the access list.

### Performance Optimization: C-Chain to Avalanche L1

For communication between the C-Chain and an L1, as well as broader interactions between the Primary Network and Avalanche L1s, we have implemented special handling for the C-Chain.

The Primary Network has a large validator set, which creates a unique challenge for Avalanche Warp messages. To reach the required stake threshold, numerous signatures would need to be collected and verifying messages from the Primary Network would be computationally costly. However, we have developed a more efficient solution.

When an Avalanche L1 receives a message from a blockchain on the Primary Network, we use the validator set of the receiving L1 instead of the entire network when validating the message. Note this is NOT possible if an L1 does not validate the Primary Network, in which case the Warp precompile must be configured with `requirePrimaryNetworkSigners`.

Sending messages from the C-Chain remains unchanged.
However, when L1 XYZ receives a message from the C-Chain, it changes the semantics to the following:

1. Read the `SourceChainID` of the signed message (C-Chain)
2. Look up the `SubnetID` that validates C-Chain: Primary Network
3. Look up the validator set of L1 XYZ (instead of the Primary Network) and the registered BLS Public Keys of L1 XYZ at the P-Chain height specified by the ProposerVM header
4. Continue Warp Message verification using the validator set of L1 XYZ instead of the Primary Network

This means that C-Chain to L1 communication only requires a threshold of stake on the receiving L1 to sign the message instead of a threshold of stake for the entire Primary Network.

This assumes that the security of L1 XYZ already depends on the validators of L1 XYZ to behave virtuously. Therefore, requiring a threshold of stake from the receiving L1's validator set instead of the whole Primary Network does not meaningfully change security of the receiving L1.

Note: this special case is ONLY applied during Warp Message verification. The message sent by the Primary Network will still contain the Avalanche C-Chain's blockchainID as the sourceChainID and signatures will be served by querying the C-Chain directly.

## Design Considerations

### Re-Processing Historical Blocks

Avalanche Warp Messaging depends on the Avalanche P-Chain state at the P-Chain height specified by the ProposerVM block header.

Verifying a message requires looking up the validator set of the source L1 on the P-Chain. To support this, Avalanche Warp Messaging uses the ProposerVM header, which includes the P-Chain height it was issued at as the canonical point to lookup the source L1's validator set.

This means verifying the Warp Message and therefore the state transition on a block depends on state that is external to the blockchain itself: the P-Chain.

The Avalanche P-Chain tracks only its current state and reverse diff layers (reversing the changes from past blocks) in order to re-calculate the validator set at a historical height. This means calculating a very old validator set that is used to verify a Warp Message in an old block may become prohibitively expensive.

Therefore, we need a heuristic to ensure that the network can correctly re-process old blocks (note: re-processing old blocks is a requirement to perform bootstrapping and is used in some VMs to serve or verify historical data).

As a result, we require that the block itself provides a deterministic hint which determines which Avalanche Warp Messages were considered valid/invalid during the block's execution. This ensures that we can always re-process blocks and use the hint to decide whether an Avalanche Warp Message should be treated as valid/invalid even after the P-Chain state that was used at the original execution time may no longer support fast lookups.

To provide that hint, we've explored two designs:

1. Include a predicate in the transaction to ensure any referenced message is valid
2. Append the results of checking whether a Warp Message is valid/invalid to the block data itself

The current implementation uses option (1).

The original reason for this was that the notion of predicates for precompiles was designed with Shared Memory in mind. In the case of shared memory, there is no canonical "P-Chain height" in the block which determines whether or not Avalanche Warp Messages are valid.

Instead, the VM interprets a shared memory import operation as valid as soon as the UTXO is available in shared memory. This means that if it were up to the block producer to staple the valid/invalid results of whether or not an attempted atomic operation should be treated as valid, a byzantine block producer could arbitrarily report that such atomic operations were invalid and cause a griefing attack to burn the gas of users that attempted to perform an import.

Therefore, a transaction specified predicate is required to implement the shared memory precompile to prevent such a griefing attack.

In contrast, Avalanche Warp Messages are validated within the context of an exact P-Chain height. Therefore, if a block producer attempted to lie about the validity of such a message, the network would interpret that block as invalid.

### Guarantees Offered by Warp Precompile vs. Built on Top

#### Guarantees Offered by Warp Precompile

The Warp Precompile was designed with the intention of minimizing the trusted computing base for the VM as much as possible. Therefore, it makes several tradeoffs which encourage users to use protocols built ON TOP of the Warp Precompile itself as opposed to directly using the Warp Precompile.

The Warp Precompile itself provides ONLY the following ability:

- Emit a verifiable message from (Address A, Blockchain A) to (Address B, Blockchain B) that can be verified by the destination chain

#### Explicitly Not Provided / Built on Top

The Warp Precompile itself does not provide any guarantees of:

- Eventual message delivery (may require re-send on blockchain A and additional assumptions about off-chain relayers and chain progress)
- Ordering of messages (requires ordering provided a layer above)
- Replay protection (requires replay protection provided a layer above)

# What is ICM? (/docs/cross-chain/avalanche-warp-messaging/overview)

---
title: What is ICM?
description: Learn about Avalanche Interchain Messaging, a protocol for cross-chain communication.
---

Avalanche Interchain Messaging (ICM) enables native cross-Avalanche L1 communication and allows [Virtual Machine (VM)](/docs/quick-start/virtual-machines) developers to implement arbitrary communication protocols between any two Avalanche L1s.

## Use Cases

Use cases for ICM may include but is not limited to:

- Oracle Networks: Connecting an Avalanche L1 to an oracle network is a costly process. ICM makes it easy for oracle networks to broadcast their data from their origin chain to other Avalanche L1s.
- Token transfers between Avalanche L1s
- State Sharding between multiple Avalanche L1s

Elements of Cross-Avalanche L1 Communication[​](#elements-of-cross-avalanche-l1-communication "Direct link to heading")
-----------------------------------------------------------------------------------------------------------

The communication consists of the following four steps:

![image showing four steps of cross-Avalanche L1 communication: Signing, aggregation, Delivery and Verification](/images/warp1.png)

### Signing Messages on the Origin Avalanche L1[​](#signing-messages-on-the-origin-avalanche-l1 "Direct link to heading")

ICM is a low-level messaging protocol. Any type of data encoded in an array of bytes can be included in the message sent to another Avalanche L1. ICM uses the [BLS signature scheme](https://crypto.stanford.edu/~dabo/pubs/papers/BLSmultisig.html), which allows message recipients to verify the authenticity of these messages. Therefore, every validator on the Avalanche network holds a BLS key pair, consisting of a private key for signing messages and a public key that others can use to verify the signature.

### Signature Aggregation on the Origin Avalanche L1[​](#signature-aggregation-on-the-origin-avalanche-l1 "Direct link to heading")

If the validator set of an Avalanche L1 is very large, this would result in the Avalanche L1's validators sending many signatures between them. One of the powerful features of BLS is the ability to aggregate many signatures of different signers in a single multi-signature. Therefore, validators of one Avalanche L1 can now individually sign a message and these signatures are then aggregated into a short multi-signature that can be quickly verified.

### Delivery of Messages to the Destination Avalanche L1[​](#delivery-of-messages-to-the-destination-avalanche-l1 "Direct link to heading")

The messages do not pass through a central protocol or trusted entity, and there is no record of messages sent between Avalanche L1s on the primary network. This avoids a bottleneck in Avalanche L1-to-Avalanche L1 communication, and non-public Avalanche L1s can communicate privately.

It is up to the Avalanche L1s and their users to determine how they want to transport data from the validators of the origin Avalanche L1 to the validators of the destination Avalanche L1 and what guarantees they want to provide for the transport.

### Verification of Messages in the Destination Avalanche L1[​](#verification-of-messages-in-the-destination-avalanche-l1 "Direct link to heading")

When an Avalanche L1 wants to process another Avalanche L1's message, it will look up both BLS Public Keys and stake of the origin Avalanche L1. The authenticity of the message can be verified using these public keys and the signature.

The combined weight of the validators that must be part of the BLS multi-signature to be considered valid can be set according to the individual requirements of each Avalanche L1-to-Avalanche L1 communication. Avalanche L1 A may accept messages from Avalanche L1 B that are signed by at least 70% of stake. Messages from Avalanche L1 C are only accepted if they have been signed by validators that account for 90% of the stake.

Since both the public keys and stake weights of all validators are recorded on the primary network's P-chain, they are readily accessible to any virtual machine run by the validators. Therefore, the Avalanche L1s do not need to communicate with each other about changes in their respective sets of validators, but can simply rely on the latest information on the P-Chain. Therefore, ICM introduces no additional trust assumption other than that the validators of the origin Avalanche L1 are participating honestly.

Reference Implementation[​](#reference-implementation "Direct link to heading")
-------------------------------------------------------------------------------

A Proof-of-Concept VM called [XSVM](https://github.com/ava-labs/xsvm) was created to demonstrate the power of ICM. XSVM enables simple ICM transfers between any two Avalanche L1s if run out-of-the-box.


# Run a Relayer (/docs/cross-chain/avalanche-warp-messaging/run-relayer)

---
title: "Run a Relayer"
description: "Reference relayer implementation for cross-chain Avalanche Interchain Message delivery."
edit_url: https://github.com/ava-labs/icm-services/edit/main/relayer/README.md
---

# ICM Relayer

Reference relayer implementation for cross-chain Avalanche Warp Message delivery.

ICM Relayer listens for Warp message events on a set of source blockchains, and constructs transactions to relay the Warp message to the intended destination blockchain. The relayer does so by querying the source blockchain validator nodes for their BLS signatures on the Warp message, combining the individual BLS signatures into a single aggregate BLS signature, and packaging the aggregate BLS signature into a transaction according to the destination blockchain VM Warp message verification rules.

## Installation

### Dev Container & Codespace

To get started easily, we provide a Dev Container specification, that can be used using GitHub Codespace or locally using Docker and VS Code. [Dev Containers](https://code.visualstudio.com/docs/devcontainers/containers) are a concept that utilizes containerization to create consistent and isolated development environment. You can run them directly on Github by clicking **Code**, switching to the **Codespaces** tab and clicking **Create codespace on main**. Alternatively, you can run them locally with the extensions for [VS Code](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) or other code editors.

### Download Prebuilt Binaries

Prebuilt binaries are available for download from the [releases page](https://github.com/ava-labs/icm-services/releases).

The following commands demonstrate how to download and install the v0.2.13 release of the relayer on MacOS. The exact commands will vary by platform.

```bash
# Download the release tarball and checksums
curl -w '%{http_code}' -sL -o ~/Downloads/icm-relayer_0.2.13_darwin_arm64.tar.gz https://github.com/ava-labs/icm-services/releases/download/v0.2.13/icm-relayer_0.2.13_darwin_arm64.tar.gz
curl -w '%{http_code}' -sL -o ~/Downloads/icm-relayer_0.2.13_checksums.txt https://github.com/ava-labs/icm-services/releases/download/v0.2.13/icm-relayer_0.2.13_checksums.txt

# (Optional) Verify the checksums
cd ~/Downloads
# Confirm that the following two commands output the same checksum
grep "icm-relayer_0.2.13_darwin_arm64.tar.gz" "icm-relayer_0.2.13_checksums.txt" 2>/dev/null
shasum -a 256 "icm-relayer_0.2.13_darwin_arm64.tar.gz" 2>/dev/null

# Extract the tarball and install the relayer binary
tar -xzf icm-relayer_0.2.13_darwin_arm64.tar.gz
sudo install icm-relayer /usr/local/bin
```

_Note:_ If downloading the binaries through a browser on MacOS, the browser may mark the binary as quarantined since it has not been verified through the App Store. To remove the quarantine, run the following command:

```bash
xattr -d com.apple.quarantine /usr/local/bin/icm-relayer
```

### Download Docker Image

The published Docker image can be pulled from `avaplatform/icm-relayer:latest` on dockerhub.

### Build from Source

See the [Building](#building) section for instructions on how to build the relayer from source.

## Requirements

[buf](https://github.com/bufbuild/buf/) is required to rebuild protobuf definitions if changes are made to any `.proto` files. See [Generate Protobuf Files](#generate-protobuf-files) for more information.

### System Requirements

- Ubuntu 22.04 or later
  - Tested on x86_64/amd64 architecture.
- MacOS 14.3 or later
  - Tested on arm64 architecture (Apple silicon).

### API Requirements

- ICM Relayer requires access to Avalanche API nodes for the P-Chain as well as any connected Subnets. The API nodes must have the following methods enabled:
  - Each Subnet API node must have enabled:
    - eth API (RPC and WS)
  - The P-Chain API node must have enabled:
    - platform.getHeight
    - platform.validatedBy
    - platform.getValidatorsAt OR platform.getCurrentValidators
  - The Info API node must have enabled:
    - info.peers
    - info.getNetworkID
  - If the Info API node is also a Subnet validator, it must have enabled:
    - info.getNodeID
    - info.getNodeIP

The Fuji and Mainnet [public API nodes](https://docs.avax.network/tooling/rpc-providers) provided by Avalanche have these methods enabled, and are suitable for use with the relayer.

### Peer-to-Peer Connections

- By default, the ICM relayer implementation gathers BLS signatures from the validators of the source Subnet via peer-to-peer `AppRequest` messages. Validator nodes need to be configured to accept incoming peer connections. Otherwise, the relayer will fail to gather Warp message signatures. For example, networking rules may need to be adjusted to allow traffic on the default AvalancheGo P2P port (9651), or the public IP may need to be manually set in the [node configuration](https://docs.avax.network/nodes/configure/avalanchego-config-flags#public-ip).
- **DEPRECATED** If configured to use the Warp API (see `warp-api-endpoint` in [Configuration](#configuration)) then aggregate signatures are fetched via a single RPC request, rather than `AppRequests` to individual validators. Note that the Warp API is disabled on the public API.

### Private Key Management

- Each configured destination blockchain requires a private key to sign transactions. This key can be provided as a hex-encoded string in the configuration (see `account-private-key` in [Configuration](#configuration)) or environment variable, or stored in KMS and used to sign transactions remotely (see `kms-key-id` and `kms-aws-region` in [Configuration](#configuration)).
- **Each private key used by the relayer should not be used to sign transactions outside of the relayer**, as this may cause the relayer to fail to sign transactions due to nonce mismatches.

## Usage

### Options

The relayer binary accepts the following command line options. Other configuration options are not supported via the command line and must be provided via the configuration JSON file or environment variable.

```bash
icm-relayer --config-file path-to-config                Specifies the relayer config file and begin relaying messages.
icm-relayer --version                                   Display icm-relayer version and exit.
icm-relayer --help                                      Display icm-relayer usage and exit.
```

### Initialize the repository

- Get all submodules: `git submodule update --init --recursive`

### Building

Before building, be sure to install Go, which is required even if you're just building the Docker image.

Build the relayer by running the script:

```bash
./scripts/build.sh
```

Build a Docker image by running the script:

```bash
./scripts/build_local_image.sh
```

### Configuration

The relayer is configured via a JSON file, the path to which is passed in via the `--config-file` command line argument. Top level configuration options are also able to be set via environment variable. To get the environment variable corresponding to a key, upper case the key and change the delimiter from "-" to "_". For example, `LOG_LEVEL` sets the `"log-level"` JSON key. The following configuration options are available:

`"log-level": "verbo" | "debug" | "info" | "warn" | "error" | "fatal" | "panic"`

- The log level for the relayer. Defaults to `info`.

`"p-chain-api": APIConfig`

- The configuration for the Avalanche P-Chain API node. The `PChainAPI` object has the following configuration:

  `"base-url": string`

  - The URL of the Avalanche P-Chain API node to which the relayer will connect. This API node needs to have the following methods enabled:
    - platform.getHeight
    - platform.validatedBy
    - platform.getValidatorsAt OR platform.getCurrentValidators

  `"query-parameters": map[string]string`

  - Additional query parameters to include in the API requests.

  `"http-headers": map[string]string`

  - Additional HTTP headers to include in the API requests.

`"info-api": APIConfig`

- The configuration for the Avalanche Info API node. The `InfoAPI` object has the following configuration:

  `"base-url": string`

  - The URL of the Avalanche Info API node to which the relayer will connect. This API node needs to have the following methods enabled:

    - info.peers
    - info.getNetworkID

  - Additionally, if the Info API node is also a validator, it must have enabled:
    - info.getNodeID
    - info.getNodeIP

  `"query-parameters": map[string]string`

  - Additional query parameters to include in the API requests.

  `"http-headers": map[string]string`

  - Additional HTTP headers to include in the API requests.

`"storage-location": string`

- The path to the directory in which the relayer will store its state. Defaults to `./icm-relayer-storage`.

`"redis-url": string`

- The URL of the Redis server to use to manage state. This URL should specify the user, password, host, port, DB index, and protocol version. For example, `"redis://user:password@localhost:6379/0?protocol=3"`. Overrides `storage-location` if provided.

`"process-missed-blocks": boolean`

- Whether or not to process missed blocks after restarting. Defaults to `true`. If set to false, the relayer will start processing blocks from the chain head.

`"api-port"`: unsigned integer

- The port on which the relayer will listen for API requests. Defaults to `8080`.

`"metrics-port"`: unsigned integer

- The port on which the relayer will expose Prometheus metrics. Defaults to `9090`.

`"db-write-interval-seconds": unsigned integer`

- The interval at which the relayer will write to the database. Defaults to `10`.

`"tls-cert-path": string`

- The path to a TLS cert file. Should only be set if a static NodeID is required for connecting to private networks.

`"tls-key-path": string`

- The path to a TLS key file. Should only be set if a static NodeID is required for connecting to private networks.

`"initial-connection-timeout-seconds": unsigned integer`

- The maximum number of seconds to wait during start up to connect to sufficient stake weight of each supported chain.

`"max-concurrent-messages": unsigned integer`

- The maximum number of messages the application will attempt to process concurrently. Processing messages involves making potentially multiple RPC requests, and issuing too many requests at once may cause failures.

`"manual-warp-messages": []ManualWarpMessage`

- The list of Warp messages to relay on startup, independent of the catch-up mechanism or normal operation. Each `ManualWarpMessage` has the following configuration:

  `"unsigned-message-bytes": string`

  - The hex-encoded bytes of the unsigned Warp message to relay.

  `"source-blockchain-id": string`

  - cb58-encoded or "0x" prefixed hex-encoded blockchain ID of the source blockchain.

  `"destination-blockchain-id": string`

  - cb58-encoded or "0x" prefixed hex-encoded blockchain ID of the destination blockchain.

  `"source-address": string`

  - The address of the source account that sent the Warp message.

  `"destination-address": string`

  - The address of the destination account that will receive the Warp message.

`"source-blockchains": []SourceBlockchains`

- The list of source blockchains to support. Each `SourceBlockchain` has the following configuration:

  `"subnet-id": string`

  - cb58-encoded or "0x" prefixed hex-encoded Subnet ID.

  `"blockchain-id": string`

  - cb58-encoded or "0x" prefixed hex-encoded blockchain ID.

  `"vm": string`

  - The VM type of the source blockchain.

  `"rpc-endpoint": APIConfig`

  - The RPC endpoint configuration of the source blockchain's API node. An `APIConfig` has the following fields:

    `"base-url": string`

    - The URL that will be queried. The API node is expected to have all standard ETH endpoints enabled.

    `"query-params": map[string]string`

    - A map of query parameters to values that will be added to the base URL

    `"http-headers": map[string]string`

    - A map of HTTP headers to include in the requests to this API

  `"ws-endpoint": APIConfig`

  - The WebSocket endpoint configuration of the source blockchain's API node. An `APIConfig` has the following fields:

    `"base-url": string`

    - The URL that will be queried. The API node is expected to accept eth_subscribe connections.

    `"query-params": map[string]string`

    - A map of query parameters to values that will be added to the base URL

    `"http-headers": map[string]string`

    - A map of HTTP headers to include in the requests to this API

  `"message-contracts": map[string]MessageProtocolConfig`

  - Map of contract addresses to the config options of the protocol at that address. Each `MessageProtocolConfig` consists of a unique `message-format` name, and the raw JSON `settings`.

  `"supported-destinations": []SupportedDestination`

  - List of destinations that the source blockchain supports. Each `SupportedDestination` consists of a cb58-encoded destination blockchain ID (`"blockchain-id"`), and a list of hex-encoded addresses (`"addresses"`) on that destination blockchain that the relayer supports delivering Warp messages to. The destination address is defined by the message protocol. For example, it could be the address called from the message protocol contract. If no supported addresses are provided, all addresses are allowed on that blockchain. If `supported-destinations` is empty, then all destination blockchains (and therefore all addresses on those destination blockchains) are supported.

  `"process-historical-blocks-from-height": unsigned integer`

  - The block height at which to back-process transactions from the source blockchain. If the database already contains a later block height for the source blockchain, then that will be used instead. Must be non-zero. Will only be used if `process-missed-blocks` is set to `true`.

  `"allowed-origin-sender-addresses": []string`

  - List of addresses on this source blockchain to relay Warp messages from. The sending address is defined by the message protocol. For example, it could be defined as the EOA that initiates the transaction, or the address that calls the message protocol contract. If empty, then all addresses are allowed.

  `"DEPRECATED warp-api-endpoint": APIConfig`

  - The RPC endpoint configuration for the Warp API, which is used to fetch Warp aggregate signatures. If omitted, then signatures are fetched via AppRequest instead.  An `APIConfig` has the following fields:

    `"base-url": string`

    - The URL that will be queried. The API node is expected to have `warp.getMessageAggregateSignature` enabled.

    `"query-params": map[string]string`

    - A map of query parameters to values that will be added to the base URL

    `"http-headers": map[string]string`

    - A map of HTTP headers to include in the requests to this API

`"destination-blockchains": []DestinationBlockchains`

- The list of destination blockchains to support. Each `DestinationBlockchain` has the following configuration:

  `"subnet-id": string`

  - cb58-encoded or "0x" prefixed hex-encoded Subnet ID.

  `"blockchain-id": string`

  - cb58-encoded or "0x" prefixed hex-encoded blockchain ID.

  `"vm": string`

  - The VM type of the source blockchain.

  `"rpc-endpoint": APIConfig`

  - The RPC endpoint configuration of the destination blockchains's API node. An `APIConfig` has the following fields:

    `"base-url": string`

    - The URL that will be queried

    `"query-params": map[string]string`

    - A map of query parameters to values that will be added to the base URL

    `"http-headers": map[string]string`

    - A map of HTTP headers to include in the requests to this API

  `"account-private-key": string`

  - The hex-encoded private key to use for signing transactions on the destination blockchain. May be provided by the environment variable `ACCOUNT_PRIVATE_KEY`. Each `destination-subnet` may use a separate private key by appending the cb58 encoded blockchain ID to the private key environment variable name, for example `ACCOUNT_PRIVATE_KEY_11111111111111111111111111111111LpoYY`
  - Please note that the private key should be exclusive to the relayer, see [Private Key Management](#private-key-management).

  `"kms-key-id": string`

  - The ID of the KMS key to use for signing transactions on the destination blockchain. If `kms-key-id` is provided, then `kms-aws-region` is required.
  - Please note that the private key in KMS should be exclusive to the relayer, see [Private Key Management](#private-key-management).

  `"kms-aws-region": string`

  - The AWS region in which the KMS key is located. Required if `kms-key-id` is provided.

  `"account-private-keys-list": []string`

  - A list of hex-encoded private keys for signing transactions on the destination blockchain. May also be provided as a space-delimited list by the environment variable `ACCOUNT_PRIVATE_KEYS_LIST`. Each `destination-subnet` may use a separate list of private keys by appending the cb58 encoded blockchain ID to the private keys environment variable name, for example `ACCOUNT_PRIVATE_KEYS_LIST_11111111111111111111111111111111LpoYY`
  - Please note that all private keys should be exclusive to the relayer, see [Private Key Management](#private-key-management).

  `"kms-keys": []KMSKey`

  - A list of KMS Keys that may be used for signing transactions on the destination blockchain. A `KMSKey` has the following fields:

    `"key-id": string`

    - The ID of the KMS key to use for signing transactions on the destination blockchain.

    `"aws-region": string`

    - The AWS region in which the KMS key is located.

  `"block-gas-limit": unsigned integer`

  - The maximum amount of gas that can be used in a single block on this blockchain. The relayer will not attempt to deliver messages that require more gas than this limit to the given chain. Defaults to 12,000,000 if not set for a given chain.

  `"max-base-fee": unsigned integer`

  - The maximum base fee gas price (in WEI) the relayer is willing to pay on this blockchain. If zero or left unset, the relayer will use a multiple of the current base fee estimation, and not have an explicit maximum.

  `"suggested-priority-fee-buffer": unsigned integer`

  - The fee per gas (in WEI) that will be added to the priority fee rate on top of the suggested priority fee fetched via RPC. A higher suggested priority fee buffer will make transaction inclusion more likely in cases where a chain's capacity is being exhausted, but also results in higher effective gas prices for transactions when potentially not necessary. The maximum priority fee per gas is also capped by `max-priority-fee-per-gas`, as described below.

  `"max-priority-fee-per-gas": unsigned integer`

  - The maximum priority fee per gas (in WEI) that the relayer is willing to pay to incentivize transactions being included on this blockchain. The relayer will use the current estimation of the required gas tip cap for this blockchain plus the `suggested-priority-fee-buffer`, up to a maximum of this configured value. Defaults to 2.5 GWEI.

  `"tx-inclusion-timeout-seconds": unisgned integer`

  - The time in seconds to wait for a sent transaction to be included in a block when verifying transaction receipts before erroring out. If omitted, defaults to 30 seconds.

`"decider-url": string`

- The URL of a service implementing the gRPC service defined by `proto/decider`, which will be queried for each message to determine whether that message should be relayed.

## Architecture

### Components

The relayer consists of the following components:

- At the global level:
  - P2P app network: issues signature `AppRequests`
  - P-Chain client: gets the validators for a Subnet
  - Relayer database: stores latest processed block for each Application Relayer
    - Currently supports Redis and local JSON file storage
- Per Source Blockchain
  - Subscriber: listens for logs pertaining to cross-chain message transactions
  - Source RPC client: queries for missed blocks on startup
- Per Destination Blockchain
  - Destination RPC client: broadcasts transactions to the destination
- Application Relayers
  - Relay messages from a specific source blockchain and source address to a specific destination blockchain and destination address

### Data Flow

<figure>
  <img src="https://raw.githubusercontent.com/ava-labs/icm-services/main/resources/relayer-diagram.png" />>
  <figcaption>Figure 1: Relayer Data Flow</figcaption>
</figure>

### Processing Missed Blocks

On startup, the relayer will process any blocks that it missed while offline if `process-missed-blocks` is set to `true` in the configuration. For each configured `source-blockchain`, the starting block height is set as the _minimum_ block height that is stored in the relayer's database across keys that pertain to that blockchain. These keys correspond to distinct sending addresses (as specified in `source-blockchain.allowed-origin-sender-addresses`), meaning that on startup, the relayer will begin processing from the _minimum_ block height across all configured sending addresses for each `source-blockchain`. Note that an empty `source-blockchain.allowed-origin-sender-addresses` list is treated as its own distinct key. If no keys are found, then the relayer begins processing from the current chain tip.

Once the starting block height is calculated, all blocks between it and the current tip of the `source-blockchain` are processed according to the _current_ configuration rules. 

_Note:_ Given these semantics for computing the starting block height, it's possible for blocks that have previously been ignored under different configuration options to be relayed on a subsequent run. For example, consider the following scenario consisting of three subsequent runs (see Figure 2 below):

- **Run 1**: Suppose that on Blockchain A we set `allowed-origin-sender-addresses=[0x1234]`, meaning that the relayer should _ignore_ messages sent by any other address. The relayer processes through block `100`, and that height is marked as processed for `0x1234`'s key.

- **Run 2**: The relayer is then restarted with `allowed-origin-sender-addresses=[0xabcd]`, replacing `0x1234`. A message is sent from address `0x1234` at block height `200`. The relayer will decide to ignore this message, and will mark block `200` as processed for `0xabcd`'s key.

- **Run 3**: The relayer is then restarted again with the original configuration of `allowed-origin-sender-addresses=[0x1234]`. The relayer will calculate the starting block height as `100`, and process blocks `100` through the current chain tip, reprocessing block `200` along the way. Instead of ignoring the message in this block, however, the relayer will relay it to the destination.

<figure>
  <img src="https://raw.githubusercontent.com/ava-labs/icm-services/main/resources/catch-up-example.png" />>
  <figcaption>Figure 2: Processing Missed Blocks Example</figcaption>
</figure>

### API

#### `/relay`
- Used to manually relay a Warp message. The body of the request must contain the following JSON:

```json
{
 "blockchain-id": "<cb58-encoded or '0x' prefixed hex-encoded of blockchain ID>",
 "message-id": "<cb58-encoded or '0x' prefixed hex-encoded of Warp message ID>",
 "block-num": "<Block number that the message was sent in>"
}
```

- If successful, the endpoint will return the following JSON:

```json
{
 "transaction-hash": "<Transaction hash that includes the delivered warp message>"
}
```

#### `/relay/message`

- Used to manually relay a warp message. The body of the request must contain the following JSON:

```json
{
 "unsigned-message-bytes": "<Hex encoded byte array containing the unsigned warp message>",
 "source-address": "<Hex encoding of address that sent the warp message>"
}
```

- If successful, the endpoint will return the following JSON:

```json
{
 "transaction-hash": "<Transaction hash that includes the delivered Warp message>",
}
```

#### `/health`

- Takes no arguments. Returns a `200` status code if all Application Relayers are healthy. Returns a `503` status if any of the Application Relayers have experienced an unrecoverable error. Here is an example return body:

```json
{
  "status": "down",
  "details": {
    "relayers-all": {
      "status": "down",
      "timestamp": "2024-06-01T05:06:07.685522Z",
      "error": "<List of cb-58 encoded IDs for unhealthy relayers>"
    }
  }
}
```

## Testing

### Unit Tests

Unit tests can be ran locally by running the command in the root of the project:

```bash
./scripts/test.sh
```

If your temporary directory is not writable, the unit tests may fail with messages like `fork/exec /tmp/go-build2296620589/b247/config.test: permission denied`. To fix this, set the `TMPDIR` environment variable to something writable, for example `export TMPDIR=~/tmp`.

### E2E Tests

To run the E2E tests locally, you'll need to install Gingko following the instructions [here](https://onsi.github.io/ginkgo/#installing-ginkgo). Run the tests using the dedicated script:

```bash
./scripts/e2e_test.sh
```

To run a specific E2E test, specify the environment variable `GINKGO_FOCUS`, which will then look for [test descriptions](https://github.com/ava-labs/icm-services/blob/main/relayer/tests/e2e_test.go#L68) that match the provided input. For example, to run the `Basic Relay` test:

```bash
GINKGO_FOCUS="Basic" ./scripts/e2e_test.sh
```

The E2E tests use the `TeleporterMessenger` contract deployment transaction specified in the following files:

- `tests/utils/UniversalTeleporterDeployerAddress.txt`
- `tests/utils/UniversalTeleporterDeployerTransaction.txt`
- `tests/utils/UniversalTeleporterMessagerContractAddress.txt`
  To update the version of Teleporter used by the E2E tests, update these values with the latest contract deployment information. For more information on how to deploy the Teleporter contract, see the [Teleporter documentation](https://github.com/ava-labs/icm-contracts/tree/main/utils/contract-deployment).

### Generate Mocks

[Gomock](https://pkg.go.dev/go.uber.org/mock/gomock) is used to generate mocks for testing. To generate mocks, run the following command at the root of the project:

```bash
go generate ./...
```

### Generate Protobuf Files

[buf](https://github.com/bufbuild/buf/) is used to generate protobuf definitions for communication with the [Decider service](https://github.com/ava-labs/icm-services/blob/main/proto/decider/decider.proto). If you change any of the protobuf definitions you will have to regenerate the `.go` files. To generate these files, run the following command at the root of the project:

```bash
./scripts/protobuf_codegen.sh
```

### Generate Abi Bindings

[subnet-evm](https://github.com/ava-labs/subnet-evm/tree/6e67777132dd7d0d556e1e34d68ad8e27b22ebef/cmd/abigen) is used to generate abi binding `.go` files for solidity contracts. If you change any of the smart contracts, you will have to update the abi bindings. To generate these files, run the following command at the root of the project:

```bash
./scripts/abi_bindings.sh
```

# Avalanche Interchain Token Transfer (ICTT) (/docs/cross-chain/interchain-token-transfer/overview)

---
title: "Avalanche Interchain Token Transfer (ICTT)"
description: "This page describes the Avalanche Interchain Token Transfer (ICTT)"
edit_url: https://github.com/ava-labs/icm-contracts/edit/main/contracts/ictt/README.md
---

# Avalanche Interchain Token Transfer (ICTT)

## Overview

Avalanche Interchain Token Transfer (ICTT) is an application that allows users to transfer tokens between L1s. The implementation is a set of smart contracts that are deployed across multiple L1s, and leverages [ICM](https://github.com/ava-labs/icm-contracts) for cross-chain communication.

Each token transferrer instance consists of one "home" contract and at least one but possibly many "remote" contracts. Each home contract instance manages one asset to be transferred out to `TokenRemote` instances. The home contract lives on the L1 where the asset to be transferred exists. A transfer consists of locking the asset as collateral on the home L1 and minting a representation of the asset on the remote L1. The remote contracts, each of which has a single specified home contract, live on other L1s that want to import the asset transferred by their specified home. The token transferrers are designed to be permissionless: anyone can register compatible `TokenRemote` instances to allow for transferring tokens from the `TokenHome` instance to that new `TokenRemote` instance. The home contract keeps track of token balances transferred to each `TokenRemote` instance, and handles returning the original tokens back to the user when assets are transferred back to the `TokenHome` instance. `TokenRemote` instances are registered with their home contract via an ICM message upon creation.

Home contract instances specify the asset to be transferred as either an ERC20 token or the native token, and they allow for transferring the token to any registered `TokenRemote` instances. The token representation on the remote chain can also either be an ERC20 or native token, allowing users to have any combination of ERC20 and native tokens between home and remote chains:

- `ERC20` -> `ERC20`
- `ERC20` -> `Native`
- `Native` -> `ERC20`
- `Native` -> `Native`

The remote tokens are designed to have compatibility with the token transferrer on the home chain by default, and they allow custom logic to be implemented in addition. For example, developers can inherit and extend the `ERC20TokenRemote` contract to add additional functionality, such as a custom minting, burning, or transfer logic.

The token transferrer also supports "multi-hop" transfers, where tokens can be transferred between remote chains. To illustrate, consider two remotes _R<sub>a</sub>_ and _R<sub>b</sub>_ that are both connected to the same home _H_. A multi-hop transfer from _R<sub>a</sub>_ to _R<sub>b</sub>_ first gets routed from _R<sub>a</sub>_ to _H_, where remote balances are updated, and then _H_ automatically routes the transfer on to _R<sub>b</sub>_.

In addition to supporting basic token transfers, the token transferrer contracts offer a `sendAndCall` interface for transferring tokens and using them in a smart contract interaction all within a single ICM message. If the call to the recipient smart contract fails, the transferred tokens are sent to a fallback recipient address on the destination chain of the transfer. The `sendAndCall` interface enables the direct use of transferred tokens in dApps on other chains, such as performing swaps, using the tokens to pay for fees when invoking services, etc.

## Upgradability

The token transferrer contracts implement both upgradeable and non-upgradeable versions. The non-upgradeable versions are extensions of their respective upgradeable token transferrer contract, and has a `constructor` that calls the `initialize` function of the upgradeable version. The upgradeable contracts are ERC7201 compliant, and use namespace storage to store the state of the contract.

## `ITokenTransferrer`

Interface that defines the events token transfer contract implementations must emit. Also defines the message types and formats of messages between all implementations.

## `IERC20TokenTransferrer` and `INativeTokenTransferrer`

Interfaces that define the external functions for interacting with token transfer contract implementations of each type. ERC20 and native token transferrer interfaces vary from each other in that the native token transferrer functions are `payable` and do not take an explicit amount parameter (it is implied by `msg.value`), while the ERC20 token transferrer functions are not `payable` and require the explicit amount parameter. Otherwise, they include the same functions.

## `TokenHome`

An abstract implementation of `ITokenTransferrer` for a token transfer contract on the "home" chain with the asset to be transferred. Each `TokenHome` instance supports transferring exactly one token type (ERC20 or native) on its chain to arbitrarily many "remote" instances on other chains. It handles locking tokens to be sent to `TokenRemote` instances, as well as receiving token transfer messages to either redeem tokens it holds as collateral (i.e. unlock), or route them to other `TokenRemote` instances (i.e. "multi-hop"). In the case of a multi-hop transfer, the `TokenHome` already has the collateral locked from when the tokens were originally transferred to the first `TokenRemote` instance, so it simply updates the accounting of the transferred balances to each respective `TokenRemote` instance. Remote contracts must first be registered with a `TokenHome` instance before the home contract will allow for sending tokens to them. This is to prevent tokens from being transferred to invalid remote addresses. Anyone is able to deploy and register remote contracts, which may have been modified from this repository. It is the responsibility of the users of the home contract to independently evaluate each remote for its security and correctness.

## `ERC20TokenHome`

A concrete implementation of `TokenHome` and `IERC20TokenTransferrer` that handles the locking and releasing of an ERC20 token.

## `NativeTokenHome`

A concrete implementation of `TokenHome` and `INativeTokenTransferrer` that handles the locking and release of the native EVM asset.

## `TokenRemote`

An abstract implementation of `ITokenTransferrer` for a token transfer contract on a "remote" chain that receives transferred assets from a specific `TokenHome` instance. Each `TokenRemote` instance has a single `TokenHome` instance that it receives token transfers from to mint tokens. It also handles sending messages (and correspondingly burning tokens) to route tokens back to other chains (either its `TokenHome`, or other `TokenRemote` instances). Once deployed, a `TokenRemote` instance must be registered with its specified `TokenHome` contract. This is done by calling `registerWithHome` on the remote contract, which will send an ICM message to the home contract with the information to register.

All messages sent by `TokenRemote` instances are sent to the specified `TokenHome` contract, whether they are to redeem the collateral from the `TokenHome` instance or route the tokens to another `TokenRemote` instance. Routing tokens from one `TokenRemote` instance to another is referred to as a "multi-hop", where the tokens are first sent back to their `TokenHome` contract to update its accounting, and then automatically routed on to their intended destination `TokenRemote` instance.

TokenRemote contracts allow for scaling token amounts, which should be used when the remote asset has a higher or lower denomination than the home asset, such as allowing for a ERC20 home asset with a denomination of 6 to be used as the native EVM asset on a remote chain (with a denomination of 18).

## `ERC20TokenRemote`

A concrete implementation of `TokenRemote`, `IERC20TokenTransferrer`, and `IERC20` that handles the minting and burning of an ERC20 asset. Note that the `ERC20TokenRemote` contract is an ERC20 implementation itself, which is why it takes the `tokenName`, `tokenSymbol`, and `tokenDecimals` in its constructor. All of the ERC20 interface implementations are inherited from the standard OpenZeppelin ERC20 implementation, and can be overriden in other implementations if desired.

## `NativeTokenRemote`

A concrete implementation of `TokenRemote`, `INativeTokenTransferrer`, and `IWrappedNativeToken` that handles the minting and burning of the native EVM asset on its chain using the native minter precompile. Deployments of this contract must be given the permission to mint native coins in the chain's configuration. Note that the `NativeTokenRemote` is also an implementation of `IWrappedNativeToken` itself, which is why the `nativeAssetSymbol` must be provided in its constructor. `NativeTokenRemote` instances always have a denomination of 18, which is the denomination of the native asset of EVM chains.

The [native minter precompile](https://build.avax.network/docs/virtual-machines/custom-precompiles#minting-native-coins) must be configured to allow the contract address of the `NativeTokenRemote` instance to call `mintNativeCoin`. The correctness of a native token transferrer implemented using `NativeTokenRemote` relies on no other accounts being allowed to call `mintNativeCoin`, which could result in the token transferrer becoming undercollateralized. Example initialization steps for a `NativeTokenRemote` instance are shown below.

Since the native minter precompile does not provide an interface for burning the native EVM asset, the "burn" functionality is implemented by transferring the native coins to an unowned address. The contract also provides a `reportBurnedTxFees` interface in order to burn the collateral in the `TokenHome` instance that should be made unredeemable to account for native tokens burnt on the chain with the `NativeTokenRemote` instance to pay for transaction fees.

To account for the need to bootstrap the chain using a transferred asset as its native token, the `NativeTokenRemote` takes the `initialReserveImbalance` in its constructor. Once registered with its `TokenHome`, the `TokenHome` will require the `initialReserveImbalance` to be accounted for before sending token amounts to be minted on the given remote chain. The following example demonstrates the intended initialization flow:

1. Create a new blockchain with 100 native tokens allocated in its genesis block, and set the pre-derived `NativeTokenRemote` contract address (based on the deployer nonce) to have the permission to mint native tokens using the native minter precompile. Note that the deployer account will need to be funded in order to deploy the `NativeTokenRemote` contract, and an account used to relay messages into this chain must also be funded to relay the first messages.
2. Deploy the `NativeTokenRemote` contract to the pre-derived address set in the blockchain configuration of step 1. The `initialReserveImbalance` should be 100, matching the number of tokens allocated in the genesis block that were not initially backed by collateral in the `TokenHome` instance.
3. Call the `registerWithHome` function on the `NativeTokenRemote` instance to send an ICM message registering this remote with its `TokenHome`. This message should be relayed and delivered to the `TokenHome` instance.
4. Once registered on the `TokenHome` contract, add 100 tokens as collateral for the new `NativeTokenRemote` instance by calling the `addCollateral` function on the `TokenHome` contract. A `CollateralAdded` event will be emitted by the `TokenHome` contract with a `remaining` amount of 0 once the `NativeTokenRemote` is fully collateralized.
5. Now that the `NativeTokenRemote` contract is fully collateralized, tokens can be moved normally in both directions across the token transfer contracts by calling their `send` functions.

The `totalNativeAssetSupply` implementation of `NativeTokenRemote` takes into account:

- the initial reserve imbalance
- the number of native tokens that it has minted
- the number of native tokens that have been burned to pay for transaction fees
- the number of native tokens "burned" to be transferred to other chains, which are sent to a pre-defined `BURNED_FOR_TRANSFER_ADDRESS`.

Note that the value returned by `totalNativeAssetSupply` is an upper bound on the circulating supply of the native asset on the chain using the `NativeTokenRemote` instance since tokens could be burned in other ways that it does not account for.

## ICM Message Fees

Fees can be optionally added to ICM messages in order to incentivize relayers to deliver them, as documented [here](https://github.com/ava-labs/icm-contracts/tree/main/contracts/teleporter#fees). The token transfer contracts in this repository allow for specifying any ERC20 token and amount to be used as the ICM message fee for single-hop transfers in either direction between `TokenHome` and `TokenRemote` instances. Fee amounts must be pre-approved to be spent by the token transfer contract before initiating a transfer.

Multi-hop transfers between two `TokenRemote` instances involve two ICM messages: the first from the initiating `TokenRemote` instance to its home, and the second from its home to the destination `TokenRemote` instance. In the multi-hop case, the first message fee can be paid in any ERC20 token and amount (similar to the single-hop case), but the second message fee must be paid in-kind of the asset being transferred and is deducted from the amount being transferred. This restriction on the secondary message fee is necessary because the transaction on the intermediate chain routing the funds to the destination `TokenRemote` instance is not sent by the wallet performing the transfer. Because of this, it can not directly spend an arbitrary ERC20 token from that wallet. Using the asset being transferred for the optional secondary fee allows users to perform an incentivized multi-hop transfer without needing to make any interaction with the home themselves. If there is a need for the second message from the home to the destination `TokenRemote` instance to pay a fee in another asset, it is recommended to perform two single-hop transfers, which allows for specifying an arbitrary ERC20 token to be used for the fee of each.

# Teleporter Addresses (/docs/cross-chain/teleporter/addresses)

---
title: Teleporter Addresses
---

## Deployed Addresses
| Contract              | Address                                        | Chain                    |
| --------------------- | ---------------------------------------------- | ------------------------ |
| `TeleporterMessenger` | **0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf** | All chains, all networks |
| `TeleporterRegistry`  | **0x7C43605E14F391720e1b37E49C78C4b03A488d98** | Mainnet C-Chain          |
| `TeleporterRegistry`  | **0xF86Cb19Ad8405AEFa7d09C778215D2Cb6eBfB228** | Fuji C-Chain             |



1. Using [Nick's method](https://yamenmerhi.medium.com/nicks-method-ethereum-keyless-execution-168a6659479c#), `TeleporterMessenger` deploys at a universal address across all chains, varying with each `teleporter` Major release. **Compatibility exists only between same versions of `TeleporterMessenger` instances.** See [Teleporter Contract Deployment](https://github.com/ava-labs/teleporter/blob/main/utils/contract-deployment/README.md) and [Deploy Teleporter to a Subnet](https://github.com/ava-labs/teleporter/tree/main?tab=readme-ov-file#deploy-teleporter-to-a-subnet) for more details.

2. `TeleporterRegistry` can be deployed to any address. See [Deploy TeleporterRegistry to a Subnet](https://github.com/ava-labs/teleporter/blob/main/README.md#deploy-teleporter-to-a-subnet) for details. The table above enumerates the canonical registry addresses on the Mainnet and Fuji C-Chains.

## A Note on Versioning

Release versions follow the [semver](https://semver.org/) convention of incompatible Major releases. A new Major version is released whenever the `TeleporterMessenger` bytecode is changed, and a new version of `TeleporterMessenger` is meant to be deployed.

Due to the use of Nick's method to deploy the contract to the same address on all chains (see [Teleporter Contract Deployment](https://github.com/ava-labs/teleporter/blob/main/utils/contract-deployment/README.md) for details), this also means that new release versions would result in different Teleporter contract addresses. Minor and Patch versions may pertain to contract changes that do not change the `TeleporterMessenger` bytecode, or to changes in the test frameworks, and will only be included in tags.


# Teleporter CLI (/docs/cross-chain/teleporter/cli)

---
title: "Teleporter CLI"
description: "The CLI is a command line interface for interacting with the Teleporter contracts."
edit_url: https://github.com/ava-labs/teleporter/edit/main/cmd/teleporter-cli/README.md
---

# Teleporter CLI

This directory contains the source code for the Teleporter CLI. The CLI is a command line interface for interacting with the Teleporter contracts. It is written with [cobra](https://github.com/spf13/cobra) commands as a Go application.

## Build

To build the CLI, run `go build` from this directory. This will create a binary called `teleporter-cli` in the current directory.

## Usage

The CLI has a number of subcommands. To see the list of subcommands, run `./teleporter-cli help`. To see the help for a specific subcommand, run `./teleporter-cli help <subcommand>`.

The supported subcommands include:

- `event`: given a log event's topics and data, attempts to decode into a Teleporter event in a more readable format.
- `message`: given a Teleporter message encoded as a hex string, attempts to decode into a Teleporter message in a more readable format.
- `transaction`: given a transaction hash, attempts to decode all relevant TeleporterMessenger and ICM log events in a more readable format.

# Deep Dive into ICM Contracts (/docs/cross-chain/teleporter/deep-dive)

---
title: "Deep Dive into ICM Contracts"
description: "ICM Contracts is an EVM compatible cross-Avalanche L1 communication protocol built on top of Avalanche Interchain Messaging (ICM), and implemented as a Solidity smart contract."
edit_url: https://github.com/ava-labs/icm-contracts/edit/main/README.md
---

# ICM Contracts

For help getting started with building ICM contracts, refer to [the avalanche-starter-kit repository](https://github.com/ava-labs/avalanche-starter-kit).

- [Setup](#setup)
  - [Initialize the repository](#initialize-the-repository)
  - [Dependencies](#dependencies)
- [Structure](#structure)
- [E2E tests](#e2e-tests)
  - [Run specific E2E tests](#run-specific-e2e-tests)
- [ABI Bindings](#abi-bindings)
- [Docs](#docs)
- [Resources](#resources)

## Setup

### Initialize the repository

- Get all submodules: `git submodule update --init --recursive`

### Dependencies

- [Ginkgo](https://onsi.github.io/ginkgo/#installing-ginkgo) for running the end-to-end tests.
- [Foundry](https://book.getfoundry.sh/) Use `./scripts/install_foundry.sh` to install Foundry for building contracts.

## Structure

- `contracts/`
  - [`governance/`](https://github.com/ava-labs/teleporter/blob/main/contracts/governance/README.md) includes contracts related to L1 governance.
  - [`ictt/`](https://github.com/ava-labs/teleporter/blob/main/contracts/ictt/README.md) Interchain Token Transfer contracts. Facilitates the transfer of tokens among L1s.
  - [`teleporter/`](https://github.com/ava-labs/teleporter/blob/main/contracts/teleporter/README.md) includes `TeleporterMessenger`, which serves as the interface for most contracts to use ICM.
    - [`registry/`](https://github.com/ava-labs/teleporter/blob/main/contracts/teleporter/registry/README.md) includes a registry contract for managing different versions of `TeleporterMessenger`.
  - [`validator-manager/`](https://github.com/ava-labs/teleporter/blob/main/contracts/validator-manager/README.md) includes contracts for managing the validator set of an L1.
- `abi-bindings/` includes Go ABI bindings for the contracts in `contracts/`.
- [`audits/`](https://github.com/ava-labs/teleporter/blob/main/audits/README.md) includes all audits conducted on contracts in this repository.
- `tests/` includes integration tests for the contracts in `contracts/`, written using the [Ginkgo](https://onsi.github.io/ginkgo/) testing framework.
- `utils/` includes Go utility functions for interacting with the contracts in `contracts/`. Included are Golang scripts to derive the expected EVM contract address deployed from a given EOA at a specific nonce, and also construct a transaction to deploy provided byte code to the same address on any EVM chain using [Nick's method](https://yamenmerhi.medium.com/nicks-method-ethereum-keyless-execution-168a6659479c#).
- `scripts/` includes bash scripts for interacting with TeleporterMessenger in various environments, as well as utility scripts.
  - `abi_bindings.sh` generates ABI bindings for the contracts in `contracts/` and outputs them to `abi-bindings/`.
  - `lint.sh` performs Solidity and Golang linting.

## E2E tests

In addition to the docker setup, end-to-end integration tests written using Ginkgo are provided in the `tests/` directory. E2E tests are run as part of CI, but can also be run locally. Any new features or cross-chain example applications checked into the repository should be accompanied by an end-to-end tests. See the [Contribution Guide](https://github.com/ava-labs/teleporter/blob/main/CONTRIBUTING.md) for additional details.

To run the E2E tests locally, you'll need to install Gingko following the instructions [here](https://onsi.github.io/ginkgo/#installing-ginkgo).

Then run the following command from the root of the repository:

```bash
./scripts/e2e_test.sh
```

### Run specific E2E tests

To run a specific E2E test, specify the environment variable `GINKGO_FOCUS`, which will then look for test descriptions that match the provided input. For example, to run the `Calculate Teleporter message IDs` test:

```bash
GINKGO_FOCUS="Calculate Teleporter message IDs" ./scripts/e2e_test.sh
```

A substring of the full test description can be used as well:

```bash
GINKGO_FOCUS="Calculate Teleporter" ./scripts/e2e_test.sh
```

The E2E test script also supports a `--components` flag, making it easy to run all the test cases for a particular project. For example, to run all E2E tests for the `tests/flows/ictt/` folder:

```bash
./scripts/e2e_test.sh --components "ictt"
```

## ABI Bindings

The E2E tests written in Golang interface with the solidity contracts by use of generated ABI bindings. To regenerate Golang ABI bindings for the Solidity smart contracts, run:

```bash
./scripts/abi_bindings.sh
```

The auto-generated bindings should be written under the `abi-bindings/` directory.

## Docs

- [ICM Protocol Overview](https://github.com/ava-labs/teleporter/blob/main/contracts/teleporter/README.md)
- [Teleporter Registry and Upgrades](https://github.com/ava-labs/teleporter/blob/main/contracts/teleporter/registry/README.md)
- [Contract Deployment](https://github.com/ava-labs/teleporter/blob/main/utils/contract-deployment/README.md)
- [Teleporter CLI](https://github.com/ava-labs/teleporter/blob/main/cmd/teleporter-cli/README.md)

## Resources

- List of blockchain signing cryptography algorithms [here](http://ethanfast.com/top-crypto.html).
- Background on stateful precompiles [here](https://medium.com/avalancheavax/customizing-the-evm-with-stateful-precompiles-f44a34f39efd).
- Background on BLS signature aggregation [here](https://crypto.stanford.edu/~dabo/pubs/papers/BLSmultisig.html).

# Getting Started (/docs/cross-chain/teleporter/getting-started)

---
title: Getting Started
---

<Callout title="Note">
Dive deeper into Teleporter and kickstart your journey in building cross-chain dApps by enrolling in our [Teleporter course](/academy/interchain-messaging).
</Callout>

<Callout title="Note">
 Note: All example applications in the [examples](https://github.com/ava-labs/teleporter/tree/example-sequential-message-app/contracts/sequential-delivery-example) directory are meant for education purposes only and are not audited. The example contracts are not intended for use in production environments.
</Callout>

This section walks through how to build an example cross-chain application on top of the Teleporter protocol, recreating the `ExampleCrossChainMessenger` [contract](https://github.com/ava-labs/teleporter/tree/example-sequential-message-app/contracts/sequential-delivery-example) that sends arbitrary string data from one chain to another. Note that this tutorial is meant for education purposes only. The resulting code is not intended for use in production environments.

Step 1: Create Initial Contract[​](#step-1-create-initial-contract "Direct link to heading")
--------------------------------------------------------------------------------------------

Create a new file called `MyExampleCrossChainMessenger.sol` in a new directory:

```
mkdir teleporter/contracts/src/CrossChainApplications/MyExampleCrossChainMessenger/
touch teleporter/contracts/src/CrossChainApplications/MyExampleCrossChainMessenger/MyExampleCrossChainMessenger.sol
```

At the top of the file define the Solidity version to work with, and import the necessary types and interfaces.

```
pragma solidity 0.8.18;

import {ITeleporterMessenger, TeleporterMessageInput, TeleporterFeeInfo} from "@teleporter/ITeleporterMessenger.sol";
import {ReentrancyGuard} from "@openzeppelin/[email protected]/security/ReentrancyGuard.sol";
```

Next, define the initial empty contract. The contract inherits from `ReentrancyGuard` to prevent reentrancy attacks.

```
contract MyExampleCrossChainMessenger is
    ReentrancyGuard
{

}
```

Finally, add the following struct and event declarations into the body of the contract, which will be integrated in later:

```
    /**
     * @dev Messages sent to this contract.
     */
    struct Message {
        address sender;
        string message;
    }

    /**
     * @dev Emitted when a message is submited to be sent.
     */
    event SendMessage(
        bytes32 indexed destinationBlockchainID,
        address indexed destinationAddress,
        address feeTokenAddress,
        uint256 feeAmount,
        uint256 requiredGasLimit,
        string message
    );

    /**
     * @dev Emitted when a new message is received from a given chain ID.
     */
    event ReceiveMessage(
        bytes32 indexed sourceBlockchainID,
        address indexed originSenderAddress,
        string message
    );
```

Step 2: Integrating Teleporter Messenger[​](#step-2-integrating-teleporter-messenger "Direct link to heading")
--------------------------------------------------------------------------------------------------------------

Now that the initial empty `MyExampleCrossChainMessenger` is defined, it's time to integrate with `ITeleporterMessenger`, which will provide the functionality to deliver cross chain messages.

Create a state variable of `ITeleporterMessenger` type called `teleporterMessenger`. Then create a constructor that takes in an address where the Teleporter Messenger would be deployed on this chain, and set the corresponding state variable.

```
    ITeleporterMessenger public immutable teleporterMessenger;

    constructor(address teleporterMessengerAddress) {
        teleporterMessenger = ITeleporterMessenger(teleporterMessengerAddress);
    }
```

Step 3: Send and Receive[​](#step-3-send-and-receive "Direct link to heading")
------------------------------------------------------------------------------

Now that `MyExampleCrossChainMessenger` has an instantiation of `ITeleporterMessenger`, the next step is to add in the functionality of sending and receiving arbitrary string data between chains.

To start, create the function declaration for `sendMessage`, which will send string data cross-chain to the specified destination address' receiver. This function allows callers to specify the destination chain ID, destination address to send to, relayer fees, required gas limit for message execution at the destination address.

```
    /**
     * @dev Send a new message to another chain.
     */
    function sendMessage(
        bytes32 destinationBlockchainID,
        address destinationAddress,
        address feeTokenAddress,
        uint256 feeAmount,
        uint256 requiredGasLimit,
        string calldata message
    ) external returns (bytes32 messageID) {

    }
```

`MyExampleCrossChainMessenger` also needs to implement `ITeleporterReceiver`. First, add the import of this interface:

```
import {ITeleporterReceiver} from "@teleporter/ITeleporterReceiver.sol";
```

Then declare that the contract will implement it:

```
  contract MyExampleCrossChainMessenger is
-     ReentrancyGuard
+     ReentrancyGuard,
+     ITeleporterReceiver
  {
```

And then finally add the method `receiveTeleporterMessage` that receives the cross-chain messages from Teleporter.

```
    /**
     * @dev Receive a new message from another chain.
     */
    function receiveTeleporterMessage(
        bytes32 sourceBlockchainID,
        address originSenderAddress,
        bytes calldata message
    ) external {

    }
```

Now it's time to implement the methods, starting with `sendMessage`. First, add the necessary imports.

```
import {SafeERC20TransferFrom, SafeERC20} from "@teleporter/SafeERC20TransferFrom.sol";
import {IERC20} from "@openzeppelin/[email protected]/token/ERC20/IERC20.sol";
```

Next, add a `using` directive to the top of the contract body specifying `SafeERC20` as the `IERC20` implementation to use:

```
    using SafeERC20 for IERC20;
```

Then add a check to the `sendMessage` function for whether `feeAmount` is greater than zero. If it is, transfer and approve the amount of IERC20 asset at `feeTokenAddress` to the Teleporter Messenger saved as a state variable.

```
        // For non-zero fee amounts, first transfer the fee to this contract, and then
        // allow the Teleporter contract to spend it.
        uint256 adjustedFeeAmount;
        if (feeAmount > 0) {
            adjustedFeeAmount = SafeERC20TransferFrom.safeTransferFrom(
                IERC20(feeTokenAddress),
                feeAmount
            );
            IERC20(feeTokenAddress).safeIncreaseAllowance(
                address(teleporterMessenger),
                adjustedFeeAmount
            );
        }
```

> Note: Relayer fees are an optional way to incentivize relayers to deliver a Teleporter message to its destination. They are not strictly necessary, and may be omitted if a relayer is willing to relay messages with no fee, such as with a self-hosted relayer.

Next, to the end of the `sendMessage` function, add the event to emit, as well as the call to the `TeleporterMessenger` contract with the message data to be executed when delivered to the destination address. Form a `TeleporterMessageInput` and call `sendCrossChainMessage` on the `TeleporterMessenger` instance to start the cross chain messaging process. The `message` must be ABI encoded so that it can be properly decoded on the receiving end.

> Note: `allowedRelayerAddresses` is empty in this example, meaning any relayer can try to deliver this cross chain message. Specific relayer addresses can be specified to ensure only those relayers can deliver the message.

```
        emit SendMessage({
            destinationBlockchainID: destinationBlockchainID,
            destinationAddress: destinationAddress,
            feeTokenAddress: feeTokenAddress,
            feeAmount: adjustedFeeAmount,
            requiredGasLimit: requiredGasLimit,
            message: message
        });
        return
            teleporterMessenger.sendCrossChainMessage(
                TeleporterMessageInput({
                    destinationBlockchainID: destinationBlockchainID,
                    destinationAddress: destinationAddress,
                    feeInfo: TeleporterFeeInfo({
                        feeTokenAddress: feeTokenAddress,
                        amount: adjustedFeeAmount
                    }),
                    requiredGasLimit: requiredGasLimit,
                    allowedRelayerAddresses: new address[](0),
                    message: abi.encode(message)
                })
            );
```

With the sending side complete, the next step is to implement `ITeleporterReceiver.receiveTeleporterMessage`. The receiver in this example will just receive the arbitrary string data, and check that the message is sent through Teleporter. To the `receiveTeleporterMessage` function, add:

```
        // Only the Teleporter receiver can deliver a message.
        require(msg.sender == address(teleporterMessenger), "Unauthorized.");

        // do something with message.
```

The base of sending and receiving messages cross chain is complete. `MyExampleCrossChainMessenger` can now be expanded with functionality that saves the received messages, and allows users to query for the latest message received from a specified chain.

Step 4: Storing the Message[​](#step-4-storing-the-message "Direct link to heading")
------------------------------------------------------------------------------------

Start by adding a map to the body of the contract, in which the key is the `sourceBlockchainID` and the value is the latest `message` sent from that chain. The `message` is of type `Message`, which is already declared in the contract.

```
    mapping(bytes32 sourceBlockchainID => Message message) private _messages;
```

Next, update `receiveTeleporterMessage` to save the message into the mapping after it is received and verified that it's sent from Teleporter. At the end of that function, ABI decode the `message` bytes into a string, and emit the `ReceiveMessage` event.

```
        // Store the message.
        string memory messageString = abi.decode(message, (string));
        _messages[sourceBlockchainID] = Message(
            originSenderAddress,
            messageString
        );
        emit ReceiveMessage(
            sourceBlockchainID,
            originSenderAddress,
            messageString
        );
```

Next, add a function to the contract called `getCurrentMessage` that allows users or contracts to easily query the contract for the latest message sent by a specified chain.

```
    /**
     * @dev Check the current message from another chain.
     */
    function getCurrentMessage(
        bytes32 sourceBlockchainID
    ) external view returns (address, string memory) {
        Message memory messageInfo = _messages[sourceBlockchainID];
        return (messageInfo.sender, messageInfo.message);
    }
```

Step 5: Upgrade Support[​](#step-5-upgrade-support "Direct link to heading")
----------------------------------------------------------------------------

At this point, the contract is now fully usable, and can be used to send arbitrary string data between chains. However, there are a few more modifications that need to be made to support upgrades to `TeleporterMessenger`. For a more in-depth explanation of how to support upgrades, see the Upgrades README [here](https://github.com/ava-labs/teleporter/blob/main/contracts/teleporter/registry/UPGRADING.md).

The first change to make is to inherit from `TeleporterOwnerUpgradeable` instead of `ITeleporterReceiver`. `TeleporterOwnerUpgradeable` integrates with the `TeleporterRegistry` via `TeleporterUpgradeable` to easily utilize the latest `TeleporterMessenger` implementation. `TeleporterOwnerUpgradeable` also ensures that only an admin address for managing Teleporter versions, specified by the constructor argument `teleporterManager`, is able to upgrade the `TeleporterMessenger` implementation used by the contract.

To start, replace the import for `ITeleporterReceiver` with `TeleporterOwnerUpgradeable`:

```
- import {ITeleporterReceiver} from "@teleporter/ITeleporterReceiver.sol";
+ import {TeleporterOwnerUpgradeable} from "@teleporter/upgrades/TeleporterOwnerUpgradeable.sol";
```

Also, replace the contract declaration to inherit from `TeleporterOwnerUpgradeable` instead of `ITeleporterReceiver`:

```
contract MyExampleCrossChainMessenger is
     ReentrancyGuard,
-    ITeleporterReceiver
+    TeleporterOwnerUpgradeable
{
```

Next, update the constructor to invoke the `TeleporterOwnerUpgradeable` constructor.

```
-     constructor(address teleporterMessengerAddress) {
-         teleporterMessenger = ITeleporterMessenger(teleporterMessengerAddress);
-     }
+     constructor(
+         address teleporterRegistryAddress,
+         address teleporterManager
+     ) TeleporterOwnerUpgradeable(teleporterRegistryAddress, teleporterManager) {}
```

Then, remove the `teleporterMessenger` state variable:

```
-     ITeleporterMessenger public immutable teleporterMessenger;
```

And at the beginning of `sendMessage()` add a call to get the latest `ITeleporterMessenger` implementation from `TeleporterRegistry`:

```
        ITeleporterMessenger teleporterMessenger = teleporterRegistry.getLatestTeleporter();
```

And finally, change `receiveTeleporterMessage` to `_receiveTeleporterMessage`, mark it as `internal override`, and change the data location of its `message` parameter to `memory`. It's also safe to remove the check against `teleporterMessenger` in `_receiveTeleporterMessage`, since that same check is handled in `TeleporterOwnerUpgradeable`'s `receiveTeleporterMessage` function.

```
-     function receiveTeleporterMessage(
+     function _receiveTeleporterMessage(
          bytes32 sourceBlockchainID,
          address originSenderAddress,
-         bytes calldata message
+         bytes memory message
-     ) external {
+     ) internal override {
-          // Only the Teleporter receiver can deliver a message.
-          require(msg.sender == address(teleporterMessenger), "Unauthorized.");
```

`MyExampleCrossChainMessenger` is now a working cross-chain dApp built on top of Teleporter! Full example [here](https://github.com/ava-labs/teleporter/tree/example-sequential-message-app/contracts/sequential-delivery-example).

Step 6: Testing[​](#step-6-testing "Direct link to heading")
------------------------------------------------------------

For testing, `scripts/local/e2e_test.sh` sets up a local test environment consisting of three avalanche-l1s deployed with Teleporter, and a lightweight inline relayer implementation to facilitate cross chain message delivery. An end-to-end test for `ExampleCrossChainMessenger` is included in `tests/flows/example_messenger.go`, which performs the following:

1.  Deploys the [ExampleERC20](https://github.com/ava-labs/teleporter/blob/main/contracts/mocks/ExampleERC20.sol) token to avalanche-l1 A.
2.  Deploys `ExampleCrossChainMessenger` to both avalanche-l1s A and B.
3.  Approves the cross-chain messenger on avalanche-l1 A to spend ERC20 tokens from the default address.
4.  Sends `"Hello, world!"` from avalanche-l1 A to avalanche-l1 B's cross-chain messenger to receive.
5.  Calls `getCurrentMessage` on avalanche-l1 B to make sure the right message and sender are received.

To run this test against the newly created `MyExampleCrossChainMessenger`, first generate the ABI Go bindings by running `./scripts/abi_bindings.sh --contract MyExampleCrossChainMessenger` from the root of this repository. Then, add to the generated Go package the `SendMessageRequiredGas` constant, which is required by the tests, in a new file `abi-bindings/go/CrossChainApplications/MyExampleCrossChainMessenger/MyExampleCrossChainMessenger/constants.go`:

```js
package myexamplecrosschainmessenger

import "math/big"

var SendMessageRequiredGas = big.NewInt(300000)
```

Next, modify `tests/utils/utils.go`, which is used by `tests/flows/example_messenger.go`, to use the ABI bindings for `MyExampleCrossChainMessenger` instead of `ExampleCrossChainMessenger`. First replace the import:

```
-       examplecrosschainmessenger "github.com/ava-labs/teleporter/abi-bindings/go/CrossChainApplications/examples/ExampleMessenger/ExampleCrossChainMessenger"
+       myexamplecrosschainmessenger "github.com/ava-labs/teleporter/abi-bindings/go/CrossChainApplications/MyExampleCrossChainMessenger/MyExampleCrossChainMessenger"
```

Then, in that same `utils.go`, replace all instances of to `examplecrosschainmessenger` with `myexamplecrosschainmessenger` and all instances of `ExampleCrossChainMessenger` with `MyExampleCrossChainMessenger`.

Finally, from the root of the repository, invoke the tests with an extra bit of configuration that tells the Ginkgo test framework to focus only on the tests of this example contract (excluding all of the broader tests of Teleporter):

```
GINKGO_FOCUS="Example cross chain messenger" scripts/local/e2e_test.sh

```



# What is ICM Contracts? (/docs/cross-chain/teleporter/overview)

---
title: "What is ICM Contracts?"
description: "ICM Contracts is a messaging protocol built on top of Avalanche Interchain Messaging that provides a developer-friendly interface for sending and receiving cross-chain messages from the EVM."
edit_url: https://github.com/ava-labs/icm-contracts/edit/main/contracts/teleporter/README.md
---

# ICM Protocol

- [Overview](#overview)
- [Data Flow](#data-flow)
- [Properties](#properties)
- [Fees](#fees)
- [Message Receipts and Fee Redemption](#message-receipts-and-fee-redemption)
- [Required Interface](#required-interface)
- [Message Delivery and Execution](#message-delivery-and-execution)
- [Resending a Message](#resending-a-message)
- [TeleporterMessenger Contract Deployment](#teleportermessenger-contract-deployment)
- [Deployed Addresses](#deployed-addresses)
- [A Note on Versioning](#a-note-on-versioning)
- [Upgradability](#upgradability)
- [Deploy TeleporterMessenger to an L1](#deploy-teleportermessenger-to-an-avalanche-l1)
- [Deploy TeleporterRegistry to an L1](#deploy-teleporterregistry-to-an-avalanche-l1)
- [Verify a Deployment of TeleporterMessenger](#verify-a-deployment-of-teleportermessenger)

## Overview

`TeleporterMessenger` is a smart contract that serves as the interface for ICM contracts to [Avalanche Interchain Messaging (ICM)](https://build.avax.network/academy/interchain-messaging/04-icm-basics/01-icm-basics). It provides a mechanism to asynchronously invoke smart contract functions on other EVM L1s within Avalanche. `TeleporterMessenger` provides a handful of useful features to ICM, such as specifying relayer incentives for message delivery, replay protection, message delivery and execution retries, and a standard interface for sending and receiving messages within a dApp deployed across multiple Avalanche L1s.

The `TeleporterMessenger` contract is a user-friendly interface to ICM, aimed at dApp developers. All of the message signing and verification is abstracted away from developers. Instead, developers simply call `sendCrossChainMessage` on the `TeleporterMessenger` contract to send a message invoking a smart contract on another Avalanche L1, and implement the `ITeleporterReceiver` interface to receive messages on the destination Avalanche L1. `TeleporterMessenger` handles all of the ICM message construction and sending, as well as the message delivery and execution.

To get started with using `TeleporterMessenger`, see [How to Deploy ICM Enabled Avalanche L1s on a Local Network](https://build.avax.network/docs/tooling/cross-chain/teleporter-local-network)

The `ITeleporterMessenger` interface provides two primary methods:

- `sendCrossChainMessage`: called by contracts on the origin chain to initiate the sending of a message to a contract on another EVM instance.
- `receiveCrossChainMessage`: called by cross-chain relayers on the destination chain to deliver signed messages to the destination EVM instance.

The `ITeleporterReceiver` interface provides a single method. All contracts that wish to receive ICM messages on the destination chain must implement this interface:

- `receiveTeleporterMessage`: called by `TeleporterMessenger` on the destination chain to deliver a message to the destination contract.

> Note: If a contract does not implement `ITeleporterReceiver`, but instead implements [fallback](https://docs.soliditylang.org/en/latest/contracts.html#fallback-function), the fallback function will be called when `TeleporterMessenger` attempts to perform message execution. The message execution is marked as failed if the fallback function reverts, otherwise it is marked as successfully executed.

## Data Flow

<div align="center">
  <img src="https://raw.githubusercontent.com/ava-labs/icm-contracts/main/resources/TeleporterDataFlowDiagram.png" />/>
</div>

## Properties

TeleporterMessenger provides a handful of useful properties to cross-chain applications that ICM messages do not provide by default. These include:

1. Replay protection: `TeleporterMessenger` ensures that a cross-chain message is not delivered multiple times.
2. Retries: In certain edge cases when there is significant validator churn, it is possible for an ICM Message to be dropped before a valid aggregate signature is created for it. `TeleporterMessenger` ensures that messages can still be delivered even in this event by allowing for retries of previously submitted messages.
3. Relay incentivization: `TeleporterMessenger` provides a mechanism for messages to optionally incentivize relayers to perform the necessary signature aggregation and pay the transaction fee to broadcast the signed message on the destination chain.
4. Allowed relayers: `TeleporterMessenger` allows users to specify a list of `allowedRelayerAddresses`, where only the specified addresses can relay and deliver the `TeleporterMessenger` message. Leaving this list empty allows all relayers to deliver.
5. Message execution: `TeleporterMessenger` enables cross-chain messages to have direct effect on their destination chain by using `evm.Call()` to invoke the `receiveTeleporterMessage` function of destination contracts that implement the `ITeleporterReceiver` interface.

## Fees

Fees can be paid on a per message basis by specifing the ERC20 asset and amount to be used to incentivize a relayer to deliver the message in the call to `sendCrossChainMessage`. The fee amount is transferred into the control of `TeleporterMessenger` (i.e. locked) before the ICM message is sent. `TeleporterMessenger` tracks the fee amount for each message ID it creates. When it subsequently receives a message back from the destination chain of the original message, the new message will have a list of receipts identifying the relayer that delivered the given message ID. At this point, the fee amount originally locked by `TeleporterMessenger` for the given message will be redeemable by the relayer identified in the receipt. If the initial fee amount was not sufficient to incentivize a relayer, it can be added to by using `addFeeAmount`.

### Message Receipts and Fee Redemption

In order to confirm delivery of a `TeleporterMessenger` message from a source chain to a destination chain, a receipt is included in the next `TeleporterMessenger` message sent in the opposite direction, from the destination chain back to the source chain. This receipt contains the message ID of the original message, as well as the reward address that the delivering relayer specified. That reward address is then able to redeem the corresponding reward on the original chain by calling `redeemRelayerRewards`. The following example illustrates this flow:

- A `TeleporterMessenger` message is sent from Chain A to Chain B, with a relayer incentive of `10` `USDC`. This message is assigned the ID `1` by the `TeleporterMessenger` contract on Chain A.
  - On Chain A, this is done by calling `sendCrossChainMessage`, and providing the `USDC` contract address and amount in the function call.
- A relayer delivers the message on Chain B by calling `receiveCrossChainMessage` and providing its address, `0x123...`
- The `TeleporterMessenger` contract on Chain B stores the relayer address in a receipt for the message ID.
- Some time later, a separate `TeleporterMessenger` message is sent from Chain B to Chain A. The `TeleporterMessenger` contract on Chain B includes the receipt for the original message in this new message.
- When this new message is delivered on Chain A, the `TeleporterMessenger` contract on Chain A reads the receipt and attributes the rewards for delivering the original message (message ID `1`) to the address `0x123...`.
- Address `0x123...` may now call `redeemRelayerRewards` on Chain A, which transfers the `10` `USDC` to its address. If it tries to do this before the receipt is received on Chain A, the call will fail.

It is possible for receipts to get "stuck" on the destination chain in the event that `TeleporterMessenger` traffic between two chains is skewed in one direction. In such a scenario, incoming messages on one chain may cause the rate at which receipts are generated to outpace the rate at which they are sent back to the other chain. To mitigate this, the method `sendSpecifiedReceipts` can be called to immediately send the receipts associated with the given message IDs back to the original chain.

## Required Interface

`TeleporterMessenger` messages are delivered by calling the `receiveTeleporterMessage` function defined by the `ITeleporterReceiver` interface. Contracts must implement this interface in order to be able to receive messages. The first two parameters of `receiveTeleporterMessage` identify the original sender of the given message on the origin chain and are set by the `TeleporterMessenger`. The third parameter to `receiveTeleporterMessage`, is the raw message payload. Applications using `TeleporterMessenger` are responsible for defining the exact format of this payload in a way that can be decoded on the receiving end. For example, applications may encode an action enum value along with the target method parameters on the sending side, then decode this data and route to the target method within `receiveTeleporterMessage`. See `ERC20Bridge.sol` for an example of this approach.

## Message Delivery and Execution

`TeleporterMessenger` is able to ensure that messages are considered delivered even if their execution fails (i.e. reverts) by using `evm.Call()` with a pre-defined gas limit to execute the message payload. This gas limit is specified by each message in the call to `sendCrossChainMessage`. Relayers must provide at least enough gas for the sub-call in addition to the standard gas used by a call to `receiveCrossChainMessage`. In the event that a message execution runs out of gas or reverts for any other reason, the hash of the message payload is stored by the receiving `TeleporterMessenger` contract instance. This allows for the message execution to be retried in the future, with possibly a higher gas limit by calling `retryMessageExecution`. Importantly, a message is still considered delivered on its destination chain even if its execution fails. This allows the relayer of the message to redeem their reward for deliverying the message, because they have no control on whether or not its execution will succeed or not so long as they provide sufficient gas to meet the specified `requiredGasLimit`.

Note that due to [EIP-150](https://eips.ethereum.org/EIPS/eip-150), the lesser of 63/64<sup>ths</sup> of the remaining gas and the `requiredGasLimit` will be provided to the code executed using `evm.Call()`. This creates an edge case where sufficient gas is provided by the relayer at time of the `requiredGasLimit` check, but less than the `requiredGasLimit` is provided for the message execution. In such a case, the message execution may fail due to having less than the `requiredGasLimit` available, but the message would still be considered received. Such a case is only possible if the remaining 1/64<sup>th</sup> of the `requiredGasLimit` is sufficient for executing the remaining logic of `receiveCrossChainMessage` so that the top level transaction does not also revert. Based on the current implementation, a message must have a `requiredGasLimit` of over 1,200,000 gas for this to be possible. In order to avoid this case entirely, it is recommended for applications sending `TeleporterMessenger` messages to add a buffer to the `requiredGasLimit` such that 63/64<sup>ths</sup> of the value passed is sufficient for the message execution.

## Resending a Message

If the sending Avalanche L1's validator set changes, then it's possible for the receiving Avalanche L1 to reject the underlying ICM message due to insufficient signing stake. For example, suppose L1 A has 5 validators with equal stake weight who all sign a `TeleporterMessenger` message sent to L1 B. 100% of L1 A's stake has signed the message. Also suppose L1 B requires 67% of the sending L1's stake to have signed a given ICM message in order for it to be accepted. Before the message can be delivered, however, 5 _more_ validators are added to L1 A's validator set (all with the same stake weight as the original validators), meaning that the `TeleporterMessenger` message was signed by _only 50%_ of L1 A's stake. L1 B will reject this message.

Once sent on chain, ICM messages cannot be re-signed by a new validator set in such a scenario. Teleporter, however, does support re-signing via the function `retrySendCrossChainMessage`, which can be called for any message that has not been acknowledged as delivered to its destination. Under the hood, this packages the `TeleporterMessenger` message into a brand new ICM message that is re-signed by the current validator set. 

## TeleporterMessenger Contract Deployment

**Do not deploy the `TeleporterMessenger` contract using `forge create`**. The `TeleporterMessenger` contract must be deployed to the same contract address on every chain. To achieve this, the contract can be deployed using a static transaction that uses Nick's method as documented in [this guide](https://github.com/ava-labs/icm-contracts/blob/main/utils/contract-deployment/README.md). Alternatively, if creating a new L1, the contract can be pre-allocated with the proper address and state in the new chain's [genesis file](https://build.avax.network/docs/virtual-machines/custom-precompiles#setting-the-genesis-allocation).

As an example, to include `TeleporterMessenger` `v1.0.0` in the genesis file, include the following values in the `alloc` settings, as documented at the link above. The `storage` values included below correspond to the two contract values that are initialized as part of the default constructor of `TeleporterMessenger`. These are the `ReentrancyGuard` values set in this [abstract contract](https://github.com/ava-labs/icm-contracts/blob/main/contracts/utilities/ReentrancyGuards.sol). Future versions of `TeleporterMessenger` may require different storage value initializations.
```json
"alloc": {
    "0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf": {
        "balance": "0x0",
        "code": "0x608060405234801561001057600080fd5b506004361061014d5760003560e01c8063a8898181116100c3578063df20e8bc1161007c578063df20e8bc1461033b578063e69d606a1461034e578063e6e67bd5146103b6578063ebc3b1ba146103f2578063ecc7042814610415578063fc2d61971461041e57600080fd5b8063a8898181146102b2578063a9a85614146102c5578063b771b3bc146102d8578063c473eef8146102e6578063ccb5f8091461031f578063d127dc9b1461033257600080fd5b8063399b77da11610115578063399b77da1461021957806362448850146102395780638245a1b01461024c578063860a3b061461025f578063892bf4121461027f5780638ac0fd041461029f57600080fd5b80630af5b4ff1461015257806322296c3a1461016d5780632bc8b0bf146101825780632ca40f55146101955780632e27c223146101ee575b600080fd5b61015a610431565b6040519081526020015b60405180910390f35b61018061017b366004612251565b610503565b005b61015a61019036600461226e565b6105f8565b6101e06101a336600461226e565b6005602090815260009182526040918290208054835180850190945260018201546001600160a01b03168452600290910154918301919091529082565b604051610164929190612287565b6102016101fc36600461226e565b610615565b6040516001600160a01b039091168152602001610164565b61015a61022736600461226e565b60009081526005602052604090205490565b61015a6102473660046122ae565b61069e565b61018061025a366004612301565b6106fc565b61015a61026d36600461226e565b60066020526000908152604090205481565b61029261028d366004612335565b6108a7565b6040516101649190612357565b6101806102ad366004612377565b6108da565b61015a6102c03660046123af565b610b19565b61015a6102d3366004612426565b610b5c565b6102016005600160991b0181565b61015a6102f43660046124be565b6001600160a01b03918216600090815260096020908152604080832093909416825291909152205490565b61018061032d3660046124f7565b610e03565b61015a60025481565b61015a61034936600461226e565b61123d565b61039761035c36600461226e565b600090815260056020908152604091829020825180840190935260018101546001600160a01b03168084526002909101549290910182905291565b604080516001600160a01b039093168352602083019190915201610164565b6103dd6103c436600461226e565b6004602052600090815260409020805460019091015482565b60408051928352602083019190915201610164565b61040561040036600461226e565b611286565b6040519015158152602001610164565b61015a60035481565b61018061042c36600461251e565b61129c565b600254600090806104fe576005600160991b016001600160a01b0316634213cf786040518163ffffffff1660e01b8152600401602060405180830381865afa158015610481573d6000803e3d6000fd5b505050506040513d601f19601f820116820180604052508101906104a59190612564565b9050806104cd5760405162461bcd60e51b81526004016104c49061257d565b60405180910390fd5b600281905560405181907f1eac640109dc937d2a9f42735a05f794b39a5e3759d681951d671aabbce4b10490600090a25b919050565b3360009081526009602090815260408083206001600160a01b0385168452909152902054806105855760405162461bcd60e51b815260206004820152602860248201527f54656c65706f727465724d657373656e6765723a206e6f2072657761726420746044820152676f2072656465656d60c01b60648201526084016104c4565b3360008181526009602090815260408083206001600160a01b03871680855290835281842093909355518481529192917f3294c84e5b0f29d9803655319087207bc94f4db29f7927846944822773780b88910160405180910390a36105f46001600160a01b03831633836114f7565b5050565b600081815260046020526040812061060f9061155f565b92915050565b6000818152600760205260408120546106825760405162461bcd60e51b815260206004820152602960248201527f54656c65706f727465724d657373656e6765723a206d657373616765206e6f74604482015268081c9958d95a5d995960ba1b60648201526084016104c4565b506000908152600860205260409020546001600160a01b031690565b60006001600054146106c25760405162461bcd60e51b81526004016104c4906125c4565b60026000556106f16106d383612804565b833560009081526004602052604090206106ec90611572565b61167c565b600160005592915050565b60016000541461071e5760405162461bcd60e51b81526004016104c4906125c4565b6002600081815590546107379060408401358435610b19565b6000818152600560209081526040918290208251808401845281548152835180850190945260018201546001600160a01b03168452600290910154838301529081019190915280519192509061079f5760405162461bcd60e51b81526004016104c4906128a7565b6000836040516020016107b29190612b42565b60408051601f19818403018152919052825181516020830120919250146107eb5760405162461bcd60e51b81526004016104c490612b55565b8360400135837f2a211ad4a59ab9d003852404f9c57c690704ee755f3c79d2c2812ad32da99df8868560200151604051610826929190612b9e565b60405180910390a360405163ee5b48eb60e01b81526005600160991b019063ee5b48eb90610858908490600401612c23565b6020604051808303816000875af1158015610877573d6000803e3d6000fd5b505050506040513d601f19601f8201168201806040525081019061089b9190612564565b50506001600055505050565b604080518082019091526000808252602082015260008381526004602052604090206108d390836118bc565b9392505050565b6001600054146108fc5760405162461bcd60e51b81526004016104c4906125c4565b600260005560018054146109225760405162461bcd60e51b81526004016104c490612c36565b60026001558061098c5760405162461bcd60e51b815260206004820152602f60248201527f54656c65706f727465724d657373656e6765723a207a65726f2061646469746960448201526e1bdb985b0819995948185b5bdd5b9d608a1b60648201526084016104c4565b6001600160a01b0382166109b25760405162461bcd60e51b81526004016104c490612c7b565b6000838152600560205260409020546109dd5760405162461bcd60e51b81526004016104c4906128a7565b6000838152600560205260409020600101546001600160a01b03838116911614610a6f5760405162461bcd60e51b815260206004820152603760248201527f54656c65706f727465724d657373656e6765723a20696e76616c69642066656560448201527f20617373657420636f6e7472616374206164647265737300000000000000000060648201526084016104c4565b6000610a7b8383611981565b600085815260056020526040812060020180549293508392909190610aa1908490612ce5565b909155505060008481526005602052604090819020905185917fc1bfd1f1208927dfbd414041dcb5256e6c9ad90dd61aec3249facbd34ff7b3e191610b03916001019081546001600160a01b0316815260019190910154602082015260400190565b60405180910390a2505060018080556000555050565b60408051306020820152908101849052606081018390526080810182905260009060a0016040516020818303038152906040528051906020012090509392505050565b6000600160005414610b805760405162461bcd60e51b81526004016104c4906125c4565b60026000818155905490866001600160401b03811115610ba257610ba2612607565b604051908082528060200260200182016040528015610be757816020015b6040805180820190915260008082526020820152815260200190600190039081610bc05790505b5090508660005b81811015610d6c5760008a8a83818110610c0a57610c0a612cf8565b90506020020135905060006007600083815260200190815260200160002054905080600003610c8a5760405162461bcd60e51b815260206004820152602660248201527f54656c65706f727465724d657373656e6765723a2072656365697074206e6f7460448201526508199bdd5b9960d21b60648201526084016104c4565b610c958d8783610b19565b8214610d095760405162461bcd60e51b815260206004820152603a60248201527f54656c65706f727465724d657373656e6765723a206d6573736167652049442060448201527f6e6f742066726f6d20736f7572636520626c6f636b636861696e00000000000060648201526084016104c4565b6000828152600860209081526040918290205482518084019093528383526001600160a01b03169082018190528651909190879086908110610d4d57610d4d612cf8565b602002602001018190525050505080610d6590612d0e565b9050610bee565b506040805160c0810182528b815260006020820152610df0918101610d96368b90038b018b612d27565b8152602001600081526020018888808060200260200160405190810160405280939291908181526020018383602002808284376000920182905250938552505060408051928352602080840190915290920152508361167c565b60016000559a9950505050505050505050565b6001805414610e245760405162461bcd60e51b81526004016104c490612c36565b60026001556040516306f8253560e41b815263ffffffff8316600482015260009081906005600160991b0190636f82535090602401600060405180830381865afa158015610e76573d6000803e3d6000fd5b505050506040513d6000823e601f3d908101601f19168201604052610e9e9190810190612da3565b9150915080610f015760405162461bcd60e51b815260206004820152602960248201527f54656c65706f727465724d657373656e6765723a20696e76616c69642077617260448201526870206d65737361676560b81b60648201526084016104c4565b60208201516001600160a01b03163014610f785760405162461bcd60e51b815260206004820152603260248201527f54656c65706f727465724d657373656e6765723a20696e76616c6964206f726960448201527167696e2073656e646572206164647265737360701b60648201526084016104c4565b60008260400151806020019051810190610f929190612f40565b90506000610f9e610431565b90508082604001511461100d5760405162461bcd60e51b815260206004820152603160248201527f54656c65706f727465724d657373656e6765723a20696e76616c6964206465736044820152701d1a5b985d1a5bdb8818da185a5b881251607a1b60648201526084016104c4565b8351825160009161101f918490610b19565b600081815260076020526040902054909150156110945760405162461bcd60e51b815260206004820152602d60248201527f54656c65706f727465724d657373656e6765723a206d65737361676520616c7260448201526c1958591e481c9958d95a5d9959609a1b60648201526084016104c4565b6110a2338460a00151611ae9565b6111005760405162461bcd60e51b815260206004820152602960248201527f54656c65706f727465724d657373656e6765723a20756e617574686f72697a6560448201526832103932b630bcb2b960b91b60648201526084016104c4565b61110e818460000151611b61565b6001600160a01b0386161561114557600081815260086020526040902080546001600160a01b0319166001600160a01b0388161790555b60c08301515160005b81811015611192576111828488600001518760c00151848151811061117557611175612cf8565b6020026020010151611bd3565b61118b81612d0e565b905061114e565b50604080518082018252855181526001600160a01b038916602080830191909152885160009081526004909152919091206111cc91611cfb565b336001600160a01b03168660000151837f292ee90bbaf70b5d4936025e09d56ba08f3e421156b6a568cf3c2840d9343e348a8860405161120d929190613150565b60405180910390a460e0840151511561122f5761122f82876000015186611d57565b505060018055505050505050565b600254600090806112605760405162461bcd60e51b81526004016104c49061257d565b600060035460016112719190612ce5565b905061127e828583610b19565b949350505050565b600081815260076020526040812054151561060f565b60018054146112bd5760405162461bcd60e51b81526004016104c490612c36565b60026001819055546000906112d59084908435610b19565b600081815260066020526040902054909150806113045760405162461bcd60e51b81526004016104c4906128a7565b80836040516020016113169190612b42565b60405160208183030381529060405280519060200120146113495760405162461bcd60e51b81526004016104c490612b55565b600061135b6080850160608601612251565b6001600160a01b03163b116113cf5760405162461bcd60e51b815260206004820152603460248201527f54656c65706f727465724d657373656e6765723a2064657374696e6174696f6e604482015273206164647265737320686173206e6f20636f646560601b60648201526084016104c4565b604051849083907f34795cc6b122b9a0ae684946319f1e14a577b4e8f9b3dda9ac94c21a54d3188c90600090a360008281526006602090815260408083208390558691611420918701908701612251565b61142d60e0870187613174565b60405160240161144094939291906131ba565b60408051601f198184030181529190526020810180516001600160e01b031663643477d560e11b179052905060006114886114816080870160608801612251565b5a84611e8a565b9050806114eb5760405162461bcd60e51b815260206004820152602b60248201527f54656c65706f727465724d657373656e6765723a20726574727920657865637560448201526a1d1a5bdb8819985a5b195960aa1b60648201526084016104c4565b50506001805550505050565b6040516001600160a01b03831660248201526044810182905261155a90849063a9059cbb60e01b906064015b60408051601f198184030181529190526020810180516001600160e01b03166001600160e01b031990931692909217909152611ea4565b505050565b8054600182015460009161060f916131e5565b6060600061158960056115848561155f565b611f76565b9050806000036115d85760408051600080825260208201909252906115d0565b60408051808201909152600080825260208201528152602001906001900390816115a95790505b509392505050565b6000816001600160401b038111156115f2576115f2612607565b60405190808252806020026020018201604052801561163757816020015b60408051808201909152600080825260208201528152602001906001900390816116105790505b50905060005b828110156115d05761164e85611f8c565b82828151811061166057611660612cf8565b60200260200101819052508061167590612d0e565b905061163d565b600080611687610431565b9050600060036000815461169a90612d0e565b919050819055905060006116b383876000015184610b19565b90506000604051806101000160405280848152602001336001600160a01b031681526020018860000151815260200188602001516001600160a01b0316815260200188606001518152602001886080015181526020018781526020018860a00151815250905060008160405160200161172c91906131f8565b60405160208183030381529060405290506000808960400151602001511115611794576040890151516001600160a01b031661177a5760405162461bcd60e51b81526004016104c490612c7b565b604089015180516020909101516117919190611981565b90505b6040805180820182528a820151516001600160a01b039081168252602080830185905283518085018552865187830120815280820184815260008a815260058452869020915182555180516001830180546001600160a01b03191691909516179093559101516002909101558a51915190919086907f2a211ad4a59ab9d003852404f9c57c690704ee755f3c79d2c2812ad32da99df890611838908890869061320b565b60405180910390a360405163ee5b48eb60e01b81526005600160991b019063ee5b48eb9061186a908690600401612c23565b6020604051808303816000875af1158015611889573d6000803e3d6000fd5b505050506040513d601f19601f820116820180604052508101906118ad9190612564565b50939998505050505050505050565b60408051808201909152600080825260208201526118d98361155f565b82106119315760405162461bcd60e51b815260206004820152602160248201527f5265636569707451756575653a20696e646578206f7574206f6620626f756e646044820152607360f81b60648201526084016104c4565b8260020160008385600001546119479190612ce5565b81526020808201929092526040908101600020815180830190925280548252600101546001600160a01b0316918101919091529392505050565b6040516370a0823160e01b815230600482015260009081906001600160a01b038516906370a0823190602401602060405180830381865afa1580156119ca573d6000803e3d6000fd5b505050506040513d601f19601f820116820180604052508101906119ee9190612564565b9050611a056001600160a01b038516333086612058565b6040516370a0823160e01b81523060048201526000906001600160a01b038616906370a0823190602401602060405180830381865afa158015611a4c573d6000803e3d6000fd5b505050506040513d601f19601f82011682018060405250810190611a709190612564565b9050818111611ad65760405162461bcd60e51b815260206004820152602c60248201527f5361666545524332305472616e7366657246726f6d3a2062616c616e6365206e60448201526b1bdd081a5b98dc99585cd95960a21b60648201526084016104c4565b611ae082826131e5565b95945050505050565b60008151600003611afc5750600161060f565b815160005b81811015611b5657846001600160a01b0316848281518110611b2557611b25612cf8565b60200260200101516001600160a01b031603611b465760019250505061060f565b611b4f81612d0e565b9050611b01565b506000949350505050565b80600003611bc15760405162461bcd60e51b815260206004820152602760248201527f54656c65706f727465724d657373656e6765723a207a65726f206d657373616760448201526665206e6f6e636560c81b60648201526084016104c4565b60009182526007602052604090912055565b6000611be484848460000151610b19565b6000818152600560209081526040918290208251808401845281548152835180850190945260018201546001600160a01b031684526002909101548383015290810191909152805191925090611c3b575050505050565b60008281526005602090815260408083208381556001810180546001600160a01b03191690556002018390558382018051830151878401516001600160a01b0390811686526009855283862092515116855292528220805491929091611ca2908490612ce5565b9250508190555082602001516001600160a01b031684837fd13a7935f29af029349bed0a2097455b91fd06190a30478c575db3f31e00bf578460200151604051611cec919061321e565b60405180910390a45050505050565b6001820180548291600285019160009182611d1583612d0e565b90915550815260208082019290925260400160002082518155910151600190910180546001600160a01b0319166001600160a01b039092169190911790555050565b80608001515a1015611db95760405162461bcd60e51b815260206004820152602560248201527f54656c65706f727465724d657373656e6765723a20696e73756666696369656e604482015264742067617360d81b60648201526084016104c4565b80606001516001600160a01b03163b600003611dda5761155a838383612096565b602081015160e0820151604051600092611df892869260240161323e565b60408051601f198184030181529190526020810180516001600160e01b031663643477d560e11b17905260608301516080840151919250600091611e3d919084611e8a565b905080611e5657611e4f858585612096565b5050505050565b604051849086907f34795cc6b122b9a0ae684946319f1e14a577b4e8f9b3dda9ac94c21a54d3188c90600090a35050505050565b60008060008084516020860160008989f195945050505050565b6000611ef9826040518060400160405280602081526020017f5361666545524332303a206c6f772d6c6576656c2063616c6c206661696c6564815250856001600160a01b031661210b9092919063ffffffff16565b80519091501561155a5780806020019051810190611f179190613268565b61155a5760405162461bcd60e51b815260206004820152602a60248201527f5361666545524332303a204552433230206f7065726174696f6e20646964206e6044820152691bdd081cdd58d8d9595960b21b60648201526084016104c4565b6000818310611f8557816108d3565b5090919050565b604080518082019091526000808252602082015281546001830154819003611ff65760405162461bcd60e51b815260206004820152601960248201527f5265636569707451756575653a20656d7074792071756575650000000000000060448201526064016104c4565b60008181526002840160208181526040808420815180830190925280548252600180820180546001600160a01b03811685870152888852959094529490556001600160a01b031990921690559061204e908390612ce5565b9093555090919050565b6040516001600160a01b03808516602483015283166044820152606481018290526120909085906323b872dd60e01b90608401611523565b50505050565b806040516020016120a791906131f8565b60408051601f1981840301815282825280516020918201206000878152600690925291902055829084907f4619adc1017b82e02eaefac01a43d50d6d8de4460774bc370c3ff0210d40c985906120fe9085906131f8565b60405180910390a3505050565b606061127e848460008585600080866001600160a01b031685876040516121329190613283565b60006040518083038185875af1925050503d806000811461216f576040519150601f19603f3d011682016040523d82523d6000602084013e612174565b606091505b509150915061218587838387612190565b979650505050505050565b606083156121ff5782516000036121f8576001600160a01b0385163b6121f85760405162461bcd60e51b815260206004820152601d60248201527f416464726573733a2063616c6c20746f206e6f6e2d636f6e747261637400000060448201526064016104c4565b508161127e565b61127e83838151156122145781518083602001fd5b8060405162461bcd60e51b81526004016104c49190612c23565b6001600160a01b038116811461224357600080fd5b50565b80356104fe8161222e565b60006020828403121561226357600080fd5b81356108d38161222e565b60006020828403121561228057600080fd5b5035919050565b828152606081016108d3602083018480516001600160a01b03168252602090810151910152565b6000602082840312156122c057600080fd5b81356001600160401b038111156122d657600080fd5b820160e081850312156108d357600080fd5b600061010082840312156122fb57600080fd5b50919050565b60006020828403121561231357600080fd5b81356001600160401b0381111561232957600080fd5b61127e848285016122e8565b6000806040838503121561234857600080fd5b50508035926020909101359150565b815181526020808301516001600160a01b0316908201526040810161060f565b60008060006060848603121561238c57600080fd5b83359250602084013561239e8161222e565b929592945050506040919091013590565b6000806000606084860312156123c457600080fd5b505081359360208301359350604090920135919050565b60008083601f8401126123ed57600080fd5b5081356001600160401b0381111561240457600080fd5b6020830191508360208260051b850101111561241f57600080fd5b9250929050565b60008060008060008086880360a081121561244057600080fd5b8735965060208801356001600160401b038082111561245e57600080fd5b61246a8b838c016123db565b90985096508691506040603f198401121561248457600080fd5b60408a01955060808a013592508083111561249e57600080fd5b50506124ac89828a016123db565b979a9699509497509295939492505050565b600080604083850312156124d157600080fd5b82356124dc8161222e565b915060208301356124ec8161222e565b809150509250929050565b6000806040838503121561250a57600080fd5b823563ffffffff811681146124dc57600080fd5b6000806040838503121561253157600080fd5b8235915060208301356001600160401b0381111561254e57600080fd5b61255a858286016122e8565b9150509250929050565b60006020828403121561257657600080fd5b5051919050565b60208082526027908201527f54656c65706f727465724d657373656e6765723a207a65726f20626c6f636b636040820152661a185a5b88125160ca1b606082015260800190565b60208082526023908201527f5265656e7472616e63794775617264733a2073656e646572207265656e7472616040820152626e637960e81b606082015260800190565b634e487b7160e01b600052604160045260246000fd5b604080519081016001600160401b038111828210171561263f5761263f612607565b60405290565b60405160c081016001600160401b038111828210171561263f5761263f612607565b60405161010081016001600160401b038111828210171561263f5761263f612607565b604051601f8201601f191681016001600160401b03811182821017156126b2576126b2612607565b604052919050565b6000604082840312156126cc57600080fd5b6126d461261d565b905081356126e18161222e565b808252506020820135602082015292915050565b60006001600160401b0382111561270e5761270e612607565b5060051b60200190565b600082601f83011261272957600080fd5b8135602061273e612739836126f5565b61268a565b82815260059290921b8401810191818101908684111561275d57600080fd5b8286015b848110156127815780356127748161222e565b8352918301918301612761565b509695505050505050565b60006001600160401b038211156127a5576127a5612607565b50601f01601f191660200190565b600082601f8301126127c457600080fd5b81356127d26127398261278c565b8181528460208386010111156127e757600080fd5b816020850160208301376000918101602001919091529392505050565b600060e0823603121561281657600080fd5b61281e612645565b8235815261282e60208401612246565b602082015261284036604085016126ba565b60408201526080830135606082015260a08301356001600160401b038082111561286957600080fd5b61287536838701612718565b608084015260c085013591508082111561288e57600080fd5b5061289b368286016127b3565b60a08301525092915050565b60208082526026908201527f54656c65706f727465724d657373656e6765723a206d657373616765206e6f7460408201526508199bdd5b9960d21b606082015260800190565b6000808335601e1984360301811261290457600080fd5b83016020810192503590506001600160401b0381111561292357600080fd5b8060051b360382131561241f57600080fd5b8183526000602080850194508260005b858110156129735781356129588161222e565b6001600160a01b031687529582019590820190600101612945565b509495945050505050565b6000808335601e1984360301811261299557600080fd5b83016020810192503590506001600160401b038111156129b457600080fd5b8060061b360382131561241f57600080fd5b8183526000602080850194508260005b858110156129735781358752828201356129ef8161222e565b6001600160a01b03168784015260409687019691909101906001016129d6565b6000808335601e19843603018112612a2657600080fd5b83016020810192503590506001600160401b03811115612a4557600080fd5b80360382131561241f57600080fd5b81835281816020850137506000828201602090810191909152601f909101601f19169091010190565b6000610100823584526020830135612a948161222e565b6001600160a01b0316602085015260408381013590850152612ab860608401612246565b6001600160a01b0316606085015260808381013590850152612add60a08401846128ed565b8260a0870152612af08387018284612935565b92505050612b0160c084018461297e565b85830360c0870152612b148382846129c6565b92505050612b2560e0840184612a0f565b85830360e0870152612b38838284612a54565b9695505050505050565b6020815260006108d36020830184612a7d565b60208082526029908201527f54656c65706f727465724d657373656e6765723a20696e76616c6964206d65736040820152680e6c2ceca40d0c2e6d60bb1b606082015260800190565b606081526000612bb16060830185612a7d565b90506108d3602083018480516001600160a01b03168252602090810151910152565b60005b83811015612bee578181015183820152602001612bd6565b50506000910152565b60008151808452612c0f816020860160208601612bd3565b601f01601f19169290920160200192915050565b6020815260006108d36020830184612bf7565b60208082526025908201527f5265656e7472616e63794775617264733a207265636569766572207265656e7460408201526472616e637960d81b606082015260800190565b60208082526034908201527f54656c65706f727465724d657373656e6765723a207a65726f2066656520617360408201527373657420636f6e7472616374206164647265737360601b606082015260800190565b634e487b7160e01b600052601160045260246000fd5b8082018082111561060f5761060f612ccf565b634e487b7160e01b600052603260045260246000fd5b600060018201612d2057612d20612ccf565b5060010190565b600060408284031215612d3957600080fd5b6108d383836126ba565b80516104fe8161222e565b600082601f830112612d5f57600080fd5b8151612d6d6127398261278c565b818152846020838601011115612d8257600080fd5b61127e826020830160208701612bd3565b805180151581146104fe57600080fd5b60008060408385031215612db657600080fd5b82516001600160401b0380821115612dcd57600080fd5b9084019060608287031215612de157600080fd5b604051606081018181108382111715612dfc57612dfc612607565b604052825181526020830151612e118161222e565b6020820152604083015182811115612e2857600080fd5b612e3488828601612d4e565b6040830152509350612e4b91505060208401612d93565b90509250929050565b600082601f830112612e6557600080fd5b81516020612e75612739836126f5565b82815260059290921b84018101918181019086841115612e9457600080fd5b8286015b84811015612781578051612eab8161222e565b8352918301918301612e98565b600082601f830112612ec957600080fd5b81516020612ed9612739836126f5565b82815260069290921b84018101918181019086841115612ef857600080fd5b8286015b848110156127815760408189031215612f155760008081fd5b612f1d61261d565b8151815284820151612f2e8161222e565b81860152835291830191604001612efc565b600060208284031215612f5257600080fd5b81516001600160401b0380821115612f6957600080fd5b908301906101008286031215612f7e57600080fd5b612f86612667565b82518152612f9660208401612d43565b602082015260408301516040820152612fb160608401612d43565b60608201526080830151608082015260a083015182811115612fd257600080fd5b612fde87828601612e54565b60a08301525060c083015182811115612ff657600080fd5b61300287828601612eb8565b60c08301525060e08301518281111561301a57600080fd5b61302687828601612d4e565b60e08301525095945050505050565b600081518084526020808501945080840160005b838110156129735781516001600160a01b031687529582019590820190600101613049565b600081518084526020808501945080840160005b83811015612973576130a8878351805182526020908101516001600160a01b0316910152565b6040969096019590820190600101613082565b60006101008251845260018060a01b0360208401511660208501526040830151604085015260608301516130fa60608601826001600160a01b03169052565b506080830151608085015260a08301518160a086015261311c82860182613035565b91505060c083015184820360c0860152613136828261306e565b91505060e083015184820360e0860152611ae08282612bf7565b6001600160a01b038316815260406020820181905260009061127e908301846130bb565b6000808335601e1984360301811261318b57600080fd5b8301803591506001600160401b038211156131a557600080fd5b60200191503681900382131561241f57600080fd5b8481526001600160a01b0384166020820152606060408201819052600090612b389083018486612a54565b8181038181111561060f5761060f612ccf565b6020815260006108d360208301846130bb565b606081526000612bb160608301856130bb565b81516001600160a01b03168152602080830151908201526040810161060f565b8381526001600160a01b0383166020820152606060408201819052600090611ae090830184612bf7565b60006020828403121561327a57600080fd5b6108d382612d93565b60008251613295818460208701612bd3565b919091019291505056fea2646970667358221220586881dd1413fe17197100ceb55646481dae802ef65d37df603c3915f51a4b6364736f6c63430008120033",
        "storage": {
            "0x0000000000000000000000000000000000000000000000000000000000000000": "0x0000000000000000000000000000000000000000000000000000000000000001",
            "0x0000000000000000000000000000000000000000000000000000000000000001": "0x0000000000000000000000000000000000000000000000000000000000000001"
        },
        "nonce": 1
    },
    "0x618FEdD9A45a8C456812ecAAE70C671c6249DfaC": {
        "balance": "0x0",
        "nonce": 1
    }
}
```

The values above are taken from the `v1.0.0` [release artifacts](https://github.com/ava-labs/icm-contracts/releases/tag/v1.0.0). The contract address, deployed bytecode, and deployer address are unique per major release. All of the other values should remain the same.

## Deployed Addresses

| Contract              | Address                                        | Chain                    |
| --------------------- | ---------------------------------------------- | ------------------------ |
| `TeleporterMessenger` | **0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf** | All chains, all networks |
| `TeleporterRegistry`  | **0x7C43605E14F391720e1b37E49C78C4b03A488d98** | Mainnet C-Chain          |
| `TeleporterRegistry`  | **0xF86Cb19Ad8405AEFa7d09C778215D2Cb6eBfB228** | Fuji C-Chain             |

- Using [Nick's method](https://yamenmerhi.medium.com/nicks-method-ethereum-keyless-execution-168a6659479c#), `TeleporterMessenger` deploys at a universal address across all chains, varying with each `teleporter` Major release. **Compatibility exists only between same-version `TeleporterMessenger` instances.** See [TeleporterMessenger Contract Deployment](https://github.com/ava-labs/icm-contracts/blob/main/utils/contract-deployment/README.md) and [Deploy TeleporterMessenger to an Avalanche L1](#deploy-teleportermessenger-to-an-avalanche-l1) for more details.

- `TeleporterRegistry` can be deployed to any address. See [Deploy TeleporterRegistry to an Avalanche L1](#deploy-teleporterregistry-to-an-avalanche-l1) for details. The table above enumerates the canonical registry addresses on the Mainnet and Fuji C-Chains.

## A Note on Versioning

Release versions follow the [semver](https://semver.org/) convention of incompatible Major releases. A new Major version is released whenever the `TeleporterMessenger` bytecode is changed, and a new version of `TeleporterMessenger` is meant to be deployed. Due to the use of Nick's method to deploy the contract to the same address on all chains (see [TeleporterMessenger Contract Deployment](https://github.com/ava-labs/icm-contracts/blob/main/utils/contract-deployment/README.md) for details), this also means that new release versions would result in different `TeleporterMessenger` contract addresses. Minor and Patch versions may pertain to contract changes that do not change the `TeleporterMessenger` bytecode, or to changes in the test frameworks, and will only be included in tags.

## Upgradability

`TeleporterMessenger` is a non-upgradeable contract and can not be changed once it is deployed. This provides immutability to the contracts, and ensures that the contract's behavior at each address is unchanging. However, to allow for new features and potential bug fixes, new versions of `TeleporterMessenger` can be deployed to different addresses. The [TeleporterRegistry](https://github.com/ava-labs/icm-contracts/blob/main/contracts/teleporter/registry/TeleporterRegistry.sol) is used to keep track of the deployed versions of Teleporter, and to provide a standard interface for dApps to interact with the different `TeleporterMessenger` versions.

`TeleporterRegistry` **is not mandatory** for dApps built on top of ICM, but dApp's are recommended to leverage the registry to ensure they use the latest `TeleporterMessenger` version available. Another recommendation standard is to have a single canonical `TeleporterRegistry` for each Avalanche L1, and unlike the `TeleporterMessenger` contract, the registry does not need to be deployed to the same address on every chain. This means the registry does not need a Nick's method deployment, and can be at different contract addresses on different chains.

For more information on the registry and how to integrate with ICM contracts, see the [Upgradability doc](https://github.com/ava-labs/icm-contracts/blob/main/contracts/teleporter/registry/README.md).

## Deploy TeleporterMessenger to an Avalanche L1

From the root of the repo, the TeleporterMessenger contract can be deployed by calling

```bash
./scripts/deploy_teleporter.sh --version <version> --rpc-url <url> [OPTIONS]
```

Required arguments:

- `--version <version>` Specify the release version to deploy. These will all be of the form `v1.X.0`. Each `TeleporterMessenger` version can only send and receive messages from the **same** `TeleporterMessenger` version on another chain. You can see a list of released versions at https://github.com/ava-labs/icm-contracts/releases.
- `--rpc-url <url>` Specify the rpc url of the node to use.

Options:

- `--private-key <private_key>` Funds the deployer address with the account held by `<private_key>`

To ensure that `TeleporterMessenger` can be deployed to the same address on every EVM based chain, it uses [Nick's Method](https://yamenmerhi.medium.com/nicks-method-ethereum-keyless-execution-168a6659479c) to deploy from a static deployer address. Teleporter costs exactly `10eth` in the Avalanche L1's native gas token to deploy, which must be sent to the deployer address.

`deploy_teleporter.sh` will send the necessary native tokens to the deployer address if it is provided with a private key for an account with sufficient funds. Alternatively, the deployer address can be funded externally. The deployer address for each version can be found by looking up the appropriate version at https://github.com/ava-labs/icm-contracts/releases and downloading `TeleporterMessenger_Deployer_Address_<VERSION>.txt`.

Alternatively for new Avalanche L1s, the `TeleporterMessenger` contract can be directly included in the genesis file as documented [here](https://github.com/ava-labs/icm-contracts/blob/main/contracts/teleporter/README.md#teleporter-messenger-contract-deployment).

## Deploy TeleporterRegistry to an Avalanche L1

There should only be one canonical `TeleporterRegistry` deployed for each chain, but if one does not exist, it is recommended to deploy the registry so ICM contracts can always use the most recent `TeleporterMessenger` version available. The registry does not need to be deployed to the same address on every chain, and therefore does not need a Nick's method transaction. To deploy, run the following command from the root of the repository:

```bash
./scripts/deploy_registry.sh --version <version> --rpc-url <url> --private-key <private_key> [OPTIONS]
```

Required arguments:

- `--version <version>` Specify the release version to deploy. These will all be of the form `v1.X.0`.
- `--rpc-url <url>` Specify the rpc url of the node to use.
- `--private-key <private_key>` Funds the deployer address with the account held by `<private_key>`

`deploy_registry.sh` will deploy a new `TeleporterRegistry` contract for the intended release version, and will also have the corresponding `TeleporterMessenger` contract registered as the initial protocol version.

## Verify a Deployment of TeleporterMessenger

`TeleporterMessenger` can be verified on L1s using sourcify. `v1.0.0` of this repository must be checked out in order to match the source code properly.

```bash
git checkout v1.0.0
git submodule update --init --recursive
cd contracts

forge verify-contract 0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf \
 src/teleporter/TeleporterMessenger.sol:TeleporterMessenger \
 --chain-id <YOUR_CHAIN_ID> \
 --rpc-url <YOUR_RPC_URL>    \
 --verifier sourcify \
 --compiler-version v0.8.18+commit.87f61d96 \
 --num-of-optimizations 200 \
```

# Teleporter Avalanche L1s on Devnet (/docs/cross-chain/teleporter/teleporter-on-devnet)

---
title: Teleporter Avalanche L1s on Devnet
description: This how-to guide focuses on deploying Teleporter-enabled Avalanche L1s to a Devnet.
---

After this tutorial, you would have created a Devnet and deployed two Avalanche L1s in it, and have enabled them to cross-communicate with each other and with the C-Chain through Teleporter and the underlying Warp technology.

For more information on cross chain messaging through Teleporter and Warp, check:

- [Cross Chain References](/docs/cross-chain)

Note that currently only [Subnet-EVM](https://github.com/ava-labs/subnet-evm) and [Subnet-EVM-Based](/docs/virtual-machines/evm-l1-customization) virtual machines support Teleporter.

## Prerequisites

Before we begin, you will need to have:

- Created an AWS account and have an updated AWS `credentials` file in home directory with \[default\] profile

Note: the tutorial uses AWS hosts, but Devnets can also be created and operated in other supported cloud providers, such as GCP.

Create Avalanche L1s Configurations[​](#create-avalanche-l1s-configurations "Direct link to heading")
-----------------------------------------------------------------------------------------

For this section we will follow this [steps](/docs/tooling/cross-chain/teleporter-local-network#create-avalanche-l1s-configurations), to create two Teleporter-enabled Avalanche L1s, `<chain1>` and `<chain2>`.

Create a Devnet and Deploy an Avalanche L1 in It[​](#create-a-devnet-and-deploy-a-avalanche-l1-in-it "Direct link to heading")
-----------------------------------------------------------------------------------------------------------------

Let's use the `devnet wiz` command to create a devnet `<devnetName>` and deploy `<chain1>` in it.

The devnet will be created in the `us-east-1` region of AWS, and will consist of 5 validators only.

```
avalanche node devnet wiz <devnetName> <chain1> --aws --node-type default --region us-east-1 --num-validators 5 --num-apis 0 --enable-monitoring=false --default-validator-params 

Creating the devnet...

Creating new EC2 instance(s) on AWS...
...

Deploying [Avalanche L1] to Cluster <devnetName>
...

configuring AWM RElayer on host i-0f1815c016b555fcc

Setting the nodes as Avalanche L1 trackers
...

Setting up teleporter on Avalanche L1

Teleporter Messenger successfully deployed to Avalanche L1 (0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf)
Teleporter Registry successfully deployed to Avalanche L1 (0xb623C4495220C603D0A939D32478F55891a61750)
Teleporter Messenger successfully deployed to c-chain (0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf)
Teleporter Registry successfully deployed to c-chain (0x5DB9A7629912EBF95876228C24A848de0bfB43A9)

Starting AWM Relayer Service

setting AWM Relayer on host i-0f1815c016b555fcc to relay L1 chain1
updating configuration file ~/.avalanche-cli/nodes/i-0f1815c016b555fcc/services/awm-relayer/awm-relayer-config.json

Devnet <devnetName> is successfully created and is now validating blockchain chain1!

Avalanche L1 <chain1> RPC URL: http://67.202.23.231:9650/ext/bc/fqcM24LNb3kTV7KD1mAvUJXYy5XunwP8mrE44YuNwPjgZHY6p/rpc
 
✓ Cluster information YAML file can be found at ~/.avalanche-cli/nodes/inventories/<devnetName>/clusterInfo.yaml at local host
```

Notice some details here:

- Two smart contracts are deployed to the Avalanche L1: Teleporter Messenger and Teleporter Registry
- Both Teleporter smart contracts are also deployed to `C-Chain`
- [AWM Teleporter Relayer](https://github.com/ava-labs/icm-services/tree/main/relayer is installed and configured as a service into one of the nodes (A Relayer [listens](/docs/cross-chain/teleporter/overview#data-flow) for new messages being generated on a source Avalanche L1 and sends them to the destination Avalanche L1.)

CLI configures the Relayer to enable every Avalanche L1 to send messages to all other Avalanche L1s. If you add more Avalanche L1s to the Devnet, the Relayer will be automatically reconfigured.

Checking Devnet Configuration and Relayer Logs[​](#checking-devnet-configuration-and-relayer-logs "Direct link to heading")
---------------------------------------------------------------------------------------------------------------------------

Execute `node list` command to get a list of the devnet nodes:

```
avalanche node list

Cluster "<devnetName>" (Devnet)
  Node i-0f1815c016b555fcc (NodeID-91PGQ7keavfSV1XVFva2WsQXWLWZqqqKe) 67.202.23.231 [Validator,Relayer]
  Node i-026392a651571232c (NodeID-AkPyyTs9e9nPGShdSoxdvWYZ6X2zYoyrK) 52.203.183.68 [Validator]
  Node i-0d1b98d5d941d6002 (NodeID-ByEe7kuwtrPStmdMgY1JiD39pBAuFY2mS) 50.16.235.194 [Validator]
  Node i-0c291f54bb38c2984 (NodeID-8SE2CdZJExwcS14PYEqr3VkxFyfDHKxKq) 52.45.0.56 [Validator]
  Node i-049916e2f35231c29 (NodeID-PjQY7xhCGaB8rYbkXYddrr1mesYi29oFo) 3.214.163.110 [Validator]
```

Notice that, in this case, `i-0f1815c016b555fcc` was set as Relayer. This host contains a `systemd` service called `awm-relayer` that can be used to check the Relayer logs, and set the execution status.

To view the Relayer logs, the following command can be used:

```
avalanche node ssh i-0f1815c016b555fcc "journalctl -u awm-relayer --no-pager"

  [Node i-0f1815c016b555fcc (NodeID-91PGQ7keavfSV1XVFva2WsQXWLWZqqqKe) 67.202.23.231 [Validator,Relayer]]
Warning: Permanently added '67.202.23.231' (ED25519) to the list of known hosts.
-- Logs begin at Fri 2024-04-05 14:11:43 UTC, end at Fri 2024-04-05 14:30:24 UTC. --
Apr 05 14:15:06 ip-172-31-47-187 systemd[1]: Started AWM Relayer systemd service.
Apr 05 14:15:07 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:07.018Z","logger":"awm-relayer","caller":"main/main.go:66","msg":"Initializing awm-relayer"}
Apr 05 14:15:07 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:07.018Z","logger":"awm-relayer","caller":"main/main.go:71","msg":"Set config options."}
Apr 05 14:15:07 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:07.018Z","logger":"awm-relayer","caller":"main/main.go:78","msg":"Initializing destination clients"}
Apr 05 14:15:07 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:07.021Z","logger":"awm-relayer","caller":"main/main.go:97","msg":"Initializing app request network"}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.159Z","logger":"awm-relayer","caller":"main/main.go:309","msg":"starting metrics server...","port":9090}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.160Z","logger":"awm-relayer","caller":"main/main.go:251","msg":"Creating relayer","originBlockchainID":"fqcM24LNb3kTV7KD1mAvUJXYy5XunwP8mrE44YuNwPjgZHY6p"}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.160Z","logger":"awm-relayer","caller":"main/main.go:251","msg":"Creating relayer","originBlockchainID":"2EfJg86if9Ka5Ag73JRfoqWz4EGuFwtemaNf4XiBBpUW4YngS6"}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.160Z","logger":"awm-relayer","caller":"relayer/relayer.go:114","msg":"Creating relayer","subnetID":"11111111111111111111111111111111LpoYY","subnetIDHex":"0000000000000000000000000000000000000000000000000000000000000000","blockchainID":"2EfJg86if9Ka5Ag73JRfoqWz4EGuFwtemaNf4XiBBpUW4YngS6","blockchainIDHex":"a2b6b947cf2b9bf6df03c8caab08e38ab951d8b120b9c37265d9be01d86bb170"}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.160Z","logger":"awm-relayer","caller":"relayer/relayer.go:114","msg":"Creating relayer","subnetID":"giY8tswWgZmcAWzPkoNrmjjrykited7GJ9799SsFzTiq5a1ML","subnetIDHex":"5a2e2d87d74b4ec62fdd6626e7d36a44716484dfcc721aa4f2168e8a61af63af","blockchainID":"fqcM24LNb3kTV7KD1mAvUJXYy5XunwP8mrE44YuNwPjgZHY6p","blockchainIDHex":"582fc7bd55472606c260668213bf1b6d291df776c9edf7e042980a84cce7418a"}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.171Z","logger":"awm-relayer","caller":"evm/subscriber.go:247","msg":"Successfully subscribed","blockchainID":"2EfJg86if9Ka5Ag73JRfoqWz4EGuFwtemaNf4XiBBpUW4YngS6"}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.171Z","logger":"awm-relayer","caller":"relayer/relayer.go:161","msg":"processed-missed-blocks set to false, starting processing from chain head","blockchainID":"2EfJg86if9Ka5Ag73JRfoqWz4EGuFwtemaNf4XiBBpUW4YngS6"}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.172Z","logger":"awm-relayer","caller":"relayer/message_relayer.go:662","msg":"Updating latest processed block in database","relayerID":"0xea06381426934ec1800992f41615b9d362c727ad542f6351dbfa7ad2849a35bf","latestBlock":6}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.173Z","logger":"awm-relayer","caller":"relayer/message_relayer.go:662","msg":"Updating latest processed block in database","relayerID":"0x175e14327136d57fe22d4bdd295ff14bea8a7d7ab1884c06a4d9119b9574b9b3","latestBlock":6}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.173Z","logger":"awm-relayer","caller":"main/main.go:272","msg":"Created relayer","blockchainID":"2EfJg86if9Ka5Ag73JRfoqWz4EGuFwtemaNf4XiBBpUW4YngS6"}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.173Z","logger":"awm-relayer","caller":"main/main.go:295","msg":"Relayer initialized. Listening for messages to relay.","originBlockchainID":"2EfJg86if9Ka5Ag73JRfoqWz4EGuFwtemaNf4XiBBpUW4YngS6"}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.178Z","logger":"awm-relayer","caller":"evm/subscriber.go:247","msg":"Successfully subscribed","blockchainID":"fqcM24LNb3kTV7KD1mAvUJXYy5XunwP8mrE44YuNwPjgZHY6p"}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.178Z","logger":"awm-relayer","caller":"relayer/relayer.go:161","msg":"processed-missed-blocks set to false, starting processing from chain head","blockchainID":"fqcM24LNb3kTV7KD1mAvUJXYy5XunwP8mrE44YuNwPjgZHY6p"}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.179Z","logger":"awm-relayer","caller":"relayer/message_relayer.go:662","msg":"Updating latest processed block in database","relayerID":"0xe584ccc0df44506255811f6b54375e46abd5db40a4c84fd9235a68f7b69c6f06","latestBlock":6}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.179Z","logger":"awm-relayer","caller":"relayer/message_relayer.go:662","msg":"Updating latest processed block in database","relayerID":"0x70f14d33bde4716928c5c4723d3969942f9dfd1f282b64ffdf96f5ac65403814","latestBlock":6}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.180Z","logger":"awm-relayer","caller":"main/main.go:272","msg":"Created relayer","blockchainID":"fqcM24LNb3kTV7KD1mAvUJXYy5XunwP8mrE44YuNwPjgZHY6p"}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.180Z","logger":"awm-relayer","caller":"main/main.go:295","msg":"Relayer initialized. Listening for messages to relay.","originBlockchainID":"fqcM24LNb3kTV7KD1mAvUJXYy5XunwP8mrE44YuNwPjgZHY6p"}
```

Deploying the Second Avalanche L1[​](#deploying-the-second-avalanche-l1 "Direct link to heading")
-------------------------------------------------------------------------------------

Let's use the `devnet wiz` command again to deploy `<chain2>`.

When deploying Avalanche L1 `<chain2>`, the two Teleporter contracts will not be deployed to C-Chain in Local Network as they have already been deployed when we deployed the first Avalanche L1.

```
avalanche node devnet wiz <devnetName> <chain2> --default-validator-params 

Adding Avalanche L1 into existing devnet <devnetName>...
...

Deploying [chain2] to Cluster <devnetName>
...

Stopping AWM Relayer Service

Setting the nodes as Avalanche L1 trackers
...

Setting up teleporter on Avalanche L1

Teleporter Messenger successfully deployed to Avalanche L1 (0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf)
Teleporter Registry successfully deployed to Avalanche L1 (0xb623C4495220C603D0A939D32478F55891a61750)
Teleporter Messenger has already been deployed to c-chain

Starting AWM Relayer Service

setting AWM Relayer on host i-0f1815c016b555fcc to relay L1 chain2
updating configuration file ~/.avalanche-cli/nodes/i-0f1815c016b555fcc/services/awm-relayer/awm-relayer-config.json

Devnet <devnetName> is now validating Avalanche L1 chain2

Avalanche L1 <chain2> RPC URL: http://67.202.23.231:9650/ext/bc/7gKt6evRnkA2uVHRfmk9WrH3dYZH9gEVVxDAknwtjvtaV3XuQ/rpc

✓ Cluster information YAML file can be found at ~/.avalanche-cli/nodes/inventories/<devnetName>/clusterInfo.yaml at local host
```

Verify Teleporter Is Successfully Set Up[​](#verify-teleporter-is-successfully-set-up "Direct link to heading")
---------------------------------------------------------------------------------------------------------------

To verify that Teleporter is successfully, let's send a couple of cross messages:

```
avalanche teleporter msg C-Chain chain1 "Hello World" --cluster <devnetName>

Delivering message "this is a message" to source Avalanche L1 "C-Chain" (2EfJg86if9Ka5Ag73JRfoqWz4EGuFwtemaNf4XiBBpUW4YngS6)
Waiting for message to be received at destination Avalanche L1 "chain1" (fqcM24LNb3kTV7KD1mAvUJXYy5XunwP8mrE44YuNwPjgZHY6p)
Message successfully Teleported!
```

```
avalanche teleporter msg chain2 chain1 "Hello World" --cluster <devnetName>

Delivering message "this is a message" to source Avalanche L1 "chain2" (29WP91AG7MqPUFEW2YwtKnsnzVrRsqcWUpoaoSV1Q9DboXGf4q)
Waiting for message to be received at destination Avalanche L1 "chain1" (fqcM24LNb3kTV7KD1mAvUJXYy5XunwP8mrE44YuNwPjgZHY6p)
Message successfully Teleported!
```

You have Teleport-ed your first message in the Devnet!

Obtaining Information on Teleporter Deploys[​](#obtaining-information-on-teleporter-deploys "Direct link to heading")
---------------------------------------------------------------------------------------------------------------------

### Obtaining Avalanche L1 Information[​](#obtaining-avalanche-l1-information "Direct link to heading")

By executing `blockchain describe` on a Teleporter enabled Avalanche L1, the following relevant information can be found:

- Blockchain RPC URL
- Blockchain ID in cb58 format
- Blockchain ID in plain hex format
- Teleporter Messenger address
- Teleporter Registry address

Let's get the information for `<chain1>`:

```
avalanche blockchain describe <chain1>

 _____       _        _ _
|  __ \     | |      (_) |
| |  | | ___| |_ __ _ _| |___
| |  | |/ _ \ __/ _  | | / __|
| |__| |  __/ || (_| | | \__ \
|_____/ \___|\__\__,_|_|_|___/

+--------------------------------+----------------------------------------------------------------------------------------+
|           PARAMETER            |                               VALUE                                                    |
+--------------------------------+----------------------------------------------------------------------------------------+
| Blockchain Name                    | Avalanche L1                                                                            |
+--------------------------------+----------------------------------------------------------------------------------------+
| ChainID                        | 1                                                                                      |
+--------------------------------+----------------------------------------------------------------------------------------+
| Token Name                     | TOKEN1 Token                                                                           |
+--------------------------------+----------------------------------------------------------------------------------------+
| Token Symbol                   | TOKEN1                                                                                 |
+--------------------------------+----------------------------------------------------------------------------------------+
| VM Version                     | v0.6.3                                                                                 |
+--------------------------------+----------------------------------------------------------------------------------------+
| VM ID                          | srEXiWaHjFEgKSgK2zBgnWQUVEy2MZA7UUqjqmBSS7MZYSCQ5                                      |
+--------------------------------+----------------------------------------------------------------------------------------+
| Cluster <devnetName> SubnetID  | giY8tswWgZmcAWzPkoNrmjjrykited7GJ9799SsFzTiq5a1ML                                      |
+--------------------------------+----------------------------------------------------------------------------------------+
| Cluster <devnetName> RPC URL   | http://67.202.23.231:9650/ext/bc/fqcM24LNb3kTV7KD1mAvUJXYy5XunwP8mrE44YuNwPjgZHY6p/rpc |
+--------------------------------+----------------------------------------------------------------------------------------+
| Cluster <devnetName>           | fqcM24LNb3kTV7KD1mAvUJXYy5XunwP8mrE44YuNwPjgZHY6p                                      |
| BlockchainID                   |                                                                                        |
+                                +----------------------------------------------------------------------------------------+
|                                | 0x582fc7bd55472606c260668213bf1b6d291df776c9edf7e042980a84cce7418a                     |
|                                |                                                                                        |
+--------------------------------+----------------------------------------------------------------------------------------+
| Cluster <devnetName> Teleporter| 0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf                                             |
| Messenger Address              |                                                                                        |
+--------------------------------+----------------------------------------------------------------------------------------+
| Cluster <devnetName> Teleporter| 0xb623C4495220C603D0A939D32478F55891a61750                                             |
| Registry Address               |                                                                                        |
+--------------------------------+----------------------------------------------------------------------------------------+

...
```

### Obtaining C-Chain Information[​](#obtaining-c-chain-information "Direct link to heading")

Similar information can be found for C-Chain by using `primary describe`:

```
avalanche primary describe --cluster <devnetName>

   _____       _____ _           _         _____
  / ____|     / ____| |         (_)       |  __ \
 | |   ______| |    | |__   __ _ _ _ __   | |__) |_ _ _ __ __ _ _ __ ___  ___
 | |  |______| |    | '_ \ / _  | | '_ \  |  ___/ _  | '__/ _  | '_   _ \/ __|
 | |____     | |____| | | | (_| | | | | | | |  | (_| | | | (_| | | | | | \__ \
  \_____|     \_____|_| |_|\__,_|_|_| |_| |_|   \__,_|_|  \__,_|_| |_| |_|___/

+------------------------------+--------------------------------------------------------------------+
|          PARAMETER           |                               VALUE                                |
+------------------------------+--------------------------------------------------------------------+
| RPC URL                      | http://67.202.23.231:9650/ext/bc/C/rpc                             |
+------------------------------+--------------------------------------------------------------------+
| EVM Chain ID                 | 43112                                                              |
+------------------------------+--------------------------------------------------------------------+
| TOKEN SYMBOL                 | AVAX                                                               |
+------------------------------+--------------------------------------------------------------------+
| Address                      | 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC                         |
+------------------------------+--------------------------------------------------------------------+
| Balance                      | 49999489.815751426                                                 |
+------------------------------+--------------------------------------------------------------------+
| Private Key                  | 56289e99c94b6912bfc12adc093c9b51124f0dc54ac7a766b2bc5ccf558d8027   |
+------------------------------+--------------------------------------------------------------------+
| BlockchainID                 | 2EfJg86if9Ka5Ag73JRfoqWz4EGuFwtemaNf4XiBBpUW4YngS6                 |
+                              +--------------------------------------------------------------------+
|                              | 0xa2b6b947cf2b9bf6df03c8caab08e38ab951d8b120b9c37265d9be01d86bb170 |
+------------------------------+--------------------------------------------------------------------+
| ICM Messenger Address        | 0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf                         |
+------------------------------+--------------------------------------------------------------------+
| ICM Registry Address         | 0x5DB9A7629912EBF95876228C24A848de0bfB43A9                         |
+------------------------------+--------------------------------------------------------------------+
```

Controlling Relayer Execution[​](#controlling-relayer-execution "Direct link to heading")
-----------------------------------------------------------------------------------------

CLI provides two commands to remotely control Relayer execution:

```
avalanche interchain relayer stop --cluster <devnetName>
✓ Remote AWM Relayer on i-0f1815c016b555fcc successfully stopped
```

```
avalanche interchain relayer start --cluster <devnetName>
✓ Remote AWM Relayer on i-0f1815c016b555fcc successfully started

```



# Teleporter Avalanche L1s on Local Network (/docs/cross-chain/teleporter/teleporter-on-local-network)

---
title: Teleporter Avalanche L1s on Local Network
---

This how-to guide focuses on deploying Teleporter-enabled Avalanche L1s to a local Avalanche network.

After this tutorial, you would have created and deployed two Avalanche L1s to the local network and have enabled them to cross-communicate with each other and with the local C-Chain (through Teleporter and the underlying Warp technology.)

Note that currently only [Subnet-EVM](https://github.com/ava-labs/subnet-evm) and [Subnet-EVM-Based](/docs/virtual-machines/evm-l1-customization) virtual machines support Teleporter.

## Prerequisites

- [Avalanche-CLI installed](/docs/tooling/get-avalanche-cli)

## Create Avalanche L1 Configurations

Let's create an Avalanche L1 called `<chain1>` with the latest Subnet-EVM version, a chain ID of 1, TOKEN1 as the token name, and with default Subnet-EVM parameters (more information regarding Avalanche L1 creation can be found [here](/docs/tooling/create-avalanche-l1#create-your-avalanche-l1-configuration)):

```
avalanche blockchain create <chain1> --evm --latest\
    --evm-chain-id 1 --evm-token TOKEN1 --evm-defaults

creating genesis for <blockchain chain1>
configuring airdrop to stored key "subnet_<chain1>_airdrop" with address 0x0EF8151A3e6ad1d4e17C8ED4128b20EB5edc58B1
loading stored key "cli-teleporter-deployer" for teleporter deploys
  (evm address, genesis balance) = (0xE932784f56774879e03F3624fbeC6261154ec711, 600000000000000000000)
using latest teleporter version (v1.0.0)
✓ Successfully created Avalanche L1 configuration
```

Notice that by default, Teleporter is enabled and a stored key is created to fund Teleporter related operations (that is deploy Teleporter smart contracts, fund Teleporter Relayer).

To disable Teleporter in your Avalanche L1, use the flag `--teleporter=false` when creating the Avalanche L1.

To disable Relayer in your Avalanche L1, use the flag `--relayer=false` when creating the Avalanche L1.

Now let's create a second Avalanche L1 called `<chain2>`, with similar settings:

```
avalanche blockchain create <chain2> --evm --latest\

creating genesis for <blockchain chain2>
configuring airdrop to stored key "subnet_<chain2>_airdrop" with address 0x0EF815FFFF6ad1d4e17C8ED4128b20EB5edAABBB
loading stored key "cli-teleporter-deployer" for teleporter deploys
  (evm address, genesis balance) = (0xE932784f56774879e03F3624fbeC6261154ec711, 600000000000000000000)
using latest teleporter version (v1.0.0)
✓ Successfully created Avalanche L1 configuration
```

## Deploy the Avalanche L1s to Local Network

Let's deploy `<chain1>`:

```
avalanche blockchain deploy <chain1> --local


Deploying [<chain1>] to Local Network
Backend controller started, pid: 149427, output at: ~/.avalanche-cli/runs/server_20240229_165923/avalanche-cli-backend.log

Booting Network. Wait until healthy...
Node logs directory: ~/.avalanche-cli/runs/network_20240229_165923/node<i>/logs
Network ready to use.

Deploying Blockchain. Wait until network acknowledges...

Teleporter Messenger successfully deployed to c-chain (0xF7cBd95f1355f0d8d659864b92e2e9fbfaB786f7)
Teleporter Registry successfully deployed to c-chain (0x17aB05351fC94a1a67Bf3f56DdbB941aE6c63E25)

Teleporter Messenger successfully deployed to <chain1> (0xF7cBd95f1355f0d8d659864b92e2e9fbfaB786f7)
Teleporter Registry successfully deployed to <chain1> (0x9EDc4cB4E781413b1b82CC3A92a60131FC111F58)

Using latest awm-relayer version (v1.1.0)
Executing AWM-Relayer...

Blockchain ready to use. Local network node endpoints:
+-------+-----------+------------------------------------------------------------------------------------+--------------------------------------------+
| NODE  |     VM    |                                        URL                                         |                  ALIAS URL                 |
+-------+-----------+------------------------------------------------------------------------------------+--------------------------------------------+
| node1 | <chain1> | http://127.0.0.1:9650/ext/bc/MzN4AbtFzQ3eKqPhFaDpwCMJmagciWSCgghkZx6YeC6jRdvb6/rpc | http://127.0.0.1:9650/ext/bc/<chain1>/rpc |
+-------+-----------+------------------------------------------------------------------------------------+--------------------------------------------+
| node2 | <chain1> | http://127.0.0.1:9652/ext/bc/MzN4AbtFzQ3eKqPhFaDpwCMJmagciWSCgghkZx6YeC6jRdvb6/rpc | http://127.0.0.1:9652/ext/bc/<chain1>/rpc |
+-------+-----------+------------------------------------------------------------------------------------+--------------------------------------------+
| node3 | <chain1> | http://127.0.0.1:9654/ext/bc/MzN4AbtFzQ3eKqPhFaDpwCMJmagciWSCgghkZx6YeC6jRdvb6/rpc | http://127.0.0.1:9654/ext/bc/<chain1>/rpc |
+-------+-----------+------------------------------------------------------------------------------------+--------------------------------------------+
| node4 | <chain1> | http://127.0.0.1:9656/ext/bc/MzN4AbtFzQ3eKqPhFaDpwCMJmagciWSCgghkZx6YeC6jRdvb6/rpc | http://127.0.0.1:9656/ext/bc/<chain1>/rpc |
+-------+-----------+------------------------------------------------------------------------------------+--------------------------------------------+
| node5 | <chain1> | http://127.0.0.1:9658/ext/bc/MzN4AbtFzQ3eKqPhFaDpwCMJmagciWSCgghkZx6YeC6jRdvb6/rpc | http://127.0.0.1:9658/ext/bc/<chain1>/rpc |
+-------+-----------+------------------------------------------------------------------------------------+--------------------------------------------+

Browser Extension connection details (any node URL from above works):
RPC URL:          http://127.0.0.1:9650/ext/bc/MzN4AbtFzQ3eKqPhFaDpwCMJmagciWSCgghkZx6YeC6jRdvb6/rpc
Funded address:   0x0EF8151A3e6ad1d4e17C8ED4128b20EB5edc58B1 with 1000000 (10^18) - private key: 16289399c9466912ffffffdc093c9b51124f0dc54ac7a766b2bc5ccf558d8eee
Network name:     <chain1>
Chain ID:         1
Currency Symbol:  TOKEN1
```

Notice some details here:

- Two smart contracts are deployed to each Avalanche L1: Teleporter Messenger and Teleporter Registry
- Both Teleporter smart contracts are also deployed to `C-Chain` in the Local Network
- [AWM Teleporter Relayer](https://github.com/ava-labs/icm-services/tree/main/relayer) is installed, configured and executed in background (A Relayer [listens](/docs/cross-chain/teleporter/overview#data-flow) for new messages being generated on a source Avalanche L1 and sends them to the destination Avalanche L1.)

CLI configures the Relayer to enable every Avalanche L1 to send messages to all other Avalanche L1s. If you add more Avalanche L1s, the Relayer will be automatically reconfigured.

When deploying Avalanche L1 `<chain2>`, the two Teleporter contracts will not be deployed to C-Chain in Local Network as they have already been deployed when we deployed the first Avalanche L1.

```
avalanche blockchain deploy <chain2> --local

Deploying [<chain2>] to Local Network

Deploying Blockchain. Wait until network acknowledges...

Teleporter Messenger has already been deployed to c-chain

Teleporter Messenger successfully deployed to <chain2> (0xF7cBd95f1355f0d8d659864b92e2e9fbfaB786f7)
Teleporter Registry successfully deployed to <chain2> (0x9EDc4cB4E781413b1b82CC3A92a60131FC111F58)

Using latest awm-relayer version (v1.1.0)
Executing AWM-Relayer...

Blockchain ready to use. Local network node endpoints:
+-------+-----------+-------------------------------------------------------------------------------------+--------------------------------------------+
| NODE  |     VM    |                                         URL                                         |                  ALIAS URL                 |
+-------+-----------+-------------------------------------------------------------------------------------+--------------------------------------------+
| node1 | <chain2> | http://127.0.0.1:9650/ext/bc/2tVGwEQmeXtdnFURW1YSq5Yf4jbJPfTBfVcu68KWHdHe5e5gX5/rpc | http://127.0.0.1:9650/ext/bc/<chain2>/rpc |
+-------+-----------+-------------------------------------------------------------------------------------+--------------------------------------------+
| node1 | <chain1> | http://127.0.0.1:9650/ext/bc/MzN4AbtFzQ3eKqPhFaDpwCMJmagciWSCgghkZx6YeC6jRdvb6/rpc  | http://127.0.0.1:9650/ext/bc/<chain1>/rpc |
+-------+-----------+-------------------------------------------------------------------------------------+--------------------------------------------+
| node2 | <chain2> | http://127.0.0.1:9652/ext/bc/2tVGwEQmeXtdnFURW1YSq5Yf4jbJPfTBfVcu68KWHdHe5e5gX5/rpc | http://127.0.0.1:9652/ext/bc/<chain2>/rpc |
+-------+-----------+-------------------------------------------------------------------------------------+--------------------------------------------+
| node2 | <chain1> | http://127.0.0.1:9652/ext/bc/MzN4AbtFzQ3eKqPhFaDpwCMJmagciWSCgghkZx6YeC6jRdvb6/rpc  | http://127.0.0.1:9652/ext/bc/<chain1>/rpc |
+-------+-----------+-------------------------------------------------------------------------------------+--------------------------------------------+
| node3 | <chain2> | http://127.0.0.1:9654/ext/bc/2tVGwEQmeXtdnFURW1YSq5Yf4jbJPfTBfVcu68KWHdHe5e5gX5/rpc | http://127.0.0.1:9654/ext/bc/<chain2>/rpc |
+-------+-----------+-------------------------------------------------------------------------------------+--------------------------------------------+
| node3 | <chain1> | http://127.0.0.1:9654/ext/bc/MzN4AbtFzQ3eKqPhFaDpwCMJmagciWSCgghkZx6YeC6jRdvb6/rpc  | http://127.0.0.1:9654/ext/bc/<chain1>/rpc |
+-------+-----------+-------------------------------------------------------------------------------------+--------------------------------------------+
| node4 | <chain2> | http://127.0.0.1:9656/ext/bc/2tVGwEQmeXtdnFURW1YSq5Yf4jbJPfTBfVcu68KWHdHe5e5gX5/rpc | http://127.0.0.1:9656/ext/bc/<chain2>/rpc |
+-------+-----------+-------------------------------------------------------------------------------------+--------------------------------------------+
| node4 | <chain1> | http://127.0.0.1:9656/ext/bc/MzN4AbtFzQ3eKqPhFaDpwCMJmagciWSCgghkZx6YeC6jRdvb6/rpc  | http://127.0.0.1:9656/ext/bc/<chain1>/rpc |
+-------+-----------+-------------------------------------------------------------------------------------+--------------------------------------------+
| node5 | <chain1> | http://127.0.0.1:9658/ext/bc/MzN4AbtFzQ3eKqPhFaDpwCMJmagciWSCgghkZx6YeC6jRdvb6/rpc  | http://127.0.0.1:9658/ext/bc/<chain1>/rpc |
+-------+-----------+-------------------------------------------------------------------------------------+--------------------------------------------+
| node5 | <chain2> | http://127.0.0.1:9658/ext/bc/2tVGwEQmeXtdnFURW1YSq5Yf4jbJPfTBfVcu68KWHdHe5e5gX5/rpc | http://127.0.0.1:9658/ext/bc/<chain2>/rpc |
+-------+-----------+-------------------------------------------------------------------------------------+--------------------------------------------+

Browser Extension connection details (any node URL from above works):
RPC URL:          http://127.0.0.1:9650/ext/bc/2tVGwEQmeXtdnFURW1YSq5Yf4jbJPfTBfVcu68KWHdHe5e5gX5/rpc
Funded address:   0x0EF815FFFF6ad1d4e17C8ED4128b20EB5edAABBB with 1000000 (10^18) - private key: 56289e99c94b6912bfc12adc093c9b51124f0dc54ac7a766b2bc5ccf558d8027
Network name:     <chain2>
Chain ID:         2
Currency Symbol:  TOKEN2
```

## Verify Teleporter Is Successfully Set Up

To verify that Teleporter is successfully, let's send a couple of cross messages:

```
avalanche teleporter msg C-Chain chain1 "Hello World" --local

Delivering message "this is a message" to source Avalanche L1 "C-Chain"
Waiting for message to be received at destination Avalanche L1 Avalanche L1 "chain1"
Message successfully Teleported!
```

```
avalanche teleporter msg chain2 chain1 "Hello World" --local

Delivering message "this is a message" to source Avalanche L1 "chain2"
Waiting for message to be received at destination Avalanche L1 Avalanche L1 "chain1"
Message successfully Teleported!
```

You have Teleport-ed your first message in the Local Network!

Relayer related logs can be found at `~/.avalanche-cli/runs/awm-relayer.log`, and Relayer configuration can be found at `~/.avalanche-cli/runs/awm-relayer-config.json`

Obtaining Information on Teleporter Deploys[​](#obtaining-information-on-teleporter-deploys "Direct link to heading")
---------------------------------------------------------------------------------------------------------------------

### Obtaining Avalanche L1 Information[​](#obtaining-avalanche-l1-information "Direct link to heading")

By executing `blockchain describe` on a Teleporter enabled Avalanche L1, the following relevant information can be found:

- Blockchain RPC URL
- Blockchain ID in cb58 format
- Blockchain ID in plain hex format
- Teleporter Messenger address
- Teleporter Registry address

Let's get the information for `<chain1>`:

```
avalanche blockchain describe <chain1>

 _____       _        _ _
|  __ \     | |      (_) |
| |  | | ___| |_ __ _ _| |___
| |  | |/ _ \ __/ _  | | / __|
| |__| |  __/ || (_| | | \__ \
|_____/ \___|\__\__,_|_|_|___/
+--------------------------------+-------------------------------------------------------------------------------------+
|           PARAMETER            |                               VALUE                                                 |
+--------------------------------+-------------------------------------------------------------------------------------+
| Avalanche L1 Name                    | chain1                                                                             |
+--------------------------------+-------------------------------------------------------------------------------------+
| ChainID                        | 1                                                                                   |
+--------------------------------+-------------------------------------------------------------------------------------+
| Token Name                     | TOKEN1 Token                                                                        |
+--------------------------------+-------------------------------------------------------------------------------------+
| Token Symbol                   | TOKEN1                                                                              |
+--------------------------------+-------------------------------------------------------------------------------------+
| VM Version                     | v0.6.3                                                                              |
+--------------------------------+-------------------------------------------------------------------------------------+
| VM ID                          | srEXiWaHjFEgKSgK2zBgnWQUVEy2MZA7UUqjqmBSS7MZYSCQ5                                   |
+--------------------------------+-------------------------------------------------------------------------------------+
| Local Network SubnetID         | 2CZP2ndbQnZxTzGuZjPrJAm5b4s2K2Bcjh8NqWoymi8NZMLYQk                                  |
+--------------------------------+-------------------------------------------------------------------------------------+
| Local Network RPC URL          | http://127.0.0.1:9650/ext/bc/2cFWSgGkmRrmKtbPkB8yTpnq9ykK3Dc2qmxphwYtiGXCvnSwg8/rpc |
+--------------------------------+-------------------------------------------------------------------------------------+
| Local Network BlockchainID     | 2cFWSgGkmRrmKtbPkB8yTpnq9ykK3Dc2qmxphwYtiGXCvnSwg8                                  |
+                                +-------------------------------------------------------------------------------------+
|                                | 0xd3bc5f71e6946d17c488d320cd1f6f5337d9dce75b3fac5023433c4634b6e91e                  |
+--------------------------------+-------------------------------------------------------------------------------------+
| Local Network Teleporter       | 0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf                                          |
| Messenger Address              |                                                                                     |
+--------------------------------+-------------------------------------------------------------------------------------+
| Local Network Teleporter       | 0xbD9e8eC38E43d34CAB4194881B9BF39d639D7Bd3                                          |
| Registry Address               |                                                                                     |
+--------------------------------+-------------------------------------------------------------------------------------+

...
```

### Obtaining C-Chain Information[​](#obtaining-c-chain-information "Direct link to heading")

Similar information can be found for C-Chain by using `primary describe`:

```
avalanche primary describe --local

   _____       _____ _           _         _____
  / ____|     / ____| |         (_)       |  __ \
 | |   ______| |    | |__   __ _ _ _ __   | |__) |_ _ _ __ __ _ _ __ ___  ___
 | |  |______| |    | '_ \ / _  | | '_ \  |  ___/ _  | '__/ _  | '_   _ \/ __|
 | |____     | |____| | | | (_| | | | | | | |  | (_| | | | (_| | | | | | \__ \
  \_____|     \_____|_| |_|\__,_|_|_| |_| |_|   \__,_|_|  \__,_|_| |_| |_|___/

+------------------------------+--------------------------------------------------------------------+
|          PARAMETER           |                               VALUE                                |
+------------------------------+--------------------------------------------------------------------+
| RPC URL                      | http://127.0.0.1:9650/ext/bc/C/rpc                                 |
+------------------------------+--------------------------------------------------------------------+
| EVM Chain ID                 | 43112                                                              |
+------------------------------+--------------------------------------------------------------------+
| TOKEN SYMBOL                 | AVAX                                                               |
+------------------------------+--------------------------------------------------------------------+
| Address                      | 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC                         |
+------------------------------+--------------------------------------------------------------------+
| Balance                      | 49999489.829989485                                                 |
+------------------------------+--------------------------------------------------------------------+
| Private Key                  | 56289e99c94b6912bfc12adc093c9b51124f0dc54ac7a766b2bc5ccf558d8027   |
+------------------------------+--------------------------------------------------------------------+
| BlockchainID                 | 2JeJDKL9Bvn1vLuuPL1DpUccBCVUh7iRnkv3a5pV9kJW5HbuQz                 |
+                              +--------------------------------------------------------------------+
|                              | 0xabc1bd35cb7313c8a2b62980172e6d7ef42aaa532c870499a148858b0b6a34fd |
+------------------------------+--------------------------------------------------------------------+
| ICM Messenger Address        | 0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf                         |
+------------------------------+--------------------------------------------------------------------+
| ICM Registry Address         | 0x17aB05351fC94a1a67Bf3f56DdbB941aE6c63E25                         |
+------------------------------+--------------------------------------------------------------------+
```

Controlling Relayer Execution[​](#controlling-relayer-execution "Direct link to heading")
-----------------------------------------------------------------------------------------

Besides having the option to not use a Relayer at Avalanche L1 creation time, the Relayer can be stopped and restarted on used request.

To stop the Relayer:

```
avalanche interchain relayer stop --local

✓ Local AWM Relayer successfully stopped
```

To start it again:

```
avalanche interchain relayer start --local

using latest awm-relayer version (v1.1.0)
Executing AWM-Relayer...
✓ Local AWM Relayer successfully started
Logs can be found at ~/.avalanche-cli/runs/awm-relayer.log

```



# Upgradeability (/docs/cross-chain/teleporter/upgradeability)

---
title: "Upgradeability"
description: "The TeleporterMessenger contract is non-upgradable. However, there could still be new versions of TeleporterMessenger contracts needed to be deployed in the future."
edit_url: https://github.com/ava-labs/teleporter/edit/main/contracts/teleporter/registry/README.md
---

# TeleporterMessenger Contracts Upgradability

## Overview

The `TeleporterMessenger` contract is non-upgradable, once a version of the contract is deployed it cannot be changed. This is with the intention of preventing any changes to the deployed contract that could potentially introduce bugs or vulnerabilities.

However, there could still be new versions of `TeleporterMessenger` contracts needed to be deployed in the future. `TeleporterRegistry` provides applications that use a `TeleporterMessenger` instance a minimal step process to integrate with new versions of `TeleporterMessenger`.

The `TeleporterRegistry` maintains a mapping of `TeleporterMessenger` contract versions to their addresses. When a new `TeleporterMessenger` version is deployed, its address can be added to the `TeleporterRegistry`. The `TeleporterRegistry` can only be updated through an ICM off-chain message that meets the following requirements:

- `sourceChainAddress` must match `VALIDATORS_SOURCE_ADDRESS = address(0)`
  - The zero address can only be set as the source chain address by an ICM off-chain message, and cannot be set by an on-chain ICM message.
- `sourceBlockchainID` must match the blockchain ID that the registry is deployed on
- `destinationBlockchainID` must match the blockchain ID that the registry is deployed on
- `destinationAddress` must match the address of the registry

In the `TeleporterRegistry` contract, the `latestVersion` state variable returns the highest version number that has been registered in the registry. The `getLatestTeleporter` function returns the `ITeleporterMessenger` that is registered with the corresponding version.

## Design

- `TeleporterRegistry` is deployed on each blockchain that needs to keep track of `TeleporterMessenger` contract versions.
- The registry's contract address on each blockchain does not need to be the same, and does not require a Nick's method transaction for deployment.
- Each registry's mapping of version to contract address is independent of registries on other blockchains, and chains can decide on their own registry mapping entries.
- Each blockchain should only have one canonical `TeleporterRegistry` contract.
- `TeleporterRegistry` contract can be initialized through a list of initial registry entries, which are `TeleporterMessenger` contract versions and their addresses.
- The registry keeps track of a mapping of `TeleporterMessenger` contract versions to their addresses, and vice versa, a mapping of `TeleporterMessenger` contract addresses to their versions.
- Version zero is an invalid version, and is used to indicate that a `TeleporterMessenger` contract has not been registered yet.
- Once a version number is registered in the registry, it cannot be changed, but a previous registered protocol address can be added to the registry with a new version. This is especially important in the case of a rollback to a previous `TeleporterMessenger` version, in which case the previous `TeleporterMessenger` contract address would need to be registered with a new version to the registry.

## Integrating `TeleporterRegistryApp` into a dApp

<div align="center">
  <img src="https://raw.githubusercontent.com/ava-labs/teleporter/main/contracts/teleporter/registry/upgrade-uml.png" /> alt="Upgrade UML diagram"/>
</div>

[TeleporterRegistryApp](https://github.com/ava-labs/teleporter/blob/main/contracts/teleporter/registry/TeleporterRegistryApp.sol) is an abstract contract that helps integrate the `TeleporterRegistry` into ICM contracts. To support upgradeable contracts, there is also a corresponding `TeleporterRegistryAppUpgradeable` contract that is upgrade compatible. By inheriting from `TeleporterRegistryApp`, dApps get:

- Ability to send ICM messages through the latest version of the `TeleporterMessenger` contract registered in the Teleporter registry. (The dApp can also override this to use a specific version of the `TeleporterMessenger` contract.)
- `minTeleporterVersion` management that allows the dApp to specify the minimum `TeleporterMessenger` version that can send messages to the dApp.
- Access controlled utility to update the `minTeleporterVersion`
- Access controlled utility to pause/unpause interaction with specific `TeleporterMessenger` addresses.

To integrate `TeleporterRegistryApp` with a dApp, pass in the Teleporter registry address inside the constructor. For upgradeable contracts `TeleporterRegistryAppUpgradeable` can be inherited, and the derived contract's `initializer` function should call either `__TeleporterRegistryApp_init` or `__TeleporterRegistryApp_init_unchained` An example dApp looks like:

```solidity
// An example dApp that integrates with the Teleporter registry
// to send/receive ICM messages.
contract ExampleApp is
    TeleporterRegistryApp
{
    ...
    // Constructor passes in the Teleporter registry address
    // to the TeleporterRegistryApp contract.
    constructor(
        address teleporterRegistryAddress,
        uint256 minTeleporterVersion
    ) TeleporterRegistryApp(teleporterRegistryAddress, minTeleporterVersion) {
        currentBlockchainID = IWarpMessenger(WARP_PRECOMPILE_ADDRESS)
            .getBlockchainID();
    }
    ...
    // Handles receiving ICM messages,
    // and also checks that the sender is a valid TeleporterMessenger contract.
    function _receiveTeleporterMessage(
        bytes32 sourceBlockchainID,
        address originSenderAddress,
        bytes memory message
    ) internal override {
        // implementation
    }

    // Implements the access control checks for the dApp's interaction with TeleporterMessenger versions.
    function _checkTeleporterRegistryAppAccess() internal view virtual override {
        //implementation
    }

}
```

### Checking TeleporterRegistryApp access

To prevent anyone from calling the dApp's `updateMinTeleporterVersion`, which would disallow messages from old `TeleporterMessenger` versions from being received, this function should be safeguarded with access controls. All contracts deriving from `TeleporterRegistryApp` will need to implement `TeleporterRegistryApp._checkTeleporterRegistryAppAccess`. For example, [TeleporterRegistryOwnableApp](https://github.com/ava-labs/teleporter/blob/main/contracts/teleporter/registry/TeleporterRegistryOwnableApp.sol) is an abstract contract that inherits `TeleporterRegistryApp`, and implements `_checkTeleporterRegistryAppAccess` to check whether the caller is the owner. There is also a corresponding `TeleporterRegistryOwnableAppUpgradeable` contract that is upgrade compatible.

```solidity
    function _checkTeleporterRegistryAppAccess() internal view virtual override {
        _checkOwner();
    }
```

Another example would be a dApp that has different roles and priveleges. `_checkTeleporterRegistryAppAccess` can be implemented to check whether the caller is a specific role.

```solidity
    function _checkTeleporterRegistryAppAccess() internal view virtual override {
        require(
            hasRole(TELEPORTER_REGISTRY_APP_ADMIN, _msgSender()),
            "TeleporterRegistryApp: caller does not have access"
        );
    }
```

### Sending with specific TeleporterMessenger version

For sending messages with the Teleporter registry, dApps should use `TeleporterRegistryApp._getTeleporterMessenger`. This function by default extends `TeleporterRegistry.getLatestTeleporter`, using the latest version, and adds an extra check on whether the latest `TeleporterMessenger` address is paused. If the dApp wants to send a message through a specific `TeleporterMessenger` version, it can override `_getTeleporterMessenger()` to use the specific `TeleporterMessenger` version with `TeleporterRegistry.getTeleporterFromVersion`.

The `TeleporterRegistryApp._sendTeleporterMessage` function makes sending ICM messages easier. The function uses `_getTeleporterMessenger` to get the sending `TeleporterMessenger` version, pays for `TeleporterMessenger` fees from the dApp's balance, and sends the cross chain message.

Using latest version:

```solidity
        ITeleporterMessenger teleporterMessenger = _getTeleporterMessenger();
```

Using specific version:

```solidity
        // Override _getTeleporterMessenger to use specific version.
        function _getTeleporterMessenger() internal view override returns (ITeleporterMessenger) {
            ITeleporterMessenger teleporter = teleporterRegistry
                .getTeleporterFromVersion($VERSION);
            require(
                !pausedTeleporterAddresses[address(teleporter)],
                "TeleporterRegistryApp: Teleporter sending version paused"
            );

            return teleporter;
        }

        ITeleporterMessenger teleporterMessenger = _getTeleporterMessenger();
```

### Receiving from specific TeleporterMessenger versions

`TeleporterRegistryApp` also provides an initial implementation of [ITeleporterReceiver.receiveTeleporterMessage](https://github.com/ava-labs/teleporter/blob/main/contracts/teleporter/ITeleporterReceiver.sol) that ensures `_msgSender` is a `TeleporterMessenger` contract with a version greater than or equal to `minTeleporterVersion`. This supports the case where a dApp wants to use a new version of the `TeleporterMessenger` contract, but still wants to be able to receive messages from the old `TeleporterMessenger` contract.The dApp can override `_receiveTeleporterMessage` to implement its own logic for receiving messages from `TeleporterMessenger` contracts.

## Managing a TeleporterRegistryApp dApp

dApps that implement `TeleporterRegistryApp` automatically use the latest `TeleporterMessenger` version registered with the `TeleporterRegistry`. Interaction with underlying `TeleporterMessenger` versions can be managed by setting the minimum `TeleporterMessenger` version, and pausing and unpausing specific versions.

The following sections include example `cast send` commands for issuing transactions that call contract functions. See the [Foundry Book](https://book.getfoundry.sh/reference/cast/cast-send) for details on how to issue transactions using common wallet options.

### Managing the Minimum TeleporterMessenger version

The `TeleporterRegistryApp` contract constructor saves the Teleporter registry in a state variable used by the inheriting dApp contract, and initializes a `minTeleporterVersion` to the highest `TeleporterMessenger` version registered in `TeleporterRegistry`. `minTeleporterVersion` is used to allow dApp's to specify the `TeleporterMessenger` versions allowed to interact with it.

#### Updating `minTeleporterVersion`

The `TeleporterRegistryApp.updateMinTeleporterVersion` function updates the `minTeleporterVersion` used to check which `TeleporterMessenger` versions can be used for sending and receiving messages. **Once the `minTeleporterVersion` is increased, any undelivered messages sent by other chains using older versions of `TeleporterMessenger` will never be able to be received**. The `updateMinTeleporterVersion` function can only be called with a version greater than the current `minTeleporterVersion` and less than `latestVersion` in the Teleporter registry.

> Example: Update the minimum TeleporterMessenger version to 2
>
> ```bash
> cast send <DAPP_ADDRESS> "updateMinTeleporterVersion(uint256)" 2
> ```

### Pausing TeleporterMessenger version interactions

dApps that inherit from `TeleporterRegistryApp` can pause `TeleporterMessenger` interactions by calling `TeleporterRegistryApp.pauseTeleporterAddress`. This function prevents the dApp contract from interacting with the paused `TeleporterMessenger` address when sending or receiving ICM messages.

`pauseTeleporterAddress` can only be called by addresses that passes the dApp's `TeleporterRegistryApp._checkTeleporterRegistryAppAccess` check.

The `TeleporterMessenger` address corresponding to a `TeleporterMessenger` version can be fetched from the registry with `TeleporterRegistry.getAddressFromVersion`

> Example: Pause TeleporterMessenger version 3
>
> ```bash
> versionThreeAddress=$(cast call <REGISTRY_ADDRESS> "getAddressFromVersion(uint256)(address)" 3)
> cast send <DAPP_ADDRESS> "pauseTeleporterAddress(address)" $versionThreeAddress
> ```

#### Pause all TeleporterMessenger interactions

To pause all `TeleporterMessenger` interactions, `TeleporterRegistryApp.pauseTeleporterAddress` must be called for every `TeleporterMessenger` version from the `minTeleporterVersion` to the latest `TeleporterMessenger` version registered in `TeleporterRegistry`. Note that there may be gaps in `TeleporterMessenger` versions registered with `TeleporterRegistry`, but they will always be in increasing order. The latest `TeleporterMessenger` version can be obtained by inspecting the public variable `TeleporterRegistry.latestVersion`. The `minTeleporterVersion` can be obtained by calling `TeleporterRegistryApp.getMinTeleporterVersion`.

> Example: Pause all registered TeleporterMessenger versions
>
> ```bash
> # Fetch the minimum TeleporterMessenger version
> minVersion=$(cast call <DAPP_ADDRESS> "getMinTeleporterVersion()(uint256)")
>
> # Fetch the latest registered version
> latestVersion=$(cast call <REGISTRY_ADDRESS> "latestVersion()(uint256)")
>
> # Pause all registered versions
> for ((version=minVersion; version<=latestVersion; version++))
> do
>  # Fetch the version address if it's registered
>  versionAddress=$(cast call <REGISTRY_ADDRESS> "getAddressFromVersion(uint256)(address)" $version)
>
>  if [ $? -eq 0 ]; then
>    # If cast call is successful, proceed to cast send
>    cast send <DAPP_ADDRESS> "pauseTeleporterAddress(address)" $versionAddress
>  else
>    # If cast call fails, print an error message and skip to the next iteration
>    echo "Version $version not registered. Skipping."
>  fi
> done
> ```

#### Unpausing TeleporterMessenger version interactions

As with pausing, dApps can unpause `TeleporterMessenger` interactions by calling `TeleporterRegistryApp.unpauseTeleporterAddress`. This unpause function allows receiving `TeleporterMessenger` message from the unpaused `TeleporterMessenger` address, and also enables the sending of messages through the unpaused `TeleporterMessenger` address in `_getTeleporterMessenger()`. Unpausing is also only allowed by addresses passing the dApp's `_checkTeleporterRegistryAppAccess` check.

Note that receiving `TeleporterMessenger` messages is still governed by the `minTeleporterVersion` check, so even if a `TeleporterMessenger` address is unpaused, the dApp will not receive messages from the unpaused `TeleporterMessenger` address if the `TeleporterMessenger` version is less than `minTeleporterVersion`.

> Example: Unpause TeleporterMessenger version 3
>
> ```bash
> versionThreeAddress=$(cast call <REGISTRY_ADDRESS> "getAddressFromVersion(uint256)(address)" 3)
> cast send <DAPP_ADDRESS> "unpauseTeleporterAddress(address)" $versionThreeAddress
> ```

# C-Chain Configs (/docs/nodes/chain-configs/c-chain)

---
title: "C-Chain Configs"
description: "This page describes the configuration options available for the C-Chain."
edit_url: https://github.com/ava-labs/coreth/edit/master/plugin/evm/config/config.md
---

> **Note**: These are the configuration options available in the coreth codebase. To set these values, you need to create a configuration file at `{chain-config-dir}/C/config.json`. This file does not exist by default.
>
> For example if `chain-config-dir` has the default value which is `$HOME/.avalanchego/configs/chains`, then `config.json` should be placed at `$HOME/.avalanchego/configs/chains/C/config.json`.
>
> For the AvalancheGo node configuration options, see the AvalancheGo Configuration page.

This document describes all configuration options available for coreth.

The C-Chain config is printed out in the log when a node starts. Default values for each config flag are specified below.

Default values are overridden only if specified in the given config file. It is recommended to only provide values which are different from the default, as that makes the config more resilient to future default changes. Otherwise, if defaults change, your node will remain with the old values, which might adversely affect your node operation.

## Example Configuration

```json
{
  "eth-apis": ["eth", "eth-filter", "net", "web3"],
  "pruning-enabled": true,
  "commit-interval": 4096,
  "trie-clean-cache": 512,
  "trie-dirty-cache": 512,
  "snapshot-cache": 256,
  "rpc-gas-cap": 50000000,
  "log-level": "info",
  "metrics-expensive-enabled": true,
  "continuous-profiler-dir": "./profiles",
  "state-sync-enabled": false,
  "accepted-cache-size": 32
}
```

## Configuration Format

Configuration is provided as a JSON object. All fields are optional unless otherwise specified.

## API Configuration

### Ethereum APIs

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `eth-apis` | array of strings | List of Ethereum services that should be enabled | `["eth", "eth-filter", "net", "web3", "internal-eth", "internal-blockchain", "internal-transaction"]` |
| `eth` | bool | Adds the `eth_coinbase` and `eth_etherbase` RPC calls to the `eth_*` namespace. | `true` | 
| `eth-filter` | bool |  Enables the public filter API for the `eth_*` namespace and adds the following RPC calls (see [here](https://eth.wiki/json-rpc/API) for complete documentation): <br/> - `eth_newPendingTransactionFilter` <br/> - `eth_newPendingTransactions` <br/> - `eth_newAcceptedTransactions` <br/> - `eth_newBlockFilter` <br/> - `eth_newHeads` <br/> - `eth_logs` <br/> - `eth_newFilter` <br/> - `eth_getLogs` <br/> - `eth_uninstallFilter` <br/> - `eth_getFilterLogs` <br/> - `eth_getFilterChanges` <br/> |   `true` | 
| `admin` | bool | Adds the `admin_importChain` and `admin_exportChain` RPC calls to the `admin_*` namespace | `false` | 
| `debug` | bool | Adds the following RPC calls to the `debug_*` namespace. <br/> - `debug_dumpBlock` <br/> - `debug_accountRange` <br/> - `debug_preimage` <br/> - `debug_getBadBlocks` <br/> - `debug_storageRangeAt` <br/> - `debug_getModifiedAccountsByNumber` <br/> - `debug_getModifiedAccountsByHash` <br/> - `debug_getAccessibleState` <br/> The following RPC calls are disabled for any nodes with `state-scheme = firewood`: <br/> - `debug_storageRangeAt` <br/> - `debug_getModifiedAccountsByNumber` <br/> - `debug_getModifiedAccountsByHash` <br/> | `false`.
| `net` | bool | Adds the following RPC calls to the `net_*` namespace. <br/> - `net_listening` <br/> - `net_peerCount` <br/> - `net_version` <br/> Note: Coreth is a virtual machine and does not have direct access to the networking layer, so `net_listening` always returns true and `net_peerCount` always returns 0. For accurate metrics on the network layer, users should use the AvalancheGo APIs. | `true` |
| `debug-tracer` | bool | Adds the following RPC calls to the `debug_*` namespace. <br/> - `debug_traceChain` <br/> - `debug_traceBlockByNumber` <br/> - `debug_traceBlockByHash` <br/> - `debug_traceBlock` <br/> - `debug_traceBadBlock` <br/> - `debug_intermediateRoots` <br/> - `debug_traceTransaction` <br/> - `debug_traceCall` | `false` |
| `web3` | bool | Adds the `web3_clientVersion` and `web3_sha3` RPC calls to the `web3_*` namespace | `true` |
| `internal-eth` | bool | Adds the following RPC calls to the `eth_*` namespace. <br/> - `eth_gasPrice` <br/> - `eth_baseFee` <br/> - `eth_maxPriorityFeePerGas` <br/> - `eth_feeHistory` | `true` |
| `internal-blockchain` | bool | Adds the following RPC calls to the `eth_*` namespace. <br/> - `eth_chainId` <br/> - `eth_blockNumber` <br/> - `eth_getBalance` <br/> - `eth_getProof` <br/> - `eth_getHeaderByNumber` <br/> - `eth_getHeaderByHash` <br/> - `eth_getBlockByNumber` <br/> - `eth_getBlockByHash` <br/> - `eth_getUncleBlockByNumberAndIndex` <br/> - `eth_getUncleBlockByBlockHashAndIndex` <br/> - `eth_getUncleCountByBlockNumber` <br/> - `eth_getUncleCountByBlockHash` <br/> - `eth_getCode` <br/> - `eth_getStorageAt` <br/> - `eth_call` <br/> - `eth_estimateGas` <br/> - `eth_createAccessList` <br/> `eth_getProof` is disabled for any node with `state-scheme = firewood` | `true` |
| `internal-transaction` | bool | Adds the following RPC calls to the `eth_*` namespace. <br/> - `eth_getBlockTransactionCountByNumber` <br/> - `eth_getBlockTransactionCountByHash` <br/> - `eth_getTransactionByBlockNumberAndIndex` <br/> - `eth_getTransactionByBlockHashAndIndex` <br/> - `eth_getRawTransactionByBlockNumberAndIndex` <br/> - `eth_getRawTransactionByBlockHashAndIndex` <br/> - `eth_getTransactionCount` <br/> - `eth_getTransactionByHash` <br/> - `eth_getRawTransactionByHash` <br/> - `eth_getTransactionReceipt` <br/> - `eth_sendTransaction` <br/> - `eth_fillTransaction` <br/> - `eth_sendRawTransaction` <br/> - `eth_sign` <br/> - `eth_signTransaction` <br/> - `eth_pendingTransactions` <br/> - `eth_resend` | `true` |
| `internal-tx-pool` | bool | Adds the following RPC calls to the `txpool_*` namespace. <br/> - `txpool_content` <br/> - `txpool_contentFrom` <br/> - `txpool_status` <br/> - `txpool_inspect` | `false` |
| `internal-debug` | bool | Adds the following RPC calls to the `debug_*` namespace. <br/> - `debug_getHeaderRlp` <br/> - `debug_getBlockRlp` <br/> - `debug_printBlock` <br/> - `debug_chaindbProperty` <br/> - `debug_chaindbCompact` | `false` |
| `debug-handler` | bool | Adds the following RPC calls to the `debug_*` namespace. <br/> - `debug_verbosity` <br/> - `debug_vmodule` <br/> - `debug_backtraceAt` <br/> - `debug_memStats` <br/> - `debug_gcStats` <br/> - `debug_blockProfile` <br/> - `debug_setBlockProfileRate` <br/> - `debug_writeBlockProfile` <br/> - `debug_mutexProfile` <br/> - `debug_setMutexProfileFraction` <br/> - `debug_writeMutexProfile` <br/> - `debug_writeMemProfile` <br/> - `debug_stacks` <br/> - `debug_freeOSMemory` <br/> - `debug_setGCPercent` | `false` |
| `internal-account` | bool | Adds the `eth_accounts` RPC call to the `eth_*` namespace  | `true` |
| `internal-personal` | bool | Adds the following RPC calls to the `personal_*` namespace. <br/> - `personal_listAccounts` <br/> - `personal_listWallets` <br/> - `personal_openWallet` <br/> - `personal_deriveAccount` <br/> - `personal_newAccount` <br/> - `personal_importRawKey` <br/> - `personal_unlockAccount` <br/> - `personal_lockAccount` <br/> - `personal_sendTransaction` <br/> - `personal_signTransaction` <br/> - `personal_sign` <br/> - `personal_ecRecover` <br/> - `personal_signAndSendTransaction` <br/> - `personal_initializeWallet` <br/> - `personal_unpair` | `false` |

### Enabling Avalanche Specific APIs

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `admin-api-enabled` | bool | Enables the Admin API |  `false` | 
| `admin-api-dir` | string | Specifies the directory for the Admin API to use to store CPU/Mem/Lock Profiles | `""` | 
| `warp-api-enabled` | bool | Enable the Warp API for cross-chain messaging | `false` |

### API Limits and Security

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `rpc-gas-cap` | uint64 | Maximum gas limit for RPC calls | `50,000,000` |
| `rpc-tx-fee-cap` | float64 | Maximum transaction fee cap in AVAX | `100` |
| `api-max-duration` | duration | Maximum duration for API calls (0 = no limit) | `0` |
| `api-max-blocks-per-request` | int64 | Maximum number of blocks per getLogs request (0 = no limit) | `0` |
| `http-body-limit` | uint64 | Maximum size of HTTP request bodies (0 = no limit) | `0` |
| `batch-request-limit` | uint64 | Maximum number of requests that can be batched in an RPC call. For no limit, set either this or `batch-response-max-size` to 0 | `1000` | 
| `batch-response-max-size` | uint64 | Maximum size (in bytes) of response that can be returned from a batched RPC call. For no limit, set either this or `batch-request-limit` to 0. Defaults to `25 MB`| `1000` |

### WebSocket Settings

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `ws-cpu-refill-rate` | duration | Rate at which WebSocket CPU usage quota is refilled (0 = no limit) | `0` |
| `ws-cpu-max-stored` | duration | Maximum stored WebSocket CPU usage quota (0 = no limit) | `0` |

## Cache Configuration

### Trie Caches

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `trie-clean-cache` | int | Size of the trie clean cache in MB | `512` |
| `trie-dirty-cache` | int | Size of the trie dirty cache in MB | `512` |
| `trie-dirty-commit-target` | int | Memory limit to target in the dirty cache before performing a commit in MB | `20` |
| `trie-prefetcher-parallelism` | int | Maximum concurrent disk reads trie prefetcher should perform | `16` |

### Other Caches

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `snapshot-cache` | int | Size of the snapshot disk layer clean cache in MB | `256` |
| `accepted-cache-size` | int | Depth to keep in the accepted headers and logs cache (blocks) | `32` |
| `state-sync-server-trie-cache` | int | Trie cache size for state sync server in MB | `64` |

## Ethereum Settings

### Transaction Processing

> **⚠️ WARNING: `allow-unfinalized-queries` should likely be set to `false` in production.** Enabling this flag can result in a confusing/unreliable user experience. Enabling this flag should only be done when users are expected to have knowledge of how Snow* consensus finalizes blocks.
> Unlike chains with reorgs and forks that require block confirmations, Avalanche **does not** increase the confidence that a block will be finalized based on the depth of the chain. Waiting for additional blocks **does not** confirm finalization. Enabling this flag removes the guarantee that the node only exposes finalized blocks; requiring users to guess if a block is finalized.

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `preimages-enabled` | bool | Enable preimage recording | `false` |
| `allow-unfinalized-queries` | bool | Allow queries for unfinalized blocks | `false` |
| `allow-unprotected-txs` | bool | Allow unprotected transactions (without EIP-155) | `false` |
| `allow-unprotected-tx-hashes` | \[\]TxHash | Specifies an array of transaction hashes that should be allowed to bypass replay protection. This flag is intended for node operators that want to explicitly allow specific transactions to be issued through their API. | an empty list |
| `local-txs-enabled` | bool | Enable treatment of transactions from local accounts as local | `false` |

### Snapshots

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `snapshot-wait` | bool | Wait for snapshot generation on startup | `false` |
| `snapshot-verification-enabled` | bool | Enable snapshot verification | `false` |

## Pruning and State Management

 > **Note**: If a node is ever run with `pruning-enabled` as `false` (archival mode), setting `pruning-enabled` to `true` will result in a warning and the node will shut down. This is to protect against unintentional misconfigurations of an archival node. To override this and switch to pruning mode, in addition to `pruning-enabled: true`, `allow-missing-tries` should be set to `true` as well. 

### Basic Pruning

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `pruning-enabled` | bool | Enable state pruning to save disk space | `true` |
| `commit-interval` | uint64 | Interval at which to persist EVM and atomic tries (blocks) | `4096` |
| `accepted-queue-limit` | int | Maximum blocks to queue before blocking during acceptance | `64` |

### State Reconstruction

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `allow-missing-tries` | bool | Suppress warnings about incomplete trie index | `false` |
| `populate-missing-tries` | uint64 | Starting block for re-populating missing tries (null = disabled) | `null` |
| `populate-missing-tries-parallelism` | int | Concurrent readers for re-populating missing tries | `1024` |

### Offline Pruning

> **Note**: If offline pruning is enabled it will  run on startup and block until it completes (approximately one hour on Mainnet). This will reduce the size of the database by deleting old trie nodes. **While performing offline pruning, your node will not be able to process blocks and will be considered offline.** While ongoing, the pruning process consumes a small amount of additional disk space (for deletion markers and the bloom filter). For more information see [here.](https://build.avax.network/docs/nodes/maintain/reduce-disk-usage#disk-space-considerations). Since offline pruning deletes old state data, this should not be run on nodes that need to support archival API requests. This is meant to be run manually, so after running with this flag once, it must be toggled back to false before running the node again. Therefore, you should run with this flag set to true and then set it to false on the subsequent run.

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `offline-pruning-enabled` | bool | Enable offline pruning | `false` |
| `offline-pruning-bloom-filter-size` | uint64 | Bloom filter size for offline pruning in MB | `512` |
| `offline-pruning-data-directory` | string | Directory for offline pruning data | - |

### Historical Data

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `historical-proof-query-window` | uint64 | Number of blocks before last accepted for proof queries (archive mode only, ~24 hours) | `43200` |
| `state-history` | uint64 | Number of most recent states that are accesible on disk (pruning mode only) | `32` |

## Transaction Pool Configuration

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `tx-pool-price-limit` | uint64 | Minimum gas price for transaction acceptance | `1` |
| `tx-pool-price-bump` | uint64 | Minimum price bump percentage for transaction replacement | `10%` |
| `tx-pool-account-slots` | uint64 | Maximum number of executable transaction slots per account | `16`  |
| `tx-pool-global-slots` | uint64 | Maximum number of executable transaction slots for all accounts | `5120` |
| `tx-pool-account-queue` | uint64 | Maximum number of non-executable transaction slots per account | `64` |
| `tx-pool-global-queue` | uint64 | Maximum number of non-executable transaction slots for all accounts | `1024` |
| `tx-pool-lifetime` | duration | Maximum duration in nanoseconds a non-executable transaction will be allowed in the poll | `600000000000` (10 minutes) |
| `price-options-slow-fee-percentage` | integer | Percentage to apply for slow fee estimation | `95` |
| `price-options-fast-fee-percentage` | integer | Percentage to apply for fast fee estimation | `105` |
| `price-options-max-tip` | integer | Maximum tip in wei for fee estimation | `20000000000` (20 Gwei) |

### Push Gossip Settings

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `push-gossip-percent-stake` | float64 | Percentage of total stake to push gossip to (range: [0, 1]) | `0.9` |
| `push-gossip-num-validators` | int | Number of validators to push gossip to | `100` |
| `push-gossip-num-peers` | int | Number of non-validator peers to push gossip to | `0` |

### Regossip Settings

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `push-regossip-num-validators` | int | Number of validators to regossip to | `10` |
| `push-regossip-num-peers` | int | Number of non-validator peers to regossip to | `0` |

### Timing Configuration

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `push-gossip-frequency` | duration | Frequency of push gossip | `100ms` |
| `pull-gossip-frequency` | duration | Frequency of pull gossip | `1s` |
| `regossip-frequency` | duration | Frequency of regossip | `30s` |

## Logging and Monitoring

### Logging

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `log-level` | string | Logging level (trace, debug, info, warn, error, crit) | `"info"` |
| `log-json-format` | bool | Use JSON format for logs | `false` |

### Profiling

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `continuous-profiler-dir` | string | Directory for continuous profiler output (empty = disabled) | `""` |
| `continuous-profiler-frequency` | duration | Frequency to run continuous profiler | `15m` |
| `continuous-profiler-max-files` | int | Maximum number of profiler files to maintain | `5` |

### Metrics

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `metrics-expensive-enabled` | bool | Enable expensive debug-level metrics; this includes Firewood metrics | `true` |

## Security and Access

### Keystore

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `keystore-directory` | string | Directory for keystore files (absolute or relative path); if empty, uses a temporary directory at `coreth-keystore` |  `""` |
| `keystore-external-signer` | string | Specifies an external URI for a clef-type signer |  `""` |
| `keystore-insecure-unlock-allowed` | bool | Allow insecure account unlocking | `false` |

## Network and Sync

### Network

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `max-outbound-active-requests` | int64 | Maximum number of outbound active requests for VM2VM network | `16` |

### State Sync

> **Note:** If state-sync is enabled, the peer will download chain state from peers up to a recent block near tip, then proceed with normal bootstrapping. Please note that if you need historical data, state sync isn't the right option. However, it is sufficient if you are just running a validator. 

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `state-sync-enabled` | bool | Enable state sync | `false` |
| `state-sync-skip-resume` | bool | Force state sync to use highest available summary block | `false` |
| `state-sync-ids` | string | Comma-separated list of state sync IDs; If not specified (or empty), peers are selected at random.| `""`|
| `state-sync-commit-interval` | uint64 | Commit interval for state sync (blocks) | `16384` |
| `state-sync-min-blocks` | uint64 | Minimum blocks ahead required for state sync | `300000` |
| `state-sync-request-size` | uint16 | Number of key/values to request per state sync request | `1024` |

## Database Configuration

> **WARNING**: `firewood` and `path` schemes are untested in production. Using `path` is strongly discouraged. To use `firewood`, you must also set the following config options:
>
> - `pruning-enabled: true` (enabled by default)
> - `state-sync-enabled: false`
> - `snapshot-cache: 0`

Failing to set these options will result in errors on VM initialization. Additionally, not all APIs are available - see these portions of the config documentation for more details.

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `inspect-database` | bool | Inspect database on startup | `false` |
| `state-scheme` | string |  EXPERIMENTAL: specifies the database scheme to store state data; can be one of `hash`, `firewood`, or `path` | `hash` | 

## Transaction Indexing

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `transaction-history` | uint64 | Maximum number of blocks from head whose transaction indices are reserved (0 = no limit) | `0` |
| `skip-tx-indexing` | bool | Skip indexing transactions entirely | `false` |

## Warp Configuration

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `warp-off-chain-messages` | array | Off-chain messages the node should be willing to sign | empty array |
| `prune-warp-db-enabled` | bool | Clear warp database on startup | `false` |

## Miscellaneous

> **Note:**  If `skip-upgrade-check` is set to `true`, the chain will skip verifying that all expected network upgrades have taken place before the last accepted block on startup. This allows node operators to recover if their node has accepted blocks after a network upgrade with a version of the code prior to the upgrade.

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `acceptor-queue-limit` | integer | Specifies the maximum number of blocks to queue during block acceptance before blocking on Accept. | `64` |
| `gas-target` | integer | The target gas per second that this node will attempt to use when creating blocks | Parent block's target | 
| `min-delay-target` | integer | The minimum delay between blocks (in milliseconds) that this node will attempt to use when creating blocks | Parent block's target |
| `skip-upgrade-check` | bool | Skip checking that upgrades occur before last accepted block ⚠️ **Warning**: Only use when you understand the implications | `false` |

# Chain Specific Configs (/docs/nodes/chain-configs)

---
title: Chain Specific Configs
---

Some chains allow the node operator to provide a custom configuration. AvalancheGo can read chain configurations from files and pass them to the corresponding chains on initialization.

AvalancheGo looks for these files in the directory specified by `--chain-config-dir` AvalancheGo flag, as documented [here](/docs/nodes/configure/configs-flags#--chain-config-dir-string). If omitted, value defaults to `$HOME/.avalanchego/configs/chains`. This directory can have sub-directories whose names are chain IDs or chain aliases. Each sub-directory contains the configuration for the chain specified in the directory name. Each sub-directory should contain a file named `config`, whose value is passed in when the corresponding chain is initialized (see below for extension). For example, config for the C-Chain should be at: `{chain-config-dir}/C/config.json`.

This also applies to Avalanche L1s, for example, if an Avalanche L1's chain id is `2ebCneCbwthjQ1rYT41nhd7M76Hc6YmosMAQrTFhBq8qeqh6tt`, the config for this chain should be at `{chain-config-dir}/2ebCneCbwthjQ1rYT41nhd7M76Hc6YmosMAQrTFhBq8qeqh6tt/config.json`

<Callout title="Tip" icon = {<BadgeCheck className="size-5 text-card" fill="green" />} >
By default, none of these directories and/or files exist. You would need to create them manually if needed.
</Callout>

The filename extension that these files should have, and the contents of these files, is VM-dependent. For example, some chains may expect `config.txt` while others expect `config.json`. If multiple files are provided with the same name but different extensions (for example `config.json` and `config.txt`) in the same sub-directory, AvalancheGo will exit with an error.

For a given chain, AvalancheGo will follow the sequence below to look for its config file, where all folder and file names are case sensitive:

1. First it looks for a config sub-directory whose name is the Chain ID.
2. If it isn't found, it looks for a config sub-directory whose name is the chain's primary alias.
3. If it's not found, it looks for a config sub-directory whose name is another alias for the chain

Alternatively, for some setups it might be more convenient to provide config entirely via the command line. For that, you can use AvalancheGo `--chain-config-content` flag, as documented [here](/docs/nodes/configure/configs-flags#--chain-config-content-string).

It is not required to provide these custom configurations. If they are not provided, a VM-specific default config will be used. And the values of these default config are printed when the node starts.

## Avalanche L1 Chain Configs

As mentioned above, if an Avalanche L1's chain id is `2ebCneCbwthjQ1rYT41nhd7M76Hc6YmosMAQrTFhBq8qeqh6tt`, the config for this chain should be at `{chain-config-dir}/2ebCneCbwthjQ1rYT41nhd7M76Hc6YmosMAQrTFhBq8qeqh6tt/config.json`

## FAQs

- When using `getBlockNumber` it will return finalized blocks. To allow for queries for unfinalized (not yet accepted) blocks/transactions use `allow-unfainalized-queries` and set to true (by default it is set to `false`) 
- When deactivating offline pruning `(pruning-enabled: false)` from previously enabled state, this will not impact blocks whose state was already pruned. This will return missing trie node errors, as the node can't lookup the state of a historical block if that state was deleted.


# P-Chain Configs (/docs/nodes/chain-configs/p-chain)

---
title: "P-Chain Configs"
description: "This page describes the configuration options available for the P-Chain."
edit_url: https://github.com/ava-labs/avalanchego/edit/master/vms/platformvm/config/config.md
---

This document provides details about the configuration options available for the PlatformVM.

## Standard Configurations

In order to specify a configuration for the PlatformVM, you need to define a `Config` struct and its parameters. The default values for these parameters are:

| Option                               | Type            | Default            |
| ------------------------------------ | --------------- | ------------------ |
| `network`                            | `Network`       | `DefaultNetwork`   |
| `block-cache-size`                   | `int`           | `64 * units.MiB`   |
| `tx-cache-size`                      | `int`           | `128 * units.MiB`  |
| `transformed-subnet-tx-cache-size`   | `int`           | `4 * units.MiB`    |
| `reward-utxos-cache-size`            | `int`           | `2048`             |
| `chain-cache-size`                   | `int`           | `2048`             |
| `chain-db-cache-size`                | `int`           | `2048`             |
| `block-id-cache-size`                | `int`           | `8192`             |
| `fx-owner-cache-size`                | `int`           | `4 * units.MiB`    |
| `subnet-to-l1-conversion-cache-size` | `int`           | `4 * units.MiB`    |
| `l1-weights-cache-size`              | `int`           | `16 * units.KiB`   |
| `l1-inactive-validators-cache-size`  | `int`           | `256 * units.KiB`  |
| `l1-subnet-id-node-id-cache-size`    | `int`           | `16 * units.KiB`   |
| `checksums-enabled`                  | `bool`          | `false`            |
| `mempool-prune-frequency`            | `time.Duration` | `30 * time.Minute` |
| `mempool-gas-capacity`               | `gas.Gas`       | `1_000_000`        |

Default values are overridden only if explicitly specified in the config.

## Network Configuration

The Network configuration defines parameters that control the network's gossip and validator behavior.

### Parameters

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `max-validator-set-staleness` | `time.Duration` | `1 minute` | Maximum age of a validator set used for peer sampling and rate limiting |
| `target-gossip-size` | `int` | `20 * units.KiB` | Target number of bytes to send when pushing transactions or responding to transaction pull requests |
| `push-gossip-percent-stake` | `float64` | `0.9` | Percentage of total stake to target in the initial gossip round. Higher stake nodes are prioritized to minimize network messages |
| `push-gossip-num-validators` | `int` | `100` | Number of validators to push transactions to in the initial gossip round |
| `push-gossip-num-peers` | `int` | `0` | Number of peers to push transactions to in the initial gossip round |
| `push-regossip-num-validators` | `int` | `10` | Number of validators for subsequent gossip rounds after the initial push |
| `push-regossip-num-peers` | `int` | `0` | Number of peers for subsequent gossip rounds after the initial push |
| `push-gossip-discarded-cache-size` | `int` | `16384` | Size of the cache storing recently dropped transaction IDs from mempool to avoid re-pushing |
| `push-gossip-max-regossip-frequency` | `time.Duration` | `30 * time.Second` | Maximum frequency limit for re-gossiping a transaction |
| `push-gossip-frequency` | `time.Duration` | `500 * time.Millisecond` | Frequency of push gossip rounds |
| `pull-gossip-poll-size` | `int` | `1` | Number of validators to sample during pull gossip rounds |
| `pull-gossip-frequency` | `time.Duration` | `1500 * time.Millisecond` | Frequency of pull gossip rounds |
| `pull-gossip-throttling-period` | `time.Duration` | `10 * time.Second` | Time window for throttling pull requests |
| `pull-gossip-throttling-limit` | `int` | `2` | Maximum number of pull queries allowed per validator within the throttling window |
| `expected-bloom-filter-elements` | `int` | `8 * 1024` | Expected number of elements when creating a new bloom filter. Larger values increase filter size |
| `expected-bloom-filter-false-positive-probability` | `float64` | `0.01` | Target probability of false positives after inserting the expected number of elements. Lower values increase filter size |
| `max-bloom-filter-false-positive-probability` | `float64` | `0.05` | Threshold for bloom filter regeneration. Filter is refreshed when false positive probability exceeds this value |

### Details

The configuration is divided into several key areas:

- **Validator Set Management**: Controls how fresh the validator set must be for network operations. The staleness setting ensures the network operates with reasonably current validator information.
- **Gossip Size Controls**: Manages the size of gossip messages to maintain efficient network usage while ensuring reliable transaction propagation.
- **Push Gossip Configuration**: Defines how transactions are initially propagated through the network, with emphasis on reaching high-stake validators first to optimize network coverage.
- **Pull Gossip Configuration**: Controls how nodes request transactions they may have missed, including throttling mechanisms to prevent network overload.
- **Bloom Filter Settings**: Configures the trade-off between memory usage and false positive rates in transaction filtering, with automatic filter regeneration when accuracy degrades.

# Subnet-EVM Configs (/docs/nodes/chain-configs/subnet-evm)

---
title: "Subnet-EVM Configs"
description: "This page describes the configuration options available for the Subnet-EVM."
edit_url: https://github.com/ava-labs/subnet-evm/edit/master/plugin/evm/config/config.md
---

# Subnet-EVM Configuration

> **Note**: These are the configuration options available in the Subnet-EVM codebase. To set these values, you need to create a configuration file at `~/.avalanchego/configs/chains/<blockchainID>/config.json`.
>
> For the AvalancheGo node configuration options, see the AvalancheGo Configuration page.

This document describes all configuration options available for Subnet-EVM.

## Example Configuration

```json
{
  "eth-apis": ["eth", "eth-filter", "net", "web3"],
  "pruning-enabled": true,
  "commit-interval": 4096,
  "trie-clean-cache": 512,
  "trie-dirty-cache": 512,
  "snapshot-cache": 256,
  "rpc-gas-cap": 50000000,
  "log-level": "info",
  "metrics-expensive-enabled": true,
  "continuous-profiler-dir": "./profiles",
  "state-sync-enabled": false,
  "accepted-cache-size": 32
}
```

## Configuration Format

Configuration is provided as a JSON object. All fields are optional unless otherwise specified.

## API Configuration

### Ethereum APIs

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `eth-apis` | array of strings | List of Ethereum services that should be enabled | `["eth", "eth-filter", "net", "web3", "internal-eth", "internal-blockchain", "internal-transaction"]` |

### Subnet-EVM Specific APIs

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `validators-api-enabled` | bool | Enable the validators API | `true` |
| `admin-api-enabled` | bool | Enable the admin API for administrative operations | `false` |
| `admin-api-dir` | string | Directory for admin API operations | - |
| `warp-api-enabled` | bool | Enable the Warp API for cross-chain messaging | `false` |

### API Limits and Security

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `rpc-gas-cap` | uint64 | Maximum gas limit for RPC calls | `50,000,000` |
| `rpc-tx-fee-cap` | float64 | Maximum transaction fee cap in AVAX | `100` |
| `api-max-duration` | duration | Maximum duration for API calls (0 = no limit) | `0` |
| `api-max-blocks-per-request` | int64 | Maximum number of blocks per getLogs request (0 = no limit) | `0` |
| `http-body-limit` | uint64 | Maximum size of HTTP request bodies | - |
| `batch-request-limit` | uint64 | Maximum number of requests that can be batched in an RPC call. For no limit, set either this or `batch-response-max-size` to 0 | `1000` | 
| `batch-response-max-size` | uint64 | Maximum size (in bytes) of response that can be returned from a batched RPC call. For no limit, set either this or `batch-request-limit` to 0. Defaults to `25 MB`| `1000` |

### WebSocket Settings

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `ws-cpu-refill-rate` | duration | Rate at which WebSocket CPU usage quota is refilled (0 = no limit) | `0` |
| `ws-cpu-max-stored` | duration | Maximum stored WebSocket CPU usage quota (0 = no limit) | `0` |

## Cache Configuration

### Trie Caches

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `trie-clean-cache` | int | Size of the trie clean cache in MB | `512` |
| `trie-dirty-cache` | int | Size of the trie dirty cache in MB | `512` |
| `trie-dirty-commit-target` | int | Memory limit to target in the dirty cache before performing a commit in MB | `20` |
| `trie-prefetcher-parallelism` | int | Maximum concurrent disk reads trie prefetcher should perform | `16` |

### Other Caches

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `snapshot-cache` | int | Size of the snapshot disk layer clean cache in MB | `256` |
| `accepted-cache-size` | int | Depth to keep in the accepted headers and logs cache (blocks) | `32` |
| `state-sync-server-trie-cache` | int | Trie cache size for state sync server in MB | `64` |

## Ethereum Settings

### Transaction Processing

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `preimages-enabled` | bool | Enable preimage recording | `false` |
| `allow-unfinalized-queries` | bool | Allow queries for unfinalized blocks | `false` |
| `allow-unprotected-txs` | bool | Allow unprotected transactions (without EIP-155) | `false` |
| `allow-unprotected-tx-hashes` | array | List of specific transaction hashes allowed to be unprotected | EIP-1820 registry tx |
| `local-txs-enabled` | bool | Enable treatment of transactions from local accounts as local | `false` |

### Snapshots

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `snapshot-wait` | bool | Wait for snapshot generation on startup | `false` |
| `snapshot-verification-enabled` | bool | Enable snapshot verification | `false` |

## Pruning and State Management

### Basic Pruning

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `pruning-enabled` | bool | Enable state pruning to save disk space | `true` |
| `commit-interval` | uint64 | Interval at which to persist EVM and atomic tries (blocks) | `4096` |
| `accepted-queue-limit` | int | Maximum blocks to queue before blocking during acceptance | `64` |

### State Reconstruction

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `allow-missing-tries` | bool | Suppress warnings about incomplete trie index | `false` |
| `populate-missing-tries` | uint64 | Starting block for re-populating missing tries (null = disabled) | `null` |
| `populate-missing-tries-parallelism` | int | Concurrent readers for re-populating missing tries | `1024` |

### Offline Pruning

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `offline-pruning-enabled` | bool | Enable offline pruning | `false` |
| `offline-pruning-bloom-filter-size` | uint64 | Bloom filter size for offline pruning in MB | `512` |
| `offline-pruning-data-directory` | string | Directory for offline pruning data | - |

### Historical Data

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `historical-proof-query-window` | uint64 | Number of blocks before last accepted for proof queries (archive mode only, ~24 hours) | `43200` |
| `state-history` | uint64 | Number of most recent states that are accesible on disk (pruning mode only) | `32` |

## Transaction Pool Configuration

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `tx-pool-price-limit` | uint64 | Minimum gas price for transaction acceptance | - |
| `tx-pool-price-bump` | uint64 | Minimum price bump percentage for transaction replacement | - |
| `tx-pool-account-slots` | uint64 | Maximum number of executable transaction slots per account | - |
| `tx-pool-global-slots` | uint64 | Maximum number of executable transaction slots for all accounts | - |
| `tx-pool-account-queue` | uint64 | Maximum number of non-executable transaction slots per account | - |
| `tx-pool-global-queue` | uint64 | Maximum number of non-executable transaction slots for all accounts | - |
| `tx-pool-lifetime` | duration | Maximum time transactions can stay in the pool | - |

## Gossip Configuration

### Push Gossip Settings

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `push-gossip-percent-stake` | float64 | Percentage of total stake to push gossip to (range: [0, 1]) | `0.9` |
| `push-gossip-num-validators` | int | Number of validators to push gossip to | `100` |
| `push-gossip-num-peers` | int | Number of non-validator peers to push gossip to | `0` |

### Regossip Settings

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `push-regossip-num-validators` | int | Number of validators to regossip to | `10` |
| `push-regossip-num-peers` | int | Number of non-validator peers to regossip to | `0` |
| `priority-regossip-addresses` | array | Addresses to prioritize for regossip | - |

### Timing Configuration

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `push-gossip-frequency` | duration | Frequency of push gossip | `100ms` |
| `pull-gossip-frequency` | duration | Frequency of pull gossip | `1s` |
| `regossip-frequency` | duration | Frequency of regossip | `30s` |

## Logging and Monitoring

### Logging

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `log-level` | string | Logging level (trace, debug, info, warn, error, crit) | `"info"` |
| `log-json-format` | bool | Use JSON format for logs | `false` |

### Profiling

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `continuous-profiler-dir` | string | Directory for continuous profiler output (empty = disabled) | - |
| `continuous-profiler-frequency` | duration | Frequency to run continuous profiler | `15m` |
| `continuous-profiler-max-files` | int | Maximum number of profiler files to maintain | `5` |

### Metrics

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `metrics-expensive-enabled` | bool | Enable expensive debug-level metrics; this includes Firewood metrics | `true` |

## Security and Access

### Keystore

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `keystore-directory` | string | Directory for keystore files (absolute or relative path) | - |
| `keystore-external-signer` | string | External signer configuration | - |
| `keystore-insecure-unlock-allowed` | bool | Allow insecure account unlocking | `false` |

### Fee Configuration

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `feeRecipient` | string | Address to send transaction fees to (leave empty if not supported) | - |

## Network and Sync

### Network

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `max-outbound-active-requests` | int64 | Maximum number of outbound active requests for VM2VM network | `16` |

### State Sync

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `state-sync-enabled` | bool | Enable state sync | `false` |
| `state-sync-skip-resume` | bool | Force state sync to use highest available summary block | `false` |
| `state-sync-ids` | string | Comma-separated list of state sync IDs | - |
| `state-sync-commit-interval` | uint64 | Commit interval for state sync (blocks) | `16384` |
| `state-sync-min-blocks` | uint64 | Minimum blocks ahead required for state sync | `300000` |
| `state-sync-request-size` | uint16 | Number of key/values to request per state sync request | `1024` |

## Database Configuration

> **WARNING**: `firewood` and `path` schemes are untested in production. Using `path` is strongly discouraged. To use `firewood`, you must also set the following config options:
>
> - `pruning-enabled: true` (enabled by default)
> - `state-sync-enabled: false`
> - `snapshot-cache: 0`

Failing to set these options will result in errors on VM initialization. Additionally, not all APIs are available - see these portions of the config documentation for more details.

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `database-type` | string | Type of database to use | `"pebbledb"` |
| `database-path` | string | Path to database directory | - |
| `database-read-only` | bool | Open database in read-only mode | `false` |
| `database-config` | string | Inline database configuration | - |
| `database-config-file` | string | Path to database configuration file | - |
| `use-standalone-database` | bool | Use standalone database instead of shared one | - |
| `inspect-database` | bool | Inspect database on startup | `false` |
| `state-scheme` | string |  EXPERIMENTAL: specifies the database scheme to store state data; can be one of `hash` or `firewood` | `hash` | 

## Transaction Indexing

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `transaction-history` | uint64 | Maximum number of blocks from head whose transaction indices are reserved (0 = no limit) | - |
| `tx-lookup-limit` | uint64 | **Deprecated** - use `transaction-history` instead | - |
| `skip-tx-indexing` | bool | Skip indexing transactions entirely | `false` |

## Warp Configuration

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `warp-off-chain-messages` | array | Off-chain messages the node should be willing to sign | - |
| `prune-warp-db-enabled` | bool | Clear warp database on startup | `false` |

## Miscellaneous

| Option | Type | Description | Default |
|--------|------|-------------|---------|
| `airdrop` | string | Path to airdrop file | - |
| `skip-upgrade-check` | bool | Skip checking that upgrades occur before last accepted block ⚠️ **Warning**: Only use when you understand the implications | `false` |
| `min-delay-target` | integer | The minimum delay between blocks (in milliseconds) that this node will attempt to use when creating blocks | Parent block's target |

## Gossip Constants

The following constants are defined for transaction gossip behavior and cannot be configured without a custom build of Subnet-EVM:

| Constant | Type | Description | Value |
|----------|------|-------------|-------|
| Bloom Filter Min Target Elements | int | Minimum target elements for bloom filter | `8,192` |
| Bloom Filter Target False Positive Rate | float | Target false positive rate | `1%` |
| Bloom Filter Reset False Positive Rate | float | Reset false positive rate | `5%` |
| Bloom Filter Churn Multiplier | int | Churn multiplier | `3` |
| Push Gossip Discarded Elements | int | Number of discarded elements | `16,384` |
| Tx Gossip Target Message Size | size | Target message size for transaction gossip | `20 KiB` |
| Tx Gossip Throttling Period | duration | Throttling period | `10s` |
| Tx Gossip Throttling Limit | int | Throttling limit | `2` |
| Tx Gossip Poll Size | int | Poll size | `1` |

## Validation Notes

- Cannot enable `populate-missing-tries` while pruning or offline pruning is enabled
- Cannot run offline pruning while pruning is disabled  
- Commit interval must be non-zero when pruning is enabled
- `push-gossip-percent-stake` must be in range `[0, 1]`
- Some settings may require node restart to take effect

# X-Chain Configs (/docs/nodes/chain-configs/x-chain)

---
title: "X-Chain Configs"
description: "This page describes the configuration options available for the X-Chain."
edit_url: https://github.com/ava-labs/avalanchego/edit/master/vms/avm/config.md
---

In order to specify a config for the X-Chain, a JSON config file should be
placed at `{chain-config-dir}/X/config.json`.

For example if `chain-config-dir` has the default value which is
`$HOME/.avalanchego/configs/chains`, then `config.json` can be placed at
`$HOME/.avalanchego/configs/chains/X/config.json`.

This allows you to specify a config to be passed into the X-Chain. The default
values for this config are:

```json
{
  "checksums-enabled": false
}
```

Default values are overridden only if explicitly specified in the config.

The parameters are as follows:

### `checksums-enabled`

_Boolean_

Enables checksums if set to `true`.

# Avalanche L1 Configs (/docs/nodes/configure/avalanche-l1-configs)

---
title: "Avalanche L1 Configs"
description: "This page describes the configuration options available for Avalanche L1s."
edit_url: https://github.com/ava-labs/avalanchego/edit/master/subnets/config.md
---

# Subnet Configs

It is possible to provide parameters for a Subnet. Parameters here apply to all
chains in the specified Subnet.

AvalancheGo looks for files specified with `{subnetID}.json` under
`--subnet-config-dir` as documented
[here](https://build.avax.network/docs/nodes/configure/configs-flags#subnet-configs).

Here is an example of Subnet config file:

```json
{
  "validatorOnly": false,
  "consensusParameters": {
    "k": 25,
    "alpha": 18
  }
}
```

## Parameters

### Private Subnet

#### `validatorOnly` (bool)

If `true` this node does not expose Subnet blockchain contents to non-validators
via P2P messages. Defaults to `false`.

Avalanche Subnets are public by default. It means that every node can sync and
listen ongoing transactions/blocks in Subnets, even they're not validating the
listened Subnet.

Subnet validators can choose not to publish contents of blockchains via this
configuration. If a node sets `validatorOnly` to true, the node exchanges
messages only with this Subnet's validators. Other peers will not be able to
learn contents of this Subnet from this node.

:::tip
This is a node-specific configuration. Every validator of this Subnet has to use
this configuration in order to create a full private Subnet.

:::

#### `allowedNodes` (string list)

If `validatorOnly=true` this allows explicitly specified NodeIDs to be allowed
to sync the Subnet regardless of validator status. Defaults to be empty.

:::tip
This is a node-specific configuration. Every validator of this Subnet has to use
this configuration in order to properly allow a node in the private Subnet.

:::

### Consensus Parameters

Subnet configs supports loading new consensus parameters. JSON keys are
different from their matching `CLI` keys. These parameters must be grouped under
`consensusParameters` key. The consensus parameters of a Subnet default to the
same values used for the Primary Network, which are given [CLI Snow Parameters](https://build.avax.network/docs/nodes/configure/configs-flags#snow-parameters).

| CLI Key                          | JSON Key              |
| :------------------------------- | :-------------------- |
| --snow-sample-size               | k                     |
| --snow-quorum-size               | alpha                 |
| --snow-commit-threshold          | `beta`                |
| --snow-concurrent-repolls        | concurrentRepolls     |
| --snow-optimal-processing        | `optimalProcessing`   |
| --snow-max-processing            | maxOutstandingItems   |
| --snow-max-time-processing       | maxItemProcessingTime |
| --snow-avalanche-batch-size      | `batchSize`           |
| --snow-avalanche-num-parents     | `parentSize`          |

#### `proposerMinBlockDelay` (duration)

The minimum delay performed when building snowman++ blocks. Default is set to 1 second.

As one of the ways to control network congestion, Snowman++ will only build a
block `proposerMinBlockDelay` after the parent block's timestamp. Some
high-performance custom VMs may find this too strict. This flag allows tuning the
frequency at which blocks are built.

### Gossip Configs

It's possible to define different Gossip configurations for each Subnet without
changing values for Primary Network. JSON keys of these
parameters are different from their matching `CLI` keys. These parameters
default to the same values used for the Primary Network. For more information
see [CLI Gossip Configs](https://build.avax.network/docs/nodes/configure/configs-flags#gossiping).

| CLI Key                                                 | JSON Key                               |
| :------------------------------------------------------ | :------------------------------------- |
| --consensus-accepted-frontier-gossip-validator-size     | gossipAcceptedFrontierValidatorSize    |
| --consensus-accepted-frontier-gossip-non-validator-size | gossipAcceptedFrontierNonValidatorSize |
| --consensus-accepted-frontier-gossip-peer-size          | gossipAcceptedFrontierPeerSize         |
| --consensus-on-accept-gossip-validator-size             | gossipOnAcceptValidatorSize            |
| --consensus-on-accept-gossip-non-validator-size         | gossipOnAcceptNonValidatorSize         |
| --consensus-on-accept-gossip-peer-size                  | gossipOnAcceptPeerSize                 |

# AvalancheGo Config Flags (/docs/nodes/configure/configs-flags)

---
title: "AvalancheGo Config Flags"
description: "This page lists all available configuration options for AvalancheGo nodes."
edit_url: https://github.com/ava-labs/avalanchego/edit/master/config/config.md
---

# AvalancheGo Configs and Flags

This document lists all available configuration options for AvalancheGo nodes. You can configure your node using either command-line flags or environment variables.

> **Note:** For comparison with the previous documentation format (using individual flag headings), see the [archived version](https://gist.github.com/navillanueva/cdb9c49c411bd89a9480f05a7afbab37).

<style>{`
.config-tables {
  overflow-x: auto;
}
.config-tables table {
  min-width: 1400px;
}
.config-tables td:nth-child(5) { 
  width: 50%;
}
.config-tables td:nth-child(-n+4) {
  white-space: nowrap;
}
`}</style>

## Environment Variable Naming Convention

All environment variables follow the pattern: `AVAGO_` + flag name where the flag name is converted to uppercase with hyphens replaced by underscores.

For example:
- Flag: `--api-admin-enabled`
- Environment Variable: `AVAGO_API_ADMIN_ENABLED`

## Example Usage

### Using Command-Line Flags

```bash
avalanchego --network-id=fuji --http-host=0.0.0.0 --log-level=debug
```

### Using Environment Variables

```bash
export AVAGO_NETWORK_ID=fuji
export AVAGO_HTTP_HOST=0.0.0.0
export AVAGO_LOG_LEVEL=debug
avalanchego
```

### Using Config File

Create a JSON config file:

```json
{
  "network-id": "fuji",
  "http-host": "0.0.0.0",
  "log-level": "debug"
}
```

Run with:

```bash
avalanchego --config-file=/path/to/config.json
```

## Configuration Precedence

Configuration sources are applied in the following order (highest to lowest precedence):

1. Command-line flags
2. Environment variables
3. Config file
4. Default values

# Configuration Options

<div className="config-tables">

### APIs

Configuration for various APIs exposed by the node.

| Flag | Env Var | Type | Default | Description |
|--------|--------|------|----|--------------------|
| `--api-admin-enabled` | `AVAGO_API_ADMIN_ENABLED` | bool | `false` | If set to `true`, this node will expose the Admin API. See [here](https://build.avax.network/docs/api-reference/admin-api) for more information. |
| `--api-health-enabled` | `AVAGO_API_HEALTH_ENABLED` | bool | `true` | If set to `false`, this node will not expose the Health API. See [here](https://build.avax.network/docs/api-reference/health-api) for more information. |
| `--index-enabled` | `AVAGO_INDEX_ENABLED` | bool | `false` | If set to `true`, this node will enable the indexer and the Index API will be available. See [here](https://build.avax.network/docs/api-reference/index-api) for more information. |
| `--api-info-enabled` | `AVAGO_API_INFO_ENABLED` | bool | `true` | If set to `false`, this node will not expose the Info API. See [here](https://build.avax.network/docs/api-reference/info-api) for more information. |
| `--api-metrics-enabled` | `AVAGO_API_METRICS_ENABLED` | bool | `true` | If set to `false`, this node will not expose the Metrics API. See [here](https://build.avax.network/docs/api-reference/metrics-api) for more information. |

### Avalanche Community Proposals

Support for [Avalanche Community Proposals](https://github.com/avalanche-foundation/ACPs).

| Flag | Env Var | Type | Default | Description |
|--------|--------|------|----|--------------------|
| `--acp-support` | `AVAGO_ACP_SUPPORT` | []int | `[]` | The `--acp-support` flag allows an AvalancheGo node to indicate support for a set of [Avalanche Community Proposals](https://github.com/avalanche-foundation/ACPs). |
| `--acp-object` | `AVAGO_ACP_OBJECT` | []int | `[]` | The `--acp-object` flag allows an AvalancheGo node to indicate objection for a set of [Avalanche Community Proposals](https://github.com/avalanche-foundation/ACPs). |

### Bootstrapping

Configuration for node bootstrapping process.

| Flag | Env Var | Type | Default | Description |
|--------|--------|------|----|--------------------|
| `--bootstrap-ancestors-max-containers-sent` | `AVAGO_BOOTSTRAP_ANCESTORS_MAX_CONTAINERS_SENT` | uint | `2000` | Max number of containers in an `Ancestors` message sent by this node. |
| `--bootstrap-ancestors-max-containers-received` | `AVAGO_BOOTSTRAP_ANCESTORS_MAX_CONTAINERS_RECEIVED` | uint | `2000` | This node reads at most this many containers from an incoming `Ancestors` message. |
| `--bootstrap-beacon-connection-timeout` | `AVAGO_BOOTSTRAP_BEACON_CONNECTION_TIMEOUT` | duration | `1m` | Timeout when attempting to connect to bootstrapping beacons. |
| `--bootstrap-ids` | `AVAGO_BOOTSTRAP_IDS` | string | network dependent | Bootstrap IDs is a comma-separated list of validator IDs. These IDs will be used to authenticate bootstrapping peers. An example setting of this field would be `--bootstrap-ids="NodeID-7Xhw2mDxuDS44j42TCB6U5579esbSt3Lg,NodeID-MFrZFVCXPv5iCn6M9K6XduxGTYp891xXZ"`. The number of given IDs here must be same with number of given `--bootstrap-ips`. The default value depends on the network ID. |
| `--bootstrap-ips` | `AVAGO_BOOTSTRAP_IPS` | string | network dependent | Bootstrap IPs is a comma-separated list of IP:port pairs. These IP Addresses will be used to bootstrap the current Avalanche state. An example setting of this field would be `--bootstrap-ips="127.0.0.1:12345,1.2.3.4:5678"`. The number of given IPs here must be same with number of given `--bootstrap-ids`. The default value depends on the network ID. |
| `--bootstrap-max-time-get-ancestors` | `AVAGO_BOOTSTRAP_MAX_TIME_GET_ANCESTORS` | duration | `50ms` | Max Time to spend fetching a container and its ancestors when responding to a GetAncestors message. |
| `--bootstrap-retry-enabled` | `AVAGO_BOOTSTRAP_RETRY_ENABLED` | bool | `true` | If set to `false`, will not retry bootstrapping if it fails. |
| `--bootstrap-retry-warn-frequency` | `AVAGO_BOOTSTRAP_RETRY_WARN_FREQUENCY` | uint | `50` | Specifies how many times bootstrap should be retried before warning the operator. |

### Chain Configuration

Some blockchains allow the node operator to provide custom configurations for individual blockchains. These custom configurations are broken down into two categories: network upgrades and optional chain configurations. AvalancheGo reads in these configurations from the chain configuration directory and passes them into the VM on initialization.

| Flag | Env Var | Type | Default | Description |
|--------|--------|------|----|--------------------|
| `--chain-config-dir` | `AVAGO_CHAIN_CONFIG_DIR` | string | `$HOME/.avalanchego/configs/chains` | Specifies the directory that contains chain configs, as described [here](https://build.avax.network/docs/nodes/chain-configs). If this flag is not provided and the default directory does not exist, AvalancheGo will not exit since custom configs are optional. However, if the flag is set, the specified folder must exist, or AvalancheGo will exit with an error. This flag is ignored if `--chain-config-content` is specified. Network upgrades are passed in from the location: `chain-config-dir`/`blockchainID`/`upgrade.*`. The chain configs are passed in from the location `chain-config-dir`/`blockchainID`/`config.*`. See [here](https://build.avax.network/docs/nodes/chain-configs) for more information. |
| `--chain-config-content` | `AVAGO_CHAIN_CONFIG_CONTENT` | string | - | As an alternative to `--chain-config-dir`, chains custom configurations can be loaded altogether from command line via `--chain-config-content` flag. Content must be base64 encoded. Example: First, encode the chain config: `echo -n '{"log-level":"trace"}' \| base64`. This will output something like `eyJsb2ctbGV2ZWwiOiJ0cmFjZSJ9`. Then create the full config JSON and encode it: `echo -n '{"C":{"Config":"eyJsb2ctbGV2ZWwiOiJ0cmFjZSJ9","Upgrade":null}}' \| base64`. Finally run: `avalanchego --chain-config-content "eyJDIjp7IkNvbmZpZyI6ImV5SnNiMmN0YkdWMlpXd2lPaUowY21GalpTSjkiLCJVcGdyYWRlIjpudWxsfX0="` |
| `--chain-aliases-file` | `AVAGO_CHAIN_ALIASES_FILE` | string | `~/.avalanchego/configs/chains/aliases.json` | Path to JSON file that defines aliases for Blockchain IDs. This flag is ignored if `--chain-aliases-file-content` is specified. Example content: `{"q2aTwKuyzgs8pynF7UXBZCU7DejbZbZ6EUyHr3JQzYgwNPUPi": ["DFK"]}`. The above example aliases the Blockchain whose ID is `"q2aTwKuyzgs8pynF7UXBZCU7DejbZbZ6EUyHr3JQzYgwNPUPi"` to `"DFK"`. Chain aliases are added after adding primary network aliases and before any changes to the aliases via the admin API. This means that the first alias included for a Blockchain on a Subnet will be treated as the `"Primary Alias"` instead of the full blockchainID. The Primary Alias is used in all metrics and logs. |
| `--chain-aliases-file-content` | `AVAGO_CHAIN_ALIASES_FILE_CONTENT` | string | - | As an alternative to `--chain-aliases-file`, it allows specifying base64 encoded aliases for Blockchains. |
| `--chain-data-dir` | `AVAGO_CHAIN_DATA_DIR` | string | `$HOME/.avalanchego/chainData` | Chain specific data directory. |

### Config File

| Flag | Env Var | Type | Default | Description |
|--------|--------|------|----|--------------------| 
|`--config-file` | `AVAGO_CONFIG_FILE` | string | - | Path to a JSON file that specifies this node's configuration. Command line arguments will override arguments set in the config file. This flag is ignored if `--config-file-content` is specified. Example JSON config file: `{"log-level": "debug"}`. [Install Script](https://build.avax.network/docs/tooling/avalanche-go-installer) creates the node config file at `~/.avalanchego/configs/node.json`. No default file is created if [AvalancheGo is built from source](https://build.avax.network/docs/nodes/run-a-node/from-source), you would need to create it manually if needed. |
| `--config-file-content` | `AVAGO_CONFIG_FILE_CONTENT` | string | - | As an alternative to `--config-file`, it allows specifying base64 encoded config content. |
| `--config-file-content-type` | `AVAGO_CONFIG_FILE_CONTENT_TYPE` | string | `JSON` | Specifies the format of the base64 encoded config content. JSON, TOML, YAML are among currently supported file format (see [here](https://github.com/spf13/viper#reading-config-files) for full list). |

### Data Directory

| Flag | Env Var | Type | Default | Description |
|--------|--------|------|----|--------------------|
| `--data-dir` | `AVAGO_DATA_DIR` | string | `$HOME/.avalanchego` | Sets the base data directory where default sub-directories will be placed unless otherwise specified. |

### Database

| Flag | Env Var | Type | Default  | Description |
|--------|--------|------|----|--------------------|
| `--db-dir` | `AVAGO_DB_DIR` | string | `$HOME/.avalanchego/db` | Specifies the directory to which the database is persisted. |
| `--db-type` | `AVAGO_DB_TYPE` | string | `leveldb` | Specifies the type of database to use. Must be one of `leveldb`, `memdb`, or `pebbledb`. `memdb` is an in-memory, non-persisted database. Note: `memdb` stores everything in memory. So if you have a 900 GiB LevelDB instance, then using `memdb` you'd need 900 GiB of RAM. `memdb` is useful for fast one-off testing, not for running an actual node (on Fuji or Mainnet). Also note that `memdb` doesn't persist after restart. So any time you restart the node it would start syncing from scratch. |

#### Database Config

| Flag | Env Var | Type | Default  | Description |
|--------|--------|------|----|--------------------|
| `--db-config-file` | `AVAGO_DB_CONFIG_FILE` | string | - | Path to the database config file. Ignored if `--db-config-file-content` is specified. |
| `--db-config-file-content` | `AVAGO_DB_CONFIG_FILE_CONTENT` | string | - | As an alternative to `--db-config-file`, it allows specifying base64 encoded database config content. |

A LevelDB config file must be JSON and may have these keys. Any keys not given will receive the default value. See [here](https://pkg.go.dev/github.com/syndtr/goleveldb/leveldb/opt#Options) for more information.

### File Descriptor Limit

| Flag | Env Var | Type | Default  | Description |
|--------|--------|------|----|--------------------|
| `--fd-limit` | `AVAGO_FD_LIMIT` | int | `32768` | Attempts to raise the process file descriptor limit to at least this value and error if the value is above the system max. |

### Genesis

| Flag | Env Var | Type | Default  | Description |
|--------|--------|------|----|--------------------|
| `--genesis-file` | `AVAGO_GENESIS_FILE` | string | - | Path to a JSON file containing the genesis data to use. Ignored when running standard networks (Mainnet, Fuji Testnet), or when `--genesis-file-content` is specified. If not given, uses default genesis data. See the documentation for the genesis JSON format [here](https://github.com/ava-labs/avalanchego/blob/master/genesis/README.md) and an example for a local network [here](https://github.com/ava-labs/avalanchego/blob/master/genesis/genesis_local.json). |
| `--genesis-file-content` | `AVAGO_GENESIS_FILE_CONTENT` | string | - | As an alternative to `--genesis-file`, it allows specifying base64 encoded genesis data to use. |

### HTTP Server

| Flag | Env Var | Type | Default  | Description |
|--------|--------|------|----|--------------------|
| `--http-allowed-hosts` | `AVAGO_HTTP_ALLOWED_HOSTS` | string | `localhost` | List of acceptable host names in API requests. Provide the wildcard (`'*'`) to accept requests from all hosts. API requests where the `Host` field is empty or an IP address will always be accepted. An API call whose HTTP `Host` field isn't acceptable will receive a 403 error code. |
| `--http-allowed-origins` | `AVAGO_HTTP_ALLOWED_ORIGINS` | string | `*` | Origins to allow on the HTTP port. Example: `"https://*.avax.network https://*.avax-test.network"` |
| `--http-host` | `AVAGO_HTTP_HOST` | string | `127.0.0.1` | The address that HTTP APIs listen on. This means that by default, your node can only handle API calls made from the same machine. To allow API calls from other machines, use `--http-host=`. You can also enter domain names as parameter. |
| `--http-port` | `AVAGO_HTTP_PORT` | int | `9650` | Each node runs an HTTP server that provides the APIs for interacting with the node and the Avalanche network. This argument specifies the port that the HTTP server will listen on. |
| `--http-idle-timeout` | `AVAGO_HTTP_IDLE_TIMEOUT` | duration | `120s` | Maximum duration to wait for the next request when keep-alives are enabled. If `--http-idle-timeout` is zero, the value of `--http-read-timeout` is used. If both are zero, there is no timeout. |
| `--http-read-timeout` | `AVAGO_HTTP_READ_TIMEOUT` | duration | `30s` | Maximum duration for reading the entire request, including the body. A zero or negative value means there will be no timeout. |
| `--http-read-header-timeout` | `AVAGO_HTTP_READ_HEADER_TIMEOUT` | duration | `30s` | Maximum duration to read request headers. The connection's read deadline is reset after reading the headers. If `--http-read-header-timeout` is zero, the value of `--http-read-timeout` is used. If both are zero, there is no timeout. |
| `--http-write-timeout` | `AVAGO_HTTP_WRITE_TIMEOUT` | duration | `30s` | Maximum duration before timing out writes of the response. It is reset whenever a new request's header is read. A zero or negative value means there will be no timeout. |
| `--http-shutdown-timeout` | `AVAGO_HTTP_SHUTDOWN_TIMEOUT` | duration | `10s` | Maximum duration to wait for existing connections to complete during node shutdown. |
| `--http-shutdown-wait` | `AVAGO_HTTP_SHUTDOWN_WAIT` | duration | `0s` | Duration to wait after receiving SIGTERM or SIGINT before initiating shutdown. The `/health` endpoint will return unhealthy during this duration (if the Health API is enabled.) |
| `--http-tls-enabled` | `AVAGO_HTTP_TLS_ENABLED` | boolean | `false` | If set to `true`, this flag will attempt to upgrade the server to use HTTPS. |
| `--http-tls-cert-file` | `AVAGO_HTTP_TLS_CERT_FILE` | string | - | This argument specifies the location of the TLS certificate used by the node for the HTTPS server. This must be specified when `--http-tls-enabled=true`. There is no default value. This flag is ignored if `--http-tls-cert-file-content` is specified. |
| `--http-tls-cert-file-content` | `AVAGO_HTTP_TLS_CERT_FILE_CONTENT` | string | - | As an alternative to `--http-tls-cert-file`, it allows specifying base64 encoded content of the TLS certificate used by the node for the HTTPS server. Note that full certificate content, with the leading and trailing header, must be base64 encoded. This must be specified when `--http-tls-enabled=true`. |
| `--http-tls-key-file` | `AVAGO_HTTP_TLS_KEY_FILE` | string | - | This argument specifies the location of the TLS private key used by the node for the HTTPS server. This must be specified when `--http-tls-enabled=true`. There is no default value. This flag is ignored if `--http-tls-key-file-content` is specified. |
| `--http-tls-key-file-content` | `AVAGO_HTTP_TLS_KEY_FILE_CONTENT` | string | - | As an alternative to `--http-tls-key-file`, it allows specifying base64 encoded content of the TLS private key used by the node for the HTTPS server. Note that full private key content, with the leading and trailing header, must be base64 encoded. This must be specified when `--http-tls-enabled=true`. |

### Logging

| Flag | Env Var | Type | Default | Description |
|--------|--------|------|----|--------------------|
| `--log-level=off` | `AVAGO_LOG_LEVEL` | string | `info` | No logs. |
| `--log-level=fatal` | `AVAGO_LOG_LEVEL` | string | `info` | Fatal errors that are not recoverable. |
| `--log-level=error` | `AVAGO_LOG_LEVEL` | string | `info` | Errors that the node encounters, these errors were able to be recovered. |
| `--log-level=warn` | `AVAGO_LOG_LEVEL` | string | `info` | Warnings that might be indicative of a spurious byzantine node, or potential future error. |
| `--log-level=info` | `AVAGO_LOG_LEVEL` | string | `info` | Useful descriptions of node status updates. |
| `--log-level=trace` | `AVAGO_LOG_LEVEL` | string | `info` | Traces container job results, useful for tracing container IDs and their outcomes. |
| `--log-level=debug` | `AVAGO_LOG_LEVEL` | string | `info` | Useful when attempting to understand possible bugs in the code. |
| `--log-level=verbo` | `AVAGO_LOG_LEVEL` | string | `info` | Tracks extensive amounts of information the node is processing, including message contents and binary dumps of data for extremely low level protocol analysis. |
| `--log-display-level` | `AVAGO_LOG_DISPLAY_LEVEL` | string | value of `--log-level` | The log level determines which events to display to stdout. If left blank, will default to the value provided to `--log-level`. |
| `--log-format=auto` | `AVAGO_LOG_FORMAT` | string | `auto` | Formats terminal-like logs when the output is a terminal. |
| `--log-format=plain` | `AVAGO_LOG_FORMAT` | string | `auto` | Plain text log format. |
| `--log-format=colors` | `AVAGO_LOG_FORMAT` | string | `auto` | Colored log format. |
| `--log-format=json` | `AVAGO_LOG_FORMAT` | string | `auto` | JSON log format. |
| `--log-dir` | `AVAGO_LOG_DIR` | string | `$HOME/.avalanchego/logs` | Specifies the directory in which system logs are kept. If you are running the node as a system service (ex. using the installer script) logs will also be stored in `$HOME/var/log/syslog`. |
| `--log-disable-display-plugin-logs` | `AVAGO_LOG_DISABLE_DISPLAY_PLUGIN_LOGS` | boolean | `false` | Disables displaying plugin logs in stdout. |
| `--log-rotater-max-size` | `AVAGO_LOG_ROTATER_MAX_SIZE` | uint | `8` | The maximum file size in megabytes of the log file before it gets rotated. |
| `--log-rotater-max-files` | `AVAGO_LOG_ROTATER_MAX_FILES` | uint | `7` | The maximum number of old log files to retain. 0 means retain all old log files. |
| `--log-rotater-max-age` | `AVAGO_LOG_ROTATER_MAX_AGE` | uint | `0` | The maximum number of days to retain old log files based on the timestamp encoded in their filename. 0 means retain all old log files. |
| `--log-rotater-compress-enabled` | `AVAGO_LOG_ROTATER_COMPRESS_ENABLED` | boolean | `false` | Enables the compression of rotated log files through gzip. |

### Continuous Profiling

You can configure your node to continuously run memory/CPU profiles and save the most recent ones. Continuous memory/CPU profiling is enabled if `--profile-continuous-enabled` is set.

| Flag | Env Var | Type | Default | Description |
|--------|--------|------|----|--------------------|
| `--profile-continuous-enabled` | `AVAGO_PROFILE_CONTINUOUS_ENABLED` | boolean | `false` | Whether the app should continuously produce performance profiles. |
| `--profile-dir` | `AVAGO_PROFILE_DIR` | string | `$HOME/.avalanchego/profiles/` | If profiling is enabled, node continuously runs memory/CPU profiles and puts them at this directory. |
| `--profile-continuous-freq` | `AVAGO_PROFILE_CONTINUOUS_FREQ` | duration | `15m` | How often a new CPU/memory profile is created. |
| `--profile-continuous-max-files` | `AVAGO_PROFILE_CONTINUOUS_MAX_FILES` | int | `5` | Maximum number of CPU/memory profile files to keep. |

### Network

| Flag | Env Var | Type | Default | Description |
|--------|--------|------|----|--------------------|
| `--network-id=mainnet` | `AVAGO_NETWORK_ID` | string | `mainnet` | Connect to Mainnet (default). |
| `--network-id=fuji` | `AVAGO_NETWORK_ID` | string | `mainnet` | Connect to the Fuji test-network. |
| `--network-id=testnet` | `AVAGO_NETWORK_ID` | string | `mainnet` | Connect to the current test-network (currently Fuji). |
| `--network-id=local` | `AVAGO_NETWORK_ID` | string | `mainnet` | Connect to a local test-network. |
| `--network-id=network-[id]` | `AVAGO_NETWORK_ID` | string | `mainnet` | Connect to the network with the given ID. `id` must be in the range \[0, 2^32\). |

### OpenTelemetry

AvalancheGo supports collecting and exporting [OpenTelemetry](https://opentelemetry.io/) traces. This might be useful for debugging, performance analysis, or monitoring.

| Flag | Env Var | Type | Default | Description |
|--------|--------|------|----|--------------------|
| `--tracing-endpoint` | `AVAGO_TRACING_ENDPOINT` | string | `localhost:4317` (gRPC) or `localhost:4318` (HTTP) | The endpoint to export trace data to. Default depends on `--tracing-exporter-type`. |
| `--tracing-exporter-type` | `AVAGO_TRACING_EXPORTER_TYPE` | string | `disabled` | Type of exporter to use for tracing. Options are \`disabled\`, \`grpc\`, \`http\`. |
| `--tracing-insecure` | `AVAGO_TRACING_INSECURE` | boolean | `true` | If true, don't use TLS when exporting trace data. |
| `--tracing-sample-rate` | `AVAGO_TRACING_SAMPLE_RATE` | float | `0.1` | The fraction of traces to sample. If \>= 1, always sample. If \<= 0, never sample. |

### Partial Sync Primary Network

| Flag | Env Var | Type | Default | Description |
|--------|--------|------|----|--------------------|
| `--partial-sync-primary-network` | `AVAGO_PARTIAL_SYNC_PRIMARY_NETWORK` | boolean | `false` | Partial sync enables nodes that are not primary network validators to optionally sync only the P-chain on the primary network. Nodes that use this option can still track Subnets. After the Etna upgrade, nodes that use this option can also validate L1s. |

### Public IP

Validators must know one of their public facing IP addresses so they can enable other nodes to connect to them. By default, the node will attempt to perform NAT traversal to get the node's IP according to its router.

| Flag | Env Var | Type | Default | Description |
|--------|--------|------|----|--------------------|
| `--public-ip` | `AVAGO_PUBLIC_IP` | string | - | If this argument is provided, the node assumes this is its public IP. When running a local network it may be easiest to set this value to `127.0.0.1`. |
| `--public-ip-resolution-frequency` | `AVAGO_PUBLIC_IP_RESOLUTION_FREQUENCY` | duration | `5m` | Frequency at which this node resolves/updates its public IP and renew NAT mappings, if applicable. |
| `--public-ip-resolution-service` | `AVAGO_PUBLIC_IP_RESOLUTION_SERVICE` | string | - | When provided, the node will use that service to periodically resolve/update its public IP. Only acceptable values are `ifconfigCo`, `opendns` or `ifconfigMe`. |

### State Syncing

| Flag | Env Var | Type | Default | Description |
|--------|--------|------|----|--------------------|
| `--state-sync-ids` | `AVAGO_STATE_SYNC_IDS` | string | - | State sync IDs is a comma-separated list of validator IDs. The specified validators will be contacted to get and authenticate the starting point (state summary) for state sync. An example setting of this field would be `--state-sync-ids="NodeID-7Xhw2mDxuDS44j42TCB6U5579esbSt3Lg,NodeID-MFrZFVCXPv5iCn6M9K6XduxGTYp891xXZ"`. The number of given IDs here must be same with number of given `--state-sync-ips`. The default value is empty, which results in all validators being sampled. |
| `--state-sync-ips` | `AVAGO_STATE_SYNC_IPS` | string | - | State sync IPs is a comma-separated list of IP:port pairs. These IP Addresses will be contacted to get and authenticate the starting point (state summary) for state sync. An example setting of this field would be `--state-sync-ips="127.0.0.1:12345,1.2.3.4:5678"`. The number of given IPs here must be the same with the number of given `--state-sync-ids`. |

### Staking

| Flag | Env Var | Type | Default | Description |
|--------|--------|------|----|--------------------|
| `--staking-port` | `AVAGO_STAKING_PORT` | int | `9651` | The port through which the network peers will connect to this node externally. Having this port accessible from the internet is required for correct node operation. |
| `--staking-tls-cert-file` | `AVAGO_STAKING_TLS_CERT_FILE` | string | `$HOME/.avalanchego/staking/staker.crt` | Avalanche uses two-way authenticated TLS connections to securely connect nodes. This argument specifies the location of the TLS certificate used by the node. This flag is ignored if `--staking-tls-cert-file-content` is specified. |
| `--staking-tls-cert-file-content` | `AVAGO_STAKING_TLS_CERT_FILE_CONTENT` | string | - | As an alternative to `--staking-tls-cert-file`, it allows specifying base64 encoded content of the TLS certificate used by the node. Note that full certificate content, with the leading and trailing header, must be base64 encoded. |
| `--staking-tls-key-file` | `AVAGO_STAKING_TLS_KEY_FILE` | string | `$HOME/.avalanchego/staking/staker.key` | Avalanche uses two-way authenticated TLS connections to securely connect nodes. This argument specifies the location of the TLS private key used by the node. This flag is ignored if `--staking-tls-key-file-content` is specified. |
| `--staking-tls-key-file-content` | `AVAGO_STAKING_TLS_KEY_FILE_CONTENT` | string | - | As an alternative to `--staking-tls-key-file`, it allows specifying base64 encoded content of the TLS private key used by the node. Note that full private key content, with the leading and trailing header, must be base64 encoded. |

### Subnets

#### Subnet Tracking

| Flag | Env Var | Type | Default | Description |
|--------|--------|------|----|--------------------|
| `--track-subnets` | `AVAGO_TRACK_SUBNETS` | string | - | Comma separated list of Subnet IDs that this node would track if added to. Defaults to empty (will only validate the Primary Network). |

#### Subnet Configs

It is possible to provide parameters for Subnets. Parameters here apply to all chains in the specified Subnets. Parameters must be specified with a `[subnetID].json` config file under `--subnet-config-dir`. AvalancheGo loads configs for Subnets specified in `--track-subnets` parameter. Full reference for all configuration options for a Subnet can be found in a separate [Subnet Configs](https://build.avax.network/docs/nodes/configure/avalanche-l1-configs) document.

| Flag | Env Var | Type | Default | Description |
|--------|--------|------|----|--------------------|
| `--subnet-config-dir` | `AVAGO_SUBNET_CONFIG_DIR` | string | `$HOME/.avalanchego/configs/subnets` | Specifies the directory that contains Subnet configs, as described above. If the flag is set explicitly, the specified folder must exist, or AvalancheGo will exit with an error. This flag is ignored if `--subnet-config-content` is specified. Example: Let's say we have a Subnet with ID `p4jUwqZsA2LuSftroCd3zb4ytH8W99oXKuKVZdsty7eQ3rXD6`. We can create a config file under the default `subnet-config-dir` at `$HOME/.avalanchego/configs/subnets/p4jUwqZsA2LuSftroCd3zb4ytH8W99oXKuKVZdsty7eQ3rXD6.json`. An example config file is: `{"validatorOnly": false, "consensusParameters": {"k": 25, "alpha": 18}}`. By default, none of these directories and/or files exist. You would need to create them manually if needed. |
| `--subnet-config-content` | `AVAGO_SUBNET_CONFIG_CONTENT` | string | - | As an alternative to `--subnet-config-dir`, it allows specifying base64 encoded parameters for a Subnet. |

### Version

| Flag | Env Var | Type | Default | Description |
|--------|--------|------|----|--------------------|
| `--version` | `AVAGO_VERSION` | boolean | `false` | If this is `true`, print the version and quit. |

# Advanced Configuration Options

⚠️ **Warning**: The following options may affect the correctness of a node. Only power users should change these.

### Gossiping

Consensus gossiping parameters.

| Flag | Env Var | Type | Default | Description |
|--------|--------|------|----|--------------------|
| `--consensus-accepted-frontier-gossip-validator-size` | `AVAGO_CONSENSUS_ACCEPTED_FRONTIER_GOSSIP_VALIDATOR_SIZE` | uint | `0` | Number of validators to gossip to when gossiping accepted frontier. |
| `--consensus-accepted-frontier-gossip-non-validator-size` | `AVAGO_CONSENSUS_ACCEPTED_FRONTIER_GOSSIP_NON_VALIDATOR_SIZE` | uint | `0` | Number of non-validators to gossip to when gossiping accepted frontier. |
| `--consensus-accepted-frontier-gossip-peer-size` | `AVAGO_CONSENSUS_ACCEPTED_FRONTIER_GOSSIP_PEER_SIZE` | uint | `15` | Number of peers to gossip to when gossiping accepted frontier. |
| `--consensus-accepted-frontier-gossip-frequency` | `AVAGO_CONSENSUS_ACCEPTED_FRONTIER_GOSSIP_FREQUENCY` | duration | `10s` | Time between gossiping accepted frontiers. |
| `--consensus-on-accept-gossip-validator-size` | `AVAGO_CONSENSUS_ON_ACCEPT_GOSSIP_VALIDATOR_SIZE` | uint | `0` | Number of validators to gossip to each accepted container to. |
| `--consensus-on-accept-gossip-non-validator-size` | `AVAGO_CONSENSUS_ON_ACCEPT_GOSSIP_NON_VALIDATOR_SIZE` | uint | `0` | Number of non-validators to gossip to each accepted container to. |
| `--consensus-on-accept-gossip-peer-size` | `AVAGO_CONSENSUS_ON_ACCEPT_GOSSIP_PEER_SIZE` | uint | `10` | Number of peers to gossip to each accepted container to. |

### Sybil Protection

Sybil protection configuration. These settings affect how the node participates in consensus.

| Flag | Env Var | Type | Default | Description |
|--------|--------|------|----|--------------------|
| `--sybil-protection-enabled` | `AVAGO_SYBIL_PROTECTION_ENABLED` | boolean | `true` | Avalanche uses Proof of Stake (PoS) as sybil resistance to make it prohibitively expensive to attack the network. If false, sybil resistance is disabled and all peers will be sampled during consensus. Note that this can not be disabled on public networks (`Fuji` and `Mainnet`). Setting this flag to `false` **does not** mean "this node is not a validator." It means that this node will sample all nodes, not just validators. **You should not set this flag to false unless you understand what you are doing.** |
| `--sybil-protection-disabled-weight` | `AVAGO_SYBIL_PROTECTION_DISABLED_WEIGHT` | uint | `100` | Weight to provide to each peer when staking is disabled. |

### Benchlist

Peer benchlisting configuration.

| Flag | Env Var | Type | Default | Description |
|--------|--------|------|----|--------------------|
| `--benchlist-duration` | `AVAGO_BENCHLIST_DURATION` | duration | `15m` | Maximum amount of time a peer is benchlisted after surpassing `--benchlist-fail-threshold`. |
| `--benchlist-fail-threshold` | `AVAGO_BENCHLIST_FAIL_THRESHOLD` | int | `10` | Number of consecutive failed queries to a node before benching it (assuming all queries to it will fail). |
| `--benchlist-min-failing-duration` | `AVAGO_BENCHLIST_MIN_FAILING_DURATION` | duration | `150s` | Minimum amount of time queries to a peer must be failing before the peer is benched. |

### Consensus Parameters

:::note
Some of these parameters can only be set on a local or private network, not on Fuji Testnet or Mainnet
:::

| Flag | Env Var | Type | Default | Description |
|--------|--------|------|----|--------------------|
| `--consensus-shutdown-timeout` | `AVAGO_CONSENSUS_SHUTDOWN_TIMEOUT` | duration | `5s` | Timeout before killing an unresponsive chain. |
| `--create-asset-tx-fee` | `AVAGO_CREATE_ASSET_TX_FEE` | int | `10000000` | Transaction fee, in nAVAX, for transactions that create new assets. This can only be changed on a local network. |
| `--tx-fee` | `AVAGO_TX_FEE` | int | `1000000` | The required amount of nAVAX to be burned for a transaction to be valid on the X-Chain, and for import/export transactions on the P-Chain. This parameter requires network agreement in its current form. Changing this value from the default should only be done on private networks or local network. |
| `--uptime-requirement` | `AVAGO_UPTIME_REQUIREMENT` | float | `0.8` | Fraction of time a validator must be online to receive rewards. This can only be changed on a local network. |
| `--uptime-metric-freq` | `AVAGO_UPTIME_METRIC_FREQ` | duration | `30s` | Frequency of renewing this node's average uptime metric. |

### Staking Parameters

Staking economics configuration.

| Flag | Env Var | Type | Default | Description |
|--------|--------|------|----|--------------------|
| `--min-validator-stake` | `AVAGO_MIN_VALIDATOR_STAKE` | int | network dependent | The minimum stake, in nAVAX, required to validate the Primary Network. This can only be changed on a local network. Defaults to `2000000000000` (2,000 AVAX) on Mainnet. Defaults to `5000000` (.005 AVAX) on Test Net. |
| `--max-validator-stake` | `AVAGO_MAX_VALIDATOR_STAKE` | int | network dependent | The maximum stake, in nAVAX, that can be placed on a validator on the primary network. This includes stake provided by both the validator and by delegators to the validator. This can only be changed on a local network. |
| `--min-delegator-stake` | `AVAGO_MIN_DELEGATOR_STAKE` | int | network dependent | The minimum stake, in nAVAX, that can be delegated to a validator of the Primary Network. Defaults to `25000000000` (25 AVAX) on Mainnet. Defaults to `5000000` (.005 AVAX) on Test Net. This can only be changed on a local network. |
| `--min-delegation-fee` | `AVAGO_MIN_DELEGATION_FEE` | int | `20000` | The minimum delegation fee that can be charged for delegation on the Primary Network, multiplied by \`10,000\`. Must be in the range \[0, 1000000\]. This can only be changed on a local network. |
| `--min-stake-duration` | `AVAGO_MIN_STAKE_DURATION` | duration | `336h` | Minimum staking duration. This can only be changed on a local network. This applies to both delegation and validation periods. |
| `--max-stake-duration` | `AVAGO_MAX_STAKE_DURATION` | duration | `8760h` | The maximum staking duration, in hours. This can only be changed on a local network. |
| `--stake-minting-period` | `AVAGO_STAKE_MINTING_PERIOD` | duration | `8760h` | Consumption period of the staking function, in hours. This can only be changed on a local network. |
| `--stake-max-consumption-rate` | `AVAGO_STAKE_MAX_CONSUMPTION_RATE` | uint | `120000` | The maximum percentage of the consumption rate for the remaining token supply in the minting period, which is 1 year on Mainnet. This can only be changed on a local network. |
| `--stake-min-consumption-rate` | `AVAGO_STAKE_MIN_CONSUMPTION_RATE` | uint | `100000` | The minimum percentage of the consumption rate for the remaining token supply in the minting period, which is 1 year on Mainnet. This can only be changed on a local network. |
| `--stake-supply-cap` | `AVAGO_STAKE_SUPPLY_CAP` | uint | `720000000000000000` | The maximum stake supply, in nAVAX, that can be placed on a validator. This can only be changed on a local network. |

### Snow Consensus

Snow consensus protocol parameters.

| Flag | Env Var | Type | Default | Description |
|--------|--------|------|----|--------------------|
| `--snow-concurrent-repolls` | `AVAGO_SNOW_CONCURRENT_REPOLLS` | int | `4` | Snow consensus requires repolling transactions that are issued during low time of network usage. This parameter lets one define how aggressive the client will be in finalizing these pending transactions. This should only be changed after careful consideration of the tradeoffs of Snow consensus. The value must be at least `1` and at most `--snow-commit-threshold`. |
| `--snow-sample-size` | `AVAGO_SNOW_SAMPLE_SIZE` | int | `20` | Snow consensus defines `k` as the number of validators that are sampled during each network poll. This parameter lets one define the `k` value used for consensus. This should only be changed after careful consideration of the tradeoffs of Snow consensus. The value must be at least `1`. |
| `--snow-quorum-size` | `AVAGO_SNOW_QUORUM_SIZE` | int | `15` | Snow consensus defines `alpha` as the number of validators that must prefer a transaction during each network poll to increase the confidence in the transaction. This parameter lets us define the `alpha` value used for consensus. This should only be changed after careful consideration of the tradeoffs of Snow consensus. The value must be at greater than `k/2`. |
| `--snow-commit-threshold` | `AVAGO_SNOW_COMMIT_THRESHOLD` | int | `20` | Snow consensus defines `beta` as the number of consecutive polls that a container must increase its confidence for it to be accepted. This parameter lets us define the `beta` value used for consensus. This should only be changed after careful consideration of the tradeoffs of Snow consensus. The value must be at least `1`. |
| `--snow-optimal-processing` | `AVAGO_SNOW_OPTIMAL_PROCESSING` | int | `50` | Optimal number of processing items in consensus. The value must be at least `1`. |
| `--snow-max-processing` | `AVAGO_SNOW_MAX_PROCESSING` | int | `1024` | Maximum number of processing items to be considered healthy. Reports unhealthy if more than this number of items are outstanding. The value must be at least `1`. |
| `--snow-max-time-processing` | `AVAGO_SNOW_MAX_TIME_PROCESSING` | duration | `2m` | Maximum amount of time an item should be processing and still be healthy. Reports unhealthy if there is an item processing for longer than this duration. The value must be greater than `0`. |

### ProposerVM

ProposerVM configuration.

| Flag | Env Var | Type | Default | Description |
|--------|--------|------|----|--------------------|
| `--proposervm-use-current-height` | `AVAGO_PROPOSERVM_USE_CURRENT_HEIGHT` | boolean | `false` | Have the ProposerVM always report the last accepted P-chain block height. |
| `--proposervm-min-block-delay` | `AVAGO_PROPOSERVM_MIN_BLOCK_DELAY` | duration | `1s` | The minimum delay to enforce when building a snowman++ block for the primary network chains and the default minimum delay for subnets. A non-default value is only suggested for non-production nodes. |

### Health Checks

Health monitoring configuration.

| Flag | Env Var | Type | Default | Description |
|--------|--------|------|----|--------------------|
| `--health-check-frequency` | `AVAGO_HEALTH_CHECK_FREQUENCY` | duration | `30s` | Health check runs with this frequency. |
| `--health-check-averager-halflife` | `AVAGO_HEALTH_CHECK_AVERAGER_HALFLIFE` | duration | `10s` | Half life of averagers used in health checks (to measure the rate of message failures, for example.) Larger value -> less volatile calculation of averages. |

### Network Configuration

Advanced network settings.

| Flag | Env Var | Type | Default | Description |
|--------|--------|------|----|--------------------|
| `--network-allow-private-ips` | `AVAGO_NETWORK_ALLOW_PRIVATE_IPS` | boolean | `true` | Allows the node to connect peers with private IPs. |
| `--network-compression-type` | `AVAGO_NETWORK_COMPRESSION_TYPE` | string | `gzip` | The type of compression to use when sending messages to peers. Must be one of \`gzip\`, \`zstd\`, \`none\`. Nodes can handle inbound \`gzip\` compressed messages but by default send \`zstd\` compressed messages. |
| `--network-initial-timeout` | `AVAGO_NETWORK_INITIAL_TIMEOUT` | duration | `5s` | Initial timeout value of the adaptive timeout manager. |
| `--network-initial-reconnect-delay` | `AVAGO_NETWORK_INITIAL_RECONNECT_DELAY` | duration | `1s` | Initial delay duration must be waited before attempting to reconnect a peer. |
| `--network-max-reconnect-delay` | `AVAGO_NETWORK_MAX_RECONNECT_DELAY` | duration | `1h` | Maximum delay duration must be waited before attempting to reconnect a peer. |
| `--network-minimum-timeout` | `AVAGO_NETWORK_MINIMUM_TIMEOUT` | duration | `2s` | Minimum timeout value of the adaptive timeout manager. |
| `--network-maximum-timeout` | `AVAGO_NETWORK_MAXIMUM_TIMEOUT` | duration | `10s` | Maximum timeout value of the adaptive timeout manager. |
| `--network-maximum-inbound-timeout` | `AVAGO_NETWORK_MAXIMUM_INBOUND_TIMEOUT` | duration | `10s` | Maximum timeout value of an inbound message. Defines duration within which an incoming message must be fulfilled. Incoming messages containing deadline higher than this value will be overridden with this value. |
| `--network-timeout-halflife` | `AVAGO_NETWORK_TIMEOUT_HALFLIFE` | duration | `5m` | Half life used when calculating average network latency. Larger value -> less volatile network latency calculation. |
| `--network-timeout-coefficient` | `AVAGO_NETWORK_TIMEOUT_COEFFICIENT` | float | `2` | Requests to peers will time out after \[network-timeout-coefficient\] \* \[average request latency\]. |
| `--network-read-handshake-timeout` | `AVAGO_NETWORK_READ_HANDSHAKE_TIMEOUT` | duration | `15s` | Timeout value for reading handshake messages. |
| `--network-ping-timeout` | `AVAGO_NETWORK_PING_TIMEOUT` | duration | `30s` | Timeout value for Ping-Pong with a peer. |
| `--network-ping-frequency` | `AVAGO_NETWORK_PING_FREQUENCY` | duration | `22.5s` | Frequency of pinging other peers. |
| `--network-health-min-conn-peers` | `AVAGO_NETWORK_HEALTH_MIN_CONN_PEERS` | uint | `1` | Node will report unhealthy if connected to less than this many peers. |
| `--network-health-max-time-since-msg-received` | `AVAGO_NETWORK_HEALTH_MAX_TIME_SINCE_MSG_RECEIVED` | duration | `1m` | Node will report unhealthy if it hasn't received a message for this amount of time. |
| `--network-health-max-time-since-msg-sent` | `AVAGO_NETWORK_HEALTH_MAX_TIME_SINCE_MSG_SENT` | duration | `1m` | Network layer returns unhealthy if haven't sent a message for at least this much time. |
| `--network-health-max-portion-send-queue-full` | `AVAGO_NETWORK_HEALTH_MAX_PORTION_SEND_QUEUE_FULL` | float | `0.9` | Node will report unhealthy if its send queue is more than this portion full. Must be in \[0,1\]. |
| `--network-health-max-send-fail-rate` | `AVAGO_NETWORK_HEALTH_MAX_SEND_FAIL_RATE` | float | `0.25` | Node will report unhealthy if more than this portion of message sends fail. Must be in \[0,1\]. |
| `--network-health-max-outstanding-request-duration` | `AVAGO_NETWORK_HEALTH_MAX_OUTSTANDING_REQUEST_DURATION` | duration | `5m` | Node reports unhealthy if there has been a request outstanding for this duration. |
| `--network-max-clock-difference` | `AVAGO_NETWORK_MAX_CLOCK_DIFFERENCE` | duration | `1m` | Max allowed clock difference value between this node and peers. |
| `--network-require-validator-to-connect` | `AVAGO_NETWORK_REQUIRE_VALIDATOR_TO_CONNECT` | boolean | `false` | If true, this node will only maintain a connection with another node if this node is a validator, the other node is a validator, or the other node is a beacon. |
| `--network-tcp-proxy-enabled` | `AVAGO_NETWORK_TCP_PROXY_ENABLED` | boolean | `false` | Require all P2P connections to be initiated with a TCP proxy header. |
| `--network-tcp-proxy-read-timeout` | `AVAGO_NETWORK_TCP_PROXY_READ_TIMEOUT` | duration | `3s` | Maximum duration to wait for a TCP proxy header. |
| `--network-outbound-connection-timeout` | `AVAGO_NETWORK_OUTBOUND_CONNECTION_TIMEOUT` | duration | `30s` | Timeout while dialing a peer. |

### Message Rate-Limiting

These flags govern rate-limiting of inbound and outbound messages. For more information on rate-limiting and the flags below, see package `throttling` in AvalancheGo.

#### CPU Based Rate-Limiting

Rate-limiting based on how much CPU usage a peer causes.

| Flag | Env Var | Type | Default | Description |
|--------|--------|------|----|--------------------|
| `--throttler-inbound-cpu-validator-alloc` | `AVAGO_THROTTLER_INBOUND_CPU_VALIDATOR_ALLOC` | float | half of CPUs | Number of CPU allocated for use by validators. Value should be in range \(0, total core count\]. |
| `--throttler-inbound-cpu-max-recheck-delay` | `AVAGO_THROTTLER_INBOUND_CPU_MAX_RECHECK_DELAY` | duration | `5s` | In the CPU rate-limiter, check at least this often whether the node's CPU usage has fallen to an acceptable level. |
| `--throttler-inbound-disk-max-recheck-delay` | `AVAGO_THROTTLER_INBOUND_DISK_MAX_RECHECK_DELAY` | duration | `5s` | In the disk-based network throttler, check at least this often whether the node's disk usage has fallen to an acceptable level. |
| `--throttler-inbound-cpu-max-non-validator-usage` | `AVAGO_THROTTLER_INBOUND_CPU_MAX_NON_VALIDATOR_USAGE` | float | 80% of CPUs | Number of CPUs that if fully utilized, will rate limit all non-validators. Value should be in range \[0, total core count\]. |
| `--throttler-inbound-cpu-max-non-validator-node-usage` | `AVAGO_THROTTLER_INBOUND_CPU_MAX_NON_VALIDATOR_NODE_USAGE` | float | CPUs / 8 | Maximum number of CPUs that a non-validator can utilize. Value should be in range \[0, total core count\]. |
| `--throttler-inbound-disk-validator-alloc` | `AVAGO_THROTTLER_INBOUND_DISK_VALIDATOR_ALLOC` | float | `1000 GiB/s` | Maximum number of disk reads/writes per second to allocate for use by validators. Must be > 0. |
| `--throttler-inbound-disk-max-non-validator-usage` | `AVAGO_THROTTLER_INBOUND_DISK_MAX_NON_VALIDATOR_USAGE` | float | `1000 GiB/s` | Number of disk reads/writes per second that, if fully utilized, will rate limit all non-validators. Must be \>= 0. |
| `--throttler-inbound-disk-max-non-validator-node-usage` | `AVAGO_THROTTLER_INBOUND_DISK_MAX_NON_VALIDATOR_NODE_USAGE` | float | `1000 GiB/s` | Maximum number of disk reads/writes per second that a non-validator can utilize. Must be \>= 0. |

#### Bandwidth Based Rate-Limiting

Rate-limiting based on the bandwidth a peer uses.

| Flag | Env Var | Type | Default | Description |
|--------|--------|------|----|--------------------|
| `--throttler-inbound-bandwidth-refill-rate` | `AVAGO_THROTTLER_INBOUND_BANDWIDTH_REFILL_RATE` | uint | `512` | Max average inbound bandwidth usage of a peer, in bytes per second. See interface `throttling.BandwidthThrottler`. |
| `--throttler-inbound-bandwidth-max-burst-size` | `AVAGO_THROTTLER_INBOUND_BANDWIDTH_MAX_BURST_SIZE` | uint | `2 MiB` | Max inbound bandwidth a node can use at once. See interface `throttling.BandwidthThrottler`. |

#### Message Size Based Rate-Limiting

Rate-limiting based on the total size, in bytes, of unprocessed messages.

| Flag | Env Var | Type | Default | Description |
|--------|--------|------|----|--------------------|
| `--throttler-inbound-at-large-alloc-size` | `AVAGO_THROTTLER_INBOUND_AT_LARGE_ALLOC_SIZE` | uint | `6 MiB` | Size, in bytes, of at-large allocation in the inbound message throttler. |
| `--throttler-inbound-validator-alloc-size` | `AVAGO_THROTTLER_INBOUND_VALIDATOR_ALLOC_SIZE` | uint | `32 MiB` | Size, in bytes, of validator allocation in the inbound message throttler. |
| `--throttler-inbound-node-max-at-large-bytes` | `AVAGO_THROTTLER_INBOUND_NODE_MAX_AT_LARGE_BYTES` | uint | `2 MiB` | Maximum number of bytes a node can take from the at-large allocation of the inbound message throttler. |

#### Message Based Rate-Limiting

Rate-limiting based on the number of unprocessed messages.

| Flag | Env Var | Type | Default | Description |
|--------|--------|------|----|--------------------|
| `--throttler-inbound-node-max-processing-msgs` | `AVAGO_THROTTLER_INBOUND_NODE_MAX_PROCESSING_MSGS` | uint | `1024` | Node will stop reading messages from a peer when it is processing this many messages from the peer. Will resume reading messages from the peer when it is processing less than this many messages. |

#### Outbound Rate-Limiting

Rate-limiting for outbound messages.

| Flag | Env Var | Type | Default | Description |
|--------|--------|------|----|--------------------|
| `--throttler-outbound-at-large-alloc-size` | `AVAGO_THROTTLER_OUTBOUND_AT_LARGE_ALLOC_SIZE` | uint | `32 MiB` | Size, in bytes, of at-large allocation in the outbound message throttler. |
| `--throttler-outbound-validator-alloc-size` | `AVAGO_THROTTLER_OUTBOUND_VALIDATOR_ALLOC_SIZE` | uint | `32 MiB` | Size, in bytes, of validator allocation in the outbound message throttler. |
| `--throttler-outbound-node-max-at-large-bytes` | `AVAGO_THROTTLER_OUTBOUND_NODE_MAX_AT_LARGE_BYTES` | uint | `2 MiB` | Maximum number of bytes a node can take from the at-large allocation of the outbound message throttler. |

### Connection Rate-Limiting

| Flag | Env Var | Type | Default | Description |
|--------|--------|------|----|--------------------|
| `--network-inbound-connection-throttling-cooldown` | `AVAGO_NETWORK_INBOUND_CONNECTION_THROTTLING_COOLDOWN` | duration | `10s` | Node will upgrade an inbound connection from a given IP at most once within this duration. If 0 or negative, will not consider recency of last upgrade when deciding whether to upgrade. |
| `--network-inbound-connection-throttling-max-conns-per-sec` | `AVAGO_NETWORK_INBOUND_CONNECTION_THROTTLING_MAX_CONNS_PER_SEC` | uint | `512` | Node will accept at most this many inbound connections per second. |
| `--network-outbound-connection-throttling-rps` | `AVAGO_NETWORK_OUTBOUND_CONNECTION_THROTTLING_RPS` | uint | `50` | Node makes at most this many outgoing peer connection attempts per second. |

### Peer List Gossiping

Nodes gossip peers to each other so that each node can have an up-to-date peer list. A node gossips `--network-peer-list-num-validator-ips` validator IPs to `--network-peer-list-validator-gossip-size` validators, `--network-peer-list-non-validator-gossip-size` non-validators and `--network-peer-list-peers-gossip-size` peers every `--network-peer-list-gossip-frequency`.

| Flag | Env Var | Type | Default | Description |
|--------|--------|------|----|--------------------|
| `--network-peer-list-num-validator-ips` | `AVAGO_NETWORK_PEER_LIST_NUM_VALIDATOR_IPS` | int | `15` | Number of validator IPs to gossip to other nodes. |
| `--network-peer-list-validator-gossip-size` | `AVAGO_NETWORK_PEER_LIST_VALIDATOR_GOSSIP_SIZE` | int | `20` | Number of validators that the node will gossip peer list to. |
| `--network-peer-list-non-validator-gossip-size` | `AVAGO_NETWORK_PEER_LIST_NON_VALIDATOR_GOSSIP_SIZE` | int | `0` | Number of non-validators that the node will gossip peer list to. |
| `--network-peer-list-peers-gossip-size` | `AVAGO_NETWORK_PEER_LIST_PEERS_GOSSIP_SIZE` | int | `0` | Number of total peers (including non-validator or validator) that the node will gossip peer list to. |
| `--network-peer-list-gossip-frequency` | `AVAGO_NETWORK_PEER_LIST_GOSSIP_FREQUENCY` | duration | `1m` | Frequency to gossip peers to other nodes. |
| `--network-peer-read-buffer-size` | `AVAGO_NETWORK_PEER_READ_BUFFER_SIZE` | int | `8 KiB` | Size of the buffer that peer messages are read into (there is one buffer per peer). |
| `--network-peer-write-buffer-size` | `AVAGO_NETWORK_PEER_WRITE_BUFFER_SIZE` | int | `8 KiB` | Size of the buffer that peer messages are written into (there is one buffer per peer). |

### Resource Usage Tracking

| Flag | Env Var | Type | Default | Description |
|--------|--------|------|----|--------------------|
| `--meter-vms-enabled` | `AVAGO_METER_VMS_ENABLED` | boolean | `true` | Enable Meter VMs to track VM performance with more granularity. |
| `--system-tracker-frequency` | `AVAGO_SYSTEM_TRACKER_FREQUENCY` | duration | `500ms` | Frequency to check the real system usage of tracked processes. More frequent checks -> usage metrics are more accurate, but more expensive to track. |
| `--system-tracker-processing-halflife` | `AVAGO_SYSTEM_TRACKER_PROCESSING_HALFLIFE` | duration | `15s` | Half life to use for the processing requests tracker. Larger half life -> usage metrics change more slowly. |
| `--system-tracker-cpu-halflife` | `AVAGO_SYSTEM_TRACKER_CPU_HALFLIFE` | duration | `15s` | Half life to use for the CPU tracker. Larger half life -> CPU usage metrics change more slowly. |
| `--system-tracker-disk-halflife` | `AVAGO_SYSTEM_TRACKER_DISK_HALFLIFE` | duration | `1m` | Half life to use for the disk tracker. Larger half life -> disk usage metrics change more slowly. |
| `--system-tracker-disk-required-available-space` | `AVAGO_SYSTEM_TRACKER_DISK_REQUIRED_AVAILABLE_SPACE` | uint | `536870912` | Minimum number of available bytes on disk, under which the node will shutdown. |
| `--system-tracker-disk-warning-threshold-available-space` | `AVAGO_SYSTEM_TRACKER_DISK_WARNING_THRESHOLD_AVAILABLE_SPACE` | uint | `1073741824` | Warning threshold for the number of available bytes on disk, under which the node will be considered unhealthy. Must be \>= `--system-tracker-disk-required-available-space`. |

### Plugins

| Flag | Env Var | Type | Default | Description |
|--------|--------|------|----|--------------------|
| `--plugin-dir` | `AVAGO_PLUGIN_DIR` | string | `$HOME/.avalanchego/plugins` | Sets the directory for [VM plugins](https://build.avax.network/docs/virtual-machines). |

### Virtual Machine (VM) Configs

| Flag | Env Var | Type | Default | Description |
|--------|--------|------|----|--------------------|
| `--vm-aliases-file` | `AVAGO_VM_ALIASES_FILE` | string | `~/.avalanchego/configs/vms/aliases.json` | Path to JSON file that defines aliases for Virtual Machine IDs. This flag is ignored if `--vm-aliases-file-content` is specified. Example content: `{"tGas3T58KzdjLHhBDMnH2TvrddhqTji5iZAMZ3RXs2NLpSnhH": ["timestampvm", "timerpc"]}`. The above example aliases the VM whose ID is `"tGas3T58KzdjLHhBDMnH2TvrddhqTji5iZAMZ3RXs2NLpSnhH"` to `"timestampvm"` and `"timerpc"`. |
| `--vm-aliases-file-content` | `AVAGO_VM_ALIASES_FILE_CONTENT` | string | - | As an alternative to `--vm-aliases-file`, it allows specifying base64 encoded aliases for Virtual Machine IDs. |

### Indexing

| Flag | Env Var | Type | Default | Description |
|--------|--------|------|----|--------------------|
| `--index-allow-incomplete` | `AVAGO_INDEX_ALLOW_INCOMPLETE` | boolean | `false` | If true, allow running the node in such a way that could cause an index to miss transactions. Ignored if index is disabled. |

### Router

| Flag | Env Var | Type | Default | Description |
|--------|--------|------|----|--------------------|
| `--router-health-max-drop-rate` | `AVAGO_ROUTER_HEALTH_MAX_DROP_RATE` | float | `1` | Node reports unhealthy if the router drops more than this portion of messages. |
| `--router-health-max-outstanding-requests` | `AVAGO_ROUTER_HEALTH_MAX_OUTSTANDING_REQUESTS` | uint | `1024` | Node reports unhealthy if there are more than this many outstanding consensus requests (Get, PullQuery, etc.) over all chains. |

## Additional Resources

- [Full documentation](https://build.avax.network/docs/quick-start)
- [Example configurations](https://github.com/ava-labs/avalanchego/tree/master/config)
- [Network upgrade schedules](https://build.avax.network/docs/quick-start/primary-network)

</div>

# Backup and Restore (/docs/nodes/maintain/backup-restore)

---
title: Backup and Restore
---

Once you have your node up and running, it's time to prepare for disaster recovery. Should your machine ever have a catastrophic failure due to either hardware or software issues, or even a case of natural disaster, it's best to be prepared for such a situation by making a backup.

When running, a complete node installation along with the database can grow to be multiple gigabytes in size. Having to back up and restore such a large volume of data can be expensive, complicated and time-consuming. Luckily, there is a better way.

Instead of having to back up and restore everything, we need to back up only what is essential, that is, those files that cannot be reconstructed because they are unique to your node. For AvalancheGo node, unique files are those that identify your node on the network, in other words, files that define your NodeID.

Even if your node is a validator on the network and has multiple delegations on it, you don't need to worry about backing up anything else, because the validation and delegation transactions are also stored on the blockchain and will be restored during bootstrapping, along with the rest of the blockchain data.

The installation itself can be easily recreated by installing the node on a new machine, and all the remaining gigabytes of blockchain data can be easily recreated by the process of bootstrapping, which copies the data over from other network peers. However, if you would like to speed up the process, see the [Database Backup and Restore section](#database)

NodeID[​](#nodeid "Direct link to heading")
-------------------------------------------

<Callout type="warn">
If more than one running nodes share the same NodeID, the communications from other nodes in the Avalanche network to this NodeID will be random to one of these nodes. If this NodeID is of a validator, it will dramatically impact the uptime calculation of the validator which will very likely disqualify the validator from receiving the staking rewards. Please make sure only one node with the same NodeID run at one time.
</Callout>

NodeID is a unique identifier that differentiates your node from all the other peers on the network. It's a string formatted like `NodeID-5mb46qkSBj81k9g9e4VFjGGSbaaSLFRzD`. You can look up the technical background of how the NodeID is constructed [here](/docs/api-reference/standards/cryptographic-primitives#tls-addresses). In essence, NodeID is defined by two files:

- `staker.crt`
- `staker.key`

NodePOP is this node's BLS key and proof of possession. Nodes must register a BLS key to act as a validator on the Primary Network. Your node's POP is logged on startup and is accessible over this endpoint.

- `publicKey` is the 48 byte hex representation of the BLS key.
- `proofOfPossession` is the 96 byte hex representation of the BLS signature.

NodePOP is defined by the `signer.key` file.

In the default installation, they can be found in the working directory, specifically in `~/.avalanchego/staking/`. All we need to do to recreate the node on another machine is to run a new installation with those same three files.

If `staker.key` and `staker.crt` are removed from a node, which is restarted afterwards, they will be recreated and a new node ID will be assigned.

If the `signer.key` is regenerated, the node will lose its previous BLS identity, which includes its public key and proof of possession. This change means that the node's former identity on the network will no longer be recognized, affecting its ability to participate in the consensus mechanism as before. Consequently, the node may lose its established reputation and any associated staking rewards.

<Callout type="warn">
If you have users defined in the keystore of your node, then you need to back up and restore those as well. [Keystore API](/docs/api-reference/keystore-api) has methods that can be used to export and import user keys. Note that Keystore API is used by developers only and not intended for use in production nodes. If you don't know what a keystore API is and have not used it, you don't need to worry about it.
</Callout>

### Backup[​](#backup "Direct link to heading")

To back up your node, we need to store `staker.crt` and `staker.key` files somewhere safe and private, preferably to a different computer, to your private To back up your node, we need to store `staker.crt`, `staker.key` and `signer.key` files somewhere safe and private, preferably to a different computer.

<Callout type="warn">
If someone gets a hold of your staker files, they still cannot get to your funds, as they are controlled by the wallet private keys, not by the node. But, they could re-create your node somewhere else, and depending on the circumstances make you lose the staking rewards. So make sure your staker files are secure.

If someone gains access to your `signer.key`, they could potentially sign transactions on behalf of your node, which might disrupt the operations and integrity of your node on the network.
</Callout>

Let's get the files off the machine running the node.

#### From Local Node[​](#from-local-node "Direct link to heading")

If you're running the node locally, on your desktop computer, just navigate to where the files are and copy them somewhere safe.

On a default Linux installation, the path to them will be `/home/USERNAME/.avalanchego/staking/`, where `USERNAME` needs to be replaced with the actual username running the node. Select and copy the files from there to a backup location. You don't need to stop the node to do that.

#### From Remote Node Using `scp`[​](#from-remote-node-using-scp "Direct link to heading")

`scp` is a 'secure copy' command line program, available built-in on Linux and MacOS computers. There is also a Windows version, `pscp`, as part of the [PuTTY](https://www.chiark.greenend.org.uk/~sgtatham/putty/latest.html) package. If using `pscp`, in the following commands replace each usage of `scp` with `pscp -scp`.

To copy the files from the node, you will need to be able to remotely log into the machine. You can use account password, but the secure and recommended way is to use the SSH keys. The procedure for acquiring and setting up SSH keys is highly dependent on your cloud provider and machine configuration. You can refer to our [Amazon Web Services](/docs/nodes/on-third-party-services/amazon-web-services) and [Microsoft Azure](/docs/nodes/on-third-party-services/microsoft-azure) setup guides for those providers. Other providers will have similar procedures.

When you have means of remote login into the machine, you can copy the files over with the following command:

```bash
scp -r ubuntu@PUBLICIP:/home/ubuntu/.avalanchego/staking ~/avalanche_backup
```

This assumes the username on the machine is `ubuntu`, replace with correct username in both places if it is different. Also, replace `PUBLICIP` with the actual public IP of the machine. If `scp` doesn't automatically use your downloaded SSH key, you can point to it manually:

```bash
scp -i /path/to/the/key.pem -r ubuntu@PUBLICIP:/home/ubuntu/.avalanchego/staking ~/avalanche_backup
```

Once executed, this command will create `avalanche_backup` directory and place those three files in it. You need to store them somewhere safe.

### Restore[​](#restore "Direct link to heading")

To restore your node from a backup, we need to do the reverse: restore `staker.key`, `staker.crt` and `signer.key` from the backup to the working directory of the new node.

First, we need to do the usual [installation](/docs/nodes/using-install-script/installing-avalanche-go) of the node. This will create a new NodeID, a new BLS key and a new BLS signature, which we need to replace. When the node is installed correctly, log into the machine where the node is running and stop it:

```bash
sudo systemctl stop avalanchego
```

We're ready to restore the node.

#### To Local Node[​](#to-local-node "Direct link to heading")

If you're running the node locally, just copy the `staker.key`, `staker.crt` and `signer.key` files from the backup location into the working directory, which on the default Linux installation will be `/home/USERNAME/.avalanchego/staking/`. Replace `USERNAME` with the actual username used to run the node.

#### To Remote Node Using `scp`[​](#to-remote-node-using-scp "Direct link to heading")

Again, the process is just the reverse operation. Using `scp` we need to copy the `staker.key`, `staker.crt` and `signer.key` files from the backup location into the remote working directory. Assuming the backed up files are located in the directory where the above backup procedure placed them:

```bash
scp ~/avalanche_backup/{staker.*,signer.key} ubuntu@PUBLICIP:/home/ubuntu/.avalanchego/staking
```

Or if you need to specify the path to the SSH key:

```bash
scp -i /path/to/the/key.pem ~/avalanche_backup/{staker.*,signer.key} ubuntu@PUBLICIP:/home/ubuntu/.avalanchego/staking
```

And again, replace `ubuntu` with correct username if different, and `PUBLICIP` with the actual public IP of the machine running the node, as well as the path to the SSH key if used.

#### Restart the Node and Verify[​](#restart-the-node-and-verify "Direct link to heading")

Once the files have been replaced, log into the machine and start the node using:

```bash
sudo systemctl start avalanchego
```

You can now check that the node is restored with the correct NodeID and NodePOP by issuing the [getNodeID](/docs/api-reference/info-api#infogetnodeid) API call in the same console you ran the previous command:

```bash
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"info.getNodeID"
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info
```

You should see your original NodeID and NodePOP (BLS key and BLS signature). Restore process is done.

Database[​](#database "Direct link to heading")
-----------------------------------------------

Normally, when starting a new node, you can just bootstrap from scratch. However, there are situations when you may prefer to reuse an existing database (ex: preserve keystore records, reduce sync time).

This tutorial will walk you through compressing your node's DB and moving it to another computer using `zip` and `scp`.

### Database Backup[​](#database-backup "Direct link to heading")

First, make sure to stop AvalancheGo, run:

```bash
sudo systemctl stop avalanchego
```

<Callout type="warn">
You must stop the Avalanche node before you back up the database otherwise data could become corrupted.
</Callout>

Once the node is stopped, you can `zip` the database directory to reduce the size of the backup and speed up the transfer using `scp`:

```bash
zip -r avalanche_db_backup.zip .avalanchego/db
```

_Note: It may take > 30 minutes to zip the node's DB._

Next, you can transfer the backup to another machine:

```bash
scp -r ubuntu@PUBLICIP:/home/ubuntu/avalanche_db_backup.zip ~/avalanche_db_backup.zip
```

This assumes the username on the machine is `ubuntu`, replace with correct username in both places if it is different. Also, replace `PUBLICIP` with the actual public IP of the machine. If `scp` doesn't automatically use your downloaded SSH key, you can point to it manually:

```bash
scp -i /path/to/the/key.pem -r ubuntu@PUBLICIP:/home/ubuntu/avalanche_db_backup.zip ~/avalanche_db_backup.zip
```

Once executed, this command will create `avalanche_db_backup.zip` directory in you home directory.

### Database Restore[​](#database-restore "Direct link to heading")

_This tutorial assumes you have already completed "Database Backup" and have a backup at ~/avalanche\_db\_backup.zip._

First, we need to do the usual [installation](/docs/nodes/using-install-script/installing-avalanche-go) of the node. When the node is installed correctly, log into the machine where the node is running and stop it:

```bash
sudo systemctl stop avalanchego
```

<Callout type="warn">
You must stop the Avalanche node before you restore the database otherwise data could become corrupted.
</Callout>

We're ready to restore the database. First, let's move the DB on the existing node (you can remove this old DB later if the restore was successful):

```bash
mv .avalanchego/db .avalanchego/db-old
```

Next, we'll unzip the backup we moved from another node (this will place the unzipped files in `~/.avalanchego/db` when the command is run in the home directory):

```bash
unzip avalanche_db_backup.zip
```

After the database has been restored on a new node, use this command to start the node:

```bash
sudo systemctl start avalanchego
```

Node should now be running from the database on the new instance. To check that everything is in order and that node is not bootstrapping from scratch (which would indicate a problem), use:

```bash
sudo journalctl -u avalanchego -f
```

The node should be catching up to the network and fetching a small number of blocks before resuming normal operation (all the ones produced from the time when the node was stopped before the backup).

Once the backup has been restored and is working as expected, the zip can be deleted:

```bash
rm avalanche_db_backup.zip
```

### Database Direct Copy[​](#database-direct-copy "Direct link to heading")

You may be in a situation where you don't have enough disk space to create the archive containing the whole database, so you cannot complete the backup process as described previously.

In that case, you can still migrate your database to a new computer, by using a different approach: `direct copy`. Instead of creating the archive, moving the archive and unpacking it, we can do all of that on the fly.

To do so, you will need `ssh` access from the destination machine (where you want the database to end up) to the source machine (where the database currently is). Setting up `ssh` is the same as explained for `scp` earlier in the document.

Same as shown previously, you need to stop the node (on both machines):

```bash
sudo systemctl stop avalanchego
```

<Callout type="warn">
You must stop the Avalanche node before you back up the database otherwise data could become corrupted.
</Callout>

Then, on the destination machine, change to a directory where you would like to the put the database files, enter the following command:

```bash
ssh -i /path/to/the/key.pem ubuntu@PUBLICIP 'tar czf - .avalanchego/db' | tar xvzf - -C .
```

Make sure to replace the correct path to the key, and correct IP of the source machine. This will compress the database, but instead of writing it to a file it will pipe it over `ssh` directly to destination machine, where it will be decompressed and written to disk. The process can take a long time, make sure it completes before continuing.

After copying is done, all you need to do now is move the database to the correct location on the destination machine. Assuming there is a default AvalancheGo node installation, we remove the old database and replace it with the new one:

```bash
rm -rf ~/.avalanchego/db
mv db ~/.avalanchego/db
```

You can now start the node on the destination machine:

```bash
sudo systemctl start avalanchego
```

Node should now be running from the copied database. To check that everything is in order and that node is not bootstrapping from scratch (which would indicate a problem), use:

```bash
sudo journalctl -u avalanchego -f
```

The node should be catching up to the network and fetching a small number of blocks before resuming normal operation (all the ones produced from the time when the node was stopped before the backup).

Summary[​](#summary "Direct link to heading")
---------------------------------------------

Essential part of securing your node is the backup that enables full and painless restoration of your node. Following this tutorial you can rest easy knowing that should you ever find yourself in a situation where you need to restore your node from scratch, you can easily and quickly do so.

If you have any problems following this tutorial, comments you want to share with us or just want to chat, you can reach us on our [Discord](https://chat.avalabs.org/) server.


# Node Bootstrap (/docs/nodes/maintain/bootstrapping)

---
title: Node Bootstrap
---

Node Bootstrap is the process where a node _securely_ downloads linear chain blocks to recreate the latest state of the chain locally.

Bootstrap must guarantee that the local state of a node is in sync with the state of other valid nodes. Once bootstrap is completed, a node has the latest state of the chain and can verify new incoming transactions and reach consensus with other nodes, collectively moving forward the chains.

Bootstrapping a node is a multi-step process which requires downloading the chains required by the Primary Network (that is, the C-Chain, P-Chain, and X-Chain), as well as the chains required by any additional Avalanche L1s that the node explicitly tracks.

This document covers the high-level technical details of how bootstrapping works. This document glosses over some specifics, but the [AvalancheGo](https://github.com/ava-labs/avalanchego) codebase is open-source and is available for curious-minded readers to learn more.

Validators and Where to Find Them[​](#validators-and-where-to-find-them "Direct link to heading")
-------------------------------------------------------------------------------------------------

Bootstrapping is all about downloading all previously accepted containers _securely_ so a node can have the latest correct state of the chain. A node can't arbitrarily trust any source - a malicious actor could provide malicious blocks, corrupting the bootstrapping node's local state, and making it impossible for the node to correctly validate the network and reach consensus with other correct nodes.

What's the most reliable source of information in the Avalanche ecosystem? It's a _large enough_ majority of validators. Therefore, the first step of bootstrapping is finding a sufficient amount of validators to download containers from.

The P-Chain is responsible for all platform-level operations, including staking events that modify an Avalanche L1's validator set. Whenever any chain (aside from the P-Chain itself) bootstraps, it requests an up-to-date validator set for that Avalanche L1 (Primary Network is an Avalanche L1 too). Once the Avalanche L1's current validator set is known, the node can securely download containers from these validators to bootstrap the chain.

There is a caveat here: the validator set must be _up-to-date_. If a bootstrapping node's validator set is stale, the node may incorrectly believe that some nodes are still validators when their validation period has already expired. A node might unknowingly end up requesting blocks from non-validators which respond with malicious blocks that aren't safe to download.

**For this reason, every Avalanche node must fully bootstrap the P-chain first before moving on to the other Primary Network chains and other Avalanche L1s to guarantee that their validator sets are up-to-date**.

What about the P-chain? The P-chain can't ever have an up-to-date validator set before completing its bootstrap. To solve this chicken-and-egg situation the Avalanche Foundation maintains a trusted default set of validators called beacons (but users are free to configure their own). Beacon Node-IDs and IP addresses are listed in the [AvalancheGo codebase](https://github.com/ava-labs/avalanchego/blob/master/genesis/bootstrappers.json). Every node has the beacon list available from the start and can reach out to them as soon as it starts.

Validators are the only sources of truth for a blockchain. Validator availability is so key to the bootstrapping process that **bootstrapping is blocked until the node establishes a sufficient amount of secure connections to validators**. If the node fails to reach a sufficient amount within a given period of time, it shuts down as no operation can be carried out safely.

Bootstrapping the Blockchain[​](#bootstrapping-the-blockchain "Direct link to heading")
---------------------------------------------------------------------------------------

Once a node is able to discover and connect to validator and beacon nodes, it's able to start bootstrapping the blockchain by downloading the individual containers.

One common misconception is that Avalanche blockchains are bootstrapped by retrieving containers starting at genesis and working up to the currently accepted frontier.

Instead, containers are downloaded from the accepted frontier downwards to genesis, and then their corresponding state transitions are executed upwards from genesis to the accepted frontier. The accepted frontier is the last accepted block for linear chains.

Why can't nodes simply download blocks in chronological order, starting from genesis upwards? The reason is efficiency: if nodes downloaded containers upwards they would only get a safety guarantee by polling a majority of validators for every single container. That's a lot of network traffic for a single container, and a node would still need to do that for each container in the chain.

Instead, if a node starts by securely retrieving the accepted frontier from a majority of honest nodes and then recursively fetches the parent containers from the accepted frontier down to genesis, it can cheaply check that containers are correct just by verifying their IDs. Each Avalanche container has the IDs of its parents (one block parent for linear chains) and an ID's integrity can be guaranteed cryptographically.

Let's dive deeper into the two bootstrap phases - frontier retrieval and container execution.

### Frontier Retrieval[​](#frontier-retrieval "Direct link to heading")

The current frontier is retrieved by requesting them from validator or beacon nodes. Avalanche bootstrap is designed to be robust - it must be able to make progress even in the presence of slow validators or network failures. This process needs to be fault-tolerant to these types of failures, since bootstrapping may take quite some time to complete and network connections can be unreliable.

Bootstrap starts when a node has connected to a sufficient majority of validator stake. A node is able to start bootstrapping when it has connected to at least 75%75\\% of total validator stake.

Seeders are the first set of peers that a node reaches out to when trying to figure out the current frontier. A subset of seeders is randomly sampled from the validator set. Seeders might be slow and provide a stale frontier, be malicious and return malicious container IDs, but they always provide an initial set of candidate frontiers to work with.

Once a node has received the candidate frontiers form its seeders, it polls **every network validator** to vet the candidates frontiers. It sends the list of candidate frontiers it received from the seeders to each validator, asking whether or not they know about these frontiers. Each validator responds returning the subset of known candidates, regardless of how up-to-date or stale the containers are. Each validator returns containers irrespective of their age so that bootstrap works even in the presence of a stale frontier.

Frontier retrieval is completed when at least one of the candidate frontiers is supported by at least 50%50\\% of total validator stake. Multiple candidate frontiers may be supported by a majority of stake, after which point the next phase, container fetching starts.

At any point in these steps a network issue may occur, preventing a node from retrieving or validating frontiers. If this occurs, bootstrap restarts by sampling a new set of seeders and repeating the bootstrapping process, optimistically assuming that the network issue will go away.

### Containers Execution[​](#containers-execution "Direct link to heading")

Once a node has at least one valid frontiers, it starts downloading parent containers for each frontier. If it's the first time the node is running, it won't know about any containers and will try fetching all parent containers recursively from the accepted frontier down to genesis (unless [state sync](#state-sync) is enabled). If bootstrap had already run previously, some containers are already available locally and the node will stop as soon as it finds a known one.

A node first just fetches and parses containers. Once the chain is complete, the node executes them in chronological order starting from the earliest downloaded container to the accepted frontier. This allows the node to rebuild the full chain state and to eventually be in sync with the rest of the network.

When Does Bootstrapping Finish?[​](#when-does-bootstrapping-finish "Direct link to heading")
--------------------------------------------------------------------------------------------

You've seen how [bootstrap works](#bootstrapping-the-blockchain) for a single chain. However, a node must bootstrap the chains in the Primary Network as well as the chains in each Avalanche L1 it tracks. This begs the questions - when are these chains bootstrapped? When is a node done bootstrapping?

The P-chain is always the first to bootstrap before any other chain. Once the P-Chain has finished, all other chains start bootstrapping in parallel, connecting to their own validators independently of one another.

A node completes bootstrapping an Avalanche L1 once all of its corresponding chains have completed bootstrapping. Because the Primary Network is a special case of Avalanche L1 that includes the entire network, this applies to it as well as any other manually tracked Avalanche L1s.

Note that Avalanche L1s bootstrap is independently of one another - so even if one Avalanche L1 has bootstrapped and is validating new transactions and adding new containers, other Avalanche L1s may still be bootstrapping in parallel.

Within a single Avalanche L1 however, an Avalanche L1 isn't done bootstrapping until the last chain completes bootstrapping. It's possible for a single chain to effectively stall a node from finishing the bootstrap for a single Avalanche L1, if it has a sufficiently long history or each operation is complex and time consuming. Even worse, other Avalanche L1 validators are continuously accepting new transactions and adding new containers on top of the previously known frontier, so a node that's slow to bootstrap can continuously fall behind the rest of the network.

Nodes mitigate this by restarting bootstrap for any chains which is blocked waiting for the remaining Avalanche L1 chains to finish bootstrapping. These chains repeat the frontier retrieval and container downloading phases to stay up-to-date with the Avalanche L1's ever moving current frontier until the slowest chain has completed bootstrapping.

Once this is complete, a node is finally ready to validate the network.

State Sync[​](#state-sync "Direct link to heading")
---------------------------------------------------

The full node bootstrap process is long, and gets longer and longer over time as more and more containers are accepted. Nodes need to bootstrap a chain by reconstructing the full chain state locally - but downloading and executing each container isn't the only way to do this.

Starting from [AvalancheGo version 1.7.11](https://github.com/ava-labs/avalanchego/releases/tag/v1.7.11), nodes can use state sync to drastically cut down bootstrapping time on the C-Chain. Instead of executing each block, state sync uses cryptographic techniques to download and verify just the state associated with the current frontier. State synced nodes can't serve every C-chain block ever historically accepted, but they can safely retrieve the full C-chain state needed to validate in a much shorter time. State sync will fetch the previous 256 blocks prior to support the previous block hash operation code.

State sync is currently only available for the C-chain. The P-chain and X-chain currently bootstrap by downloading all blocks. Note that irrespective of the bootstrap method used (including state sync), each chain is still blocked on all other chains in its Avalanche L1 completing their bootstrap before continuing into normal operation.

<Callout title="Note">
There are no configs to state sync an archival node. If you need all the historical state then you must not use state sync and setup the config of the node for an archival node.
</Callout>


Conclusions and FAQ[​](#conclusions-and-faq "Direct link to heading")
---------------------------------------------------------------------

If you got this far, you've hopefully gotten a better idea of what's going on when your node bootstraps. Here's a few frequently asked questions about bootstrapping.

### How Can I Get the ETA for Node Bootstrap?[​](#how-can-i-get-the-eta-for-node-bootstrap "Direct link to heading")

Logs provide information about both container downloading and their execution for each chain. Here is an example

```bash
[02-16|17:31:42.950] INFO <P Chain> bootstrap/bootstrapper.go:494 fetching blocks {"numFetchedBlocks": 5000, "numTotalBlocks": 101357, "eta": "2m52s"}
[02-16|17:31:58.110] INFO <P Chain> bootstrap/bootstrapper.go:494 fetching blocks {"numFetchedBlocks": 10000, "numTotalBlocks": 101357, "eta": "3m40s"}
[02-16|17:32:04.554] INFO <P Chain> bootstrap/bootstrapper.go:494 fetching blocks {"numFetchedBlocks": 15000, "numTotalBlocks": 101357, "eta": "2m56s"}
...
[02-16|17:36:52.404] INFO <P Chain> queue/jobs.go:203 executing operations {"numExecuted": 17881, "numToExecute": 101357, "eta": "2m20s"}
[02-16|17:37:22.467] INFO <P Chain> queue/jobs.go:203 executing operations {"numExecuted": 35009, "numToExecute": 101357, "eta": "1m54s"}
[02-16|17:37:52.468] INFO <P Chain> queue/jobs.go:203 executing operations {"numExecuted": 52713, "numToExecute": 101357, "eta": "1m23s"}
```

Similar logs are emitted for X and C chains and any chain in explicitly tracked Avalanche L1s.

### Why Chain Bootstrap ETA Keeps On Changing?[​](#why-chain-bootstrap-eta-keeps-on-changing "Direct link to heading")

As you saw in the [bootstrap completion section](#when-does-bootstrapping-finish), an Avalanche L1 like the Primary Network completes once all of its chains finish bootstrapping. Some Avalanche L1 chains may have to wait for the slowest to finish. They'll restart bootstrapping in the meantime, to make sure they won't fall back too much with respect to the network accepted frontier.

What Order Do The Chains Bootstrap?[​](#what-order-do-the-chains-bootstrap "Direct link to heading")
----------------------------------------------------------------------------------------------------

The 3 chains will bootstrap in the following order: P-chain, X-chain, C-chain.

### Why Are AvalancheGo APIs Disabled During Bootstrapping?[​](#why-are-avalanchego-apis-disabled-during-bootstrapping "Direct link to heading")

AvalancheGo APIs are [explicitly disabled](https://github.com/ava-labs/avalanchego/blob/master/api/server/server.go#L367:L379) during bootstrapping. The reason is that if the node has not fully rebuilt its Avalanche L1s state, it can't provide accurate information. AvalancheGo APIs are activated once bootstrap completes and node transition into its normal operating mode, accepting and validating transactions.


# Enroll in Avalanche Notify (/docs/nodes/maintain/enroll-in-avalanche-notify)

---
title: Enroll in Avalanche Notify
---

To receive email alerts if a validator becomes unresponsive or out-of-date, sign up with the Avalanche Notify tool: [http://notify.avax.network](http://notify.avax.network/).

Avalanche Notify is an active monitoring system that checks a validator's responsiveness each minute.

An email alert is sent if a validator is down for 5 consecutive checks and when a validator recovers (is responsive for 5 checks in a row).

<Callout title="Tip" icon = {<BadgeCheck className="size-5 text-card" fill="green" />} >
When signing up for email alerts, consider using a new, alias, or auto-forwarding email address to protect your privacy. Otherwise, it will be possible to link your NodeID to your email.
</Callout>

<Callout type="warn">
This tool is currently in BETA and validator alerts may erroneously be triggered, not triggered, or delayed. The best way to maximize the likelihood of earning staking rewards is to run redundant monitoring/alerting.
</Callout>


# Monitoring (/docs/nodes/maintain/monitoring)

---
title: Monitoring
description: Learn how to monitor an AvalancheGo node.
---

This tutorial demonstrates how to set up infrastructure to monitor an instance of [AvalancheGo](https://github.com/ava-labs/avalanchego). We will use:

- [Prometheus](https://prometheus.io/) to gather and store data
- [`node_exporter`](https://github.com/prometheus/node_exporter) to get information about the machine,
- AvalancheGo's [Metrics API](/docs/api-reference/metrics-api) to get information about the node
- [Grafana](https://grafana.com/) to visualize data on a dashboard.
- A set of pre-made [Avalanche dashboards](https://github.com/ava-labs/avalanche-monitoring/tree/main/grafana/dashboards)

## Prerequisites:

- A running AvalancheGo node
- Shell access to the machine running the node
- Administrator privileges on the machine

This tutorial assumes you have Ubuntu 20.04 running on your node. Other Linux flavors that use `systemd` for running services and `apt-get` for package management might work but have not been tested. Community member has reported it works on Debian 10, might work on other Debian releases as well.

### Caveat: Security

The system as described here **should not** be opened to the public internet. Neither Prometheus nor Grafana as shown here is hardened against unauthorized access. Make sure that both of them are accessible only over a secured proxy, local network, or VPN. Setting that up is beyond the scope of this tutorial, but exercise caution. Bad security practices could lead to attackers gaining control over your node! It is your responsibility to follow proper security practices.

Monitoring Installer Script[​](#monitoring-installer-script "Direct link to heading")
-------------------------------------------------------------------------------------

In order to make node monitoring easier to install, we have made a script that does most of the work for you. To download and run the script, log into the machine the node runs on with a user that has administrator privileges and enter the following command:

```bash
wget -nd -m https://raw.githubusercontent.com/ava-labs/avalanche-monitoring/main/grafana/monitoring-installer.sh ;\
chmod 755 monitoring-installer.sh;
```

This will download the script and make it executable.

Script itself is run multiple times with different arguments, each installing a different tool or part of the environment. To make sure it downloaded and set up correctly, begin by running:

```bash
./monitoring-installer.sh --help
```

It should display:

```bash
Usage: ./monitoring-installer.sh [--1|--2|--3|--4|--5|--help]

Options:
--help   Shows this message
--1      Step 1: Installs Prometheus
--2      Step 2: Installs Grafana
--3      Step 3: Installs node_exporter
--4      Step 4: Installs AvalancheGo Grafana dashboards
--5      Step 5: (Optional) Installs additional dashboards

Run without any options, script will download and install latest version of AvalancheGo dashboards.
```

Let's get to it.

Step 1: Set up Prometheus [​](#step-1-set-up-prometheus- "Direct link to heading")
----------------------------------------------------------------------------------

Run the script to execute the first step:

```bash
./monitoring-installer.sh --1
```

It should produce output something like this:

```bash
AvalancheGo monitoring installer
--------------------------------
STEP 1: Installing Prometheus

Checking environment...
Found arm64 architecture...
Prometheus install archive found:
https://github.com/prometheus/prometheus/releases/download/v2.31.0/prometheus-2.31.0.linux-arm64.tar.gz
Attempting to download:
https://github.com/prometheus/prometheus/releases/download/v2.31.0/prometheus-2.31.0.linux-arm64.tar.gz
prometheus.tar.gz                           100%[=========================================================================================>]  65.11M   123MB/s    in 0.5s
2021-11-05 14:16:11 URL:https://github-releases.githubusercontent.com/6838921/a215b0e7-df1f-402b-9541-a3ec9d431f76?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIWNJYAX4CSVEH53A%2F20211105%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20211105T141610Z&X-Amz-Expires=300&X-Amz-Signature=72a8ae4c6b5cea962bb9cad242cb4478082594b484d6a519de58b8241b319d94&X-Amz-SignedHeaders=host&actor_id=0&key_id=0&repo_id=6838921&response-content-disposition=attachment%3B%20filename%3Dprometheus-2.31.0.linux-arm64.tar.gz&response-content-type=application%2Foctet-stream [68274531/68274531] -> "prometheus.tar.gz" [1]
...
```

You may be prompted to confirm additional package installs, do that if asked. Script run should end with instructions on how to check that Prometheus installed correctly. Let's do that, run:

```bash
sudo systemctl status prometheus
```

It should output something like:

```bash
● prometheus.service - Prometheus
Loaded: loaded (/etc/systemd/system/prometheus.service; enabled; vendor preset: enabled)
Active: active (running) since Fri 2021-11-12 11:38:32 UTC; 17min ago
Docs: https://prometheus.io/docs/introduction/overview/
Main PID: 548 (prometheus)
Tasks: 10 (limit: 9300)
Memory: 95.6M
CGroup: /system.slice/prometheus.service
└─548 /usr/local/bin/prometheus --config.file=/etc/prometheus/prometheus.yml --storage.tsdb.path=/var/lib/prometheus --web.console.templates=/etc/prometheus/con>

Nov 12 11:38:33 ip-172-31-36-200 prometheus[548]: ts=2021-11-12T11:38:33.644Z caller=head.go:590 level=info component=tsdb msg="WAL segment loaded" segment=81 maxSegment=84
Nov 12 11:38:33 ip-172-31-36-200 prometheus[548]: ts=2021-11-12T11:38:33.773Z caller=head.go:590 level=info component=tsdb msg="WAL segment loaded" segment=82 maxSegment=84
```

Note the `active (running)` status (press `q` to exit). You can also check Prometheus web interface, available on `http://your-node-host-ip:9090/`

<Callout type="warn">
You may need to do `sudo ufw allow 9090/tcp` if the firewall is on, and/or adjust the security settings to allow connections to port 9090 if the node is running on a cloud instance. For AWS, you can look it up [here](/docs/nodes/on-third-party-services/amazon-web-services#create-a-security-group). If on public internet, make sure to only allow your IP to connect!
</Callout>

If everything is OK, let's move on.

Step 2: Install Grafana [​](#step-2-install-grafana- "Direct link to heading")
------------------------------------------------------------------------------

Run the script to execute the second step:

```bash
./monitoring-installer.sh --2
```

It should produce output something like this:

```bash
AvalancheGo monitoring installer
--------------------------------
STEP 2: Installing Grafana

OK
deb https://packages.grafana.com/oss/deb stable main
Hit:1 http://us-east-2.ec2.ports.ubuntu.com/ubuntu-ports focal InRelease
Get:2 http://us-east-2.ec2.ports.ubuntu.com/ubuntu-ports focal-updates InRelease [114 kB]
Get:3 http://us-east-2.ec2.ports.ubuntu.com/ubuntu-ports focal-backports InRelease [101 kB]
Hit:4 http://ppa.launchpad.net/longsleep/golang-backports/ubuntu focal InRelease
Get:5 http://ports.ubuntu.com/ubuntu-ports focal-security InRelease [114 kB]
Get:6 https://packages.grafana.com/oss/deb stable InRelease [12.1 kB]
...
```

To make sure it's running properly:

```bash
sudo systemctl status grafana-server
```

which should again show Grafana as `active`. Grafana should now be available at `http://your-node-host-ip:3000/` from your browser. Log in with username: admin, password: admin, and you will be prompted to set up a new, secure password. Do that.

<Callout type="warn">
You may need to do `sudo ufw allow 3000/tcp` if the firewall is on, and/or adjust the cloud instance settings to allow connections to port 3000. If on public internet, make sure to only allow your IP to connect!
</Callout>

Prometheus and Grafana are now installed, we're ready for the next step.

Step 3: Set up `node_exporter` [​](#step-3-set-up-node_exporter- "Direct link to heading")
------------------------------------------------------------------------------------------

In addition to metrics from AvalancheGo, let's set up monitoring of the machine itself, so we can check CPU, memory, network and disk usage and be aware of any anomalies. For that, we will use `node_exporter`, a Prometheus plugin.

Run the script to execute the third step:

```bash
./monitoring-installer.sh --3
```

The output should look something like this:

```bash
AvalancheGo monitoring installer
--------------------------------
STEP 3: Installing node_exporter

Checking environment...
Found arm64 architecture...
Downloading archive...
https://github.com/prometheus/node_exporter/releases/download/v1.2.2/node_exporter-1.2.2.linux-arm64.tar.gz
node_exporter.tar.gz                        100%[=========================================================================================>]   7.91M  --.-KB/s    in 0.1s
2021-11-05 14:57:25 URL:https://github-releases.githubusercontent.com/9524057/6dc22304-a1f5-419b-b296-906f6dd168dc?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIWNJYAX4CSVEH53A%2F20211105%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20211105T145725Z&X-Amz-Expires=300&X-Amz-Signature=3890e09e58ea9d4180684d9286c9e791b96b0c411d8f8a494f77e99f260bdcbb&X-Amz-SignedHeaders=host&actor_id=0&key_id=0&repo_id=9524057&response-content-disposition=attachment%3B%20filename%3Dnode_exporter-1.2.2.linux-arm64.tar.gz&response-content-type=application%2Foctet-stream [8296266/8296266] -> "node_exporter.tar.gz" [1]
node_exporter-1.2.2.linux-arm64/LICENSE
```

Again, we check that the service is running correctly:

```bash
sudo systemctl status node_exporter
```

If the service is running, Prometheus, Grafana and `node_exporter` should all work together now. To check, in your browser visit Prometheus web interface on `http://your-node-host-ip:9090/targets`. You should see three targets enabled:

- Prometheus
- AvalancheGo
- `avalanchego-machine`

Make sure that all of them have `State` as `UP`.

<Callout title="Note">
If you run your AvalancheGo node with TLS enabled on your API port, you will need to manually edit the `/etc/prometheus/prometheus.yml` file and change the `avalanchego` job to look like this:

```yml
- job_name: "avalanchego"
  metrics_path: "/ext/metrics"
  scheme: "https"
  tls_config:
    insecure_skip_verify: true
  static_configs:
    - targets: ["localhost:9650"]
```

Mind the spacing (leading spaces too)! You will need admin privileges to do that (use `sudo`). Restart Prometheus service afterwards with `sudo systemctl restart prometheus`.
</Callout>

All that's left to do now is to provision the data source and install the actual dashboards that will show us the data.

Step 4: Dashboards [​](#step-4-dashboards- "Direct link to heading")
--------------------------------------------------------------------

Run the script to install the dashboards:

```bash
./monitoring-installer.sh --4
```

It will produce output something like this:

```bash
AvalancheGo monitoring installer
--------------------------------

Downloading...
Last-modified header missing -- time-stamps turned off.
2021-11-05 14:57:47 URL:https://raw.githubusercontent.com/ava-labs/avalanche-monitoring/master/grafana/dashboards/c_chain.json [50282/50282] -> "c_chain.json" [1]
FINISHED --2021-11-05 14:57:47--
Total wall clock time: 0.2s
Downloaded: 1 files, 49K in 0s (132 MB/s)
Last-modified header missing -- time-stamps turned off.
...
```

This will download the latest versions of the dashboards from GitHub and provision Grafana to load them, as well as defining Prometheus as a data source. It may take up to 30 seconds for the dashboards to show up. In your browser, go to: `http://your-node-host-ip:3000/dashboards`. You should see 7 Avalanche dashboards:

![Imported dashboards](/images/monitoring1.png)

Select 'Avalanche Main Dashboard' by clicking its title. It should load, and look similar to this:

![Main Dashboard](/images/monitoring2.png)

Some graphs may take some time to populate fully, as they need a series of data points in order to render correctly.

You can bookmark the main dashboard as it shows the most important information about the node at a glance. Every dashboard has a link to all the others as the first row, so you can move between them easily.

Step 5: Additional Dashboards (Optional)[​](#step-5-additional-dashboards-optional "Direct link to heading")
------------------------------------------------------------------------------------------------------------

Step 4 installs the basic set of dashboards that make sense to have on any node. Step 5 is for installing additional dashboards that may not be useful for every installation.

Currently, there is only one additional dashboard: Avalanche L1s. If your node is running any Avalanche L1s, you may want to add this as well. Do:

```bash
./monitoring-installer.sh --5
```

This will add the Avalanche L1s dashboard. It allows you to monitor operational data for any Avalanche L1 that is synced on the node. There is an Avalanche L1 switcher that allows you to switch between different Avalanche L1s. As there are many Avalanche L1s and not every node will have all of them, by default, it comes populated only with Spaces and WAGMI Avalanche L1s that exist on Fuji testnet:

![Avalanche L1s switcher](/images/monitoring3.png)

To configure the dashboard and add any Layer 1s that your node is syncing, you will need to edit the dashboard. Select the `dashboard settings` icon (image of a cog) in the upper right corner of the dashboard display and switch to `Variables` section and select the `subnet` variable. It should look something like this:

![Variables screen](/images/monitoring4.png)

The variable format is:

```bash
Subnet name:<BlockchainID>
```

and the separator between entries is a comma. Entries for Spaces and WAGMI look like:

```bash
Spaces (Fuji) : 2ebCneCbwthjQ1rYT41nhd7M76Hc6YmosMAQrTFhBq8qeqh6tt, WAGMI (Fuji) : 2AM3vsuLoJdGBGqX2ibE8RGEq4Lg7g4bot6BT1Z7B9dH5corUD
```

After editing the values, press `Update` and then click `Save dashboard` button and confirm. Press the back arrow in the upper left corner to return to the dashboard. New values should now be selectable from the dropdown and data for the selected Avalanche L1 will be shown in the panels.

Updating[​](#updating "Direct link to heading")
-----------------------------------------------

Available node metrics are updated constantly, new ones are added and obsolete removed, so it is good a practice to update the dashboards from time to time, especially if you notice any missing data in panels. Updating the dashboards is easy, just run the script with no arguments, and it will refresh the dashboards with the latest available versions. Allow up to 30s for dashboards to update in Grafana.

If you added the optional extra dashboards (step 5), they will be updated as well.

Summary[​](#summary "Direct link to heading")
---------------------------------------------

Using the script to install node monitoring is easy, and it gives you insight into how your node is behaving and what's going on under the hood. Also, pretty graphs!

If you have feedback on this tutorial, problems with the script or following the steps, send us a message on [Discord](https://chat.avalabs.org/).


# Reduce Disk Usage (/docs/nodes/maintain/reduce-disk-usage)

---
title: Reduce Disk Usage
---

Offline Pruning is ported from `go-ethereum` to reduce the amount of disk space taken up by the TrieDB (storage for the Merkle Forest).

Offline pruning creates a bloom filter and adds all trie nodes in the active state to the bloom filter to mark the data as protected. This ensures that any part of the active state will not be removed during offline pruning.

After generating the bloom filter, offline pruning iterates over the database and searches for trie nodes that are safe to be removed from disk.

A bloom filter is a probabilistic data structure that reports whether an item is definitely not in a set or possibly in a set. Therefore, for each key we iterate, we check if it is in the bloom filter. If the key is definitely not in the bloom filter, then it is not in the active state and we can safely delete it. If the key is possibly in the set, then we skip over it to ensure we do not delete any active state.

During iteration, the underlying database (LevelDB) writes deletion markers, causing a temporary increase in disk usage.

After iterating over the database and deleting any old trie nodes that it can, offline pruning then runs compaction to minimize the DB size after the potentially large number of delete operations.

Finding the C-Chain Config File[​](#finding-the-c-chain-config-file "Direct link to heading")
---------------------------------------------------------------------------------------------

In order to enable offline pruning, you need to update the C-Chain config file to include the parameters `offline-pruning-enabled` and `offline-pruning-data-directory`.

The default location of the C-Chain config file is `~/.avalanchego/configs/chains/C/config.json`. **Please note that by default, this file does not exist. You would need to create it manually.** You can update the directory for chain configs by passing in the directory of your choice via the CLI argument: `chain-config-dir`. See [this](/docs/nodes/configure/configs-flags) for more info. For example, if you start your node with:

```bash
./build/avalanchego --chain-config-dir=/home/ubuntu/chain-configs
```

The chain config directory will be updated to `/home/ubuntu/chain-configs` and the corresponding C-Chain config file will be: `/home/ubuntu/chain-configs/C/config.json`.

Running Offline Pruning[​](#running-offline-pruning "Direct link to heading")
-----------------------------------------------------------------------------

In order to enable offline pruning, update the C-Chain config file to include the following parameters:

```json
{
  "offline-pruning-enabled": true,
  "offline-pruning-data-directory": "/home/ubuntu/offline-pruning"
}
```

This will set `/home/ubuntu/offline-pruning` as the directory to be used by the offline pruner. Offline pruning will store the bloom filter in this location, so you must ensure that the path exists.

Now that the C-Chain config file has been updated, you can start your node with the command (no CLI arguments are necessary if using the default chain config directory):

Once AvalancheGo starts the C-Chain, you can expect to see update logs from the offline pruner:

```bash
INFO [02-09|00:20:15.625] Iterating state snapshot                 accounts=297,231 slots=6,669,708 elapsed=16.001s eta=1m29.03s
INFO [02-09|00:20:23.626] Iterating state snapshot                 accounts=401,907 slots=10,698,094 elapsed=24.001s eta=1m32.522s
INFO [02-09|00:20:31.626] Iterating state snapshot                 accounts=606,544 slots=13,891,948 elapsed=32.002s eta=1m10.927s
INFO [02-09|00:20:39.626] Iterating state snapshot                 accounts=760,948 slots=18,025,523 elapsed=40.002s eta=1m2.603s
INFO [02-09|00:20:47.626] Iterating state snapshot                 accounts=886,583 slots=21,769,199 elapsed=48.002s eta=1m8.834s
INFO [02-09|00:20:55.626] Iterating state snapshot                 accounts=1,046,295 slots=26,120,100 elapsed=56.002s eta=57.401s
INFO [02-09|00:21:03.626] Iterating state snapshot                 accounts=1,229,257 slots=30,241,391 elapsed=1m4.002s eta=47.674s
INFO [02-09|00:21:11.626] Iterating state snapshot                 accounts=1,344,091 slots=34,128,835 elapsed=1m12.002s eta=45.185s
INFO [02-09|00:21:19.626] Iterating state snapshot                 accounts=1,538,009 slots=37,791,218 elapsed=1m20.002s eta=34.59s
INFO [02-09|00:21:27.627] Iterating state snapshot                 accounts=1,729,564 slots=41,694,303 elapsed=1m28.002s eta=25.006s
INFO [02-09|00:21:35.627] Iterating state snapshot                 accounts=1,847,617 slots=45,646,011 elapsed=1m36.003s eta=20.052s
INFO [02-09|00:21:43.627] Iterating state snapshot                 accounts=1,950,875 slots=48,832,722 elapsed=1m44.003s eta=9.299s
INFO [02-09|00:21:47.342] Iterated snapshot                        accounts=1,950,875 slots=49,667,870 elapsed=1m47.718s
INFO [02-09|00:21:47.351] Writing state bloom to disk              name=/home/ubuntu/offline-pruning/statebloom.0xd6fca36db4b60b34330377040ef6566f6033ed8464731cbb06dc35c8401fa38e.bf.gz
INFO [02-09|00:23:04.421] State bloom filter committed             name=/home/ubuntu/offline-pruning/statebloom.0xd6fca36db4b60b34330377040ef6566f6033ed8464731cbb06dc35c8401fa38e.bf.gz
```

The bloom filter should be populated and committed to disk after about 5 minutes. At this point, if the node shuts down, it will resume the offline pruning session when it restarts (note: this operation cannot be cancelled).

In order to ensure that users do not mistakenly leave offline pruning enabled for the long term (which could result in an hour of downtime on each restart), we have added a manual protection which requires that after an offline pruning session, the node must be started with offline pruning disabled at least once before it will start with offline pruning enabled again. Therefore, once the bloom filter has been committed to disk, you should update the C-Chain config file to include the following parameters:

```json
{
  "offline-pruning-enabled": false,
  "offline-pruning-data-directory": "/home/ubuntu/offline-pruning"
}
```

It is important to keep the same data directory in the config file, so that the node knows where to look for the bloom filter on a restart if offline pruning has not finished.

Now if your node restarts, it will be marked as having correctly disabled offline pruning after the run and be allowed to resume normal operation once offline pruning has finished running.

You will see progress logs throughout the offline pruning run which will indicate the session's progress:

```bash
INFO [02-09|00:31:51.920] Pruning state data                       nodes=40,116,759 size=10.08GiB  elapsed=8m47.499s eta=12m50.961s
INFO [02-09|00:31:59.921] Pruning state data                       nodes=41,659,059 size=10.47GiB  elapsed=8m55.499s eta=12m13.822s
INFO [02-09|00:32:07.921] Pruning state data                       nodes=41,687,047 size=10.48GiB  elapsed=9m3.499s  eta=12m23.915s
INFO [02-09|00:32:15.921] Pruning state data                       nodes=41,715,823 size=10.48GiB  elapsed=9m11.499s eta=12m33.965s
INFO [02-09|00:32:23.921] Pruning state data                       nodes=41,744,167 size=10.49GiB  elapsed=9m19.500s eta=12m44.004s
INFO [02-09|00:32:31.921] Pruning state data                       nodes=41,772,613 size=10.50GiB  elapsed=9m27.500s eta=12m54.01s
INFO [02-09|00:32:39.921] Pruning state data                       nodes=41,801,267 size=10.50GiB  elapsed=9m35.500s eta=13m3.992s
INFO [02-09|00:32:47.922] Pruning state data                       nodes=41,829,714 size=10.51GiB  elapsed=9m43.500s eta=13m13.951s
INFO [02-09|00:32:55.922] Pruning state data                       nodes=41,858,400 size=10.52GiB  elapsed=9m51.501s eta=13m23.885s
INFO [02-09|00:33:03.923] Pruning state data                       nodes=41,887,131 size=10.53GiB  elapsed=9m59.501s eta=13m33.79s
INFO [02-09|00:33:11.923] Pruning state data                       nodes=41,915,583 size=10.53GiB  elapsed=10m7.502s eta=13m43.678s
INFO [02-09|00:33:19.924] Pruning state data                       nodes=41,943,891 size=10.54GiB  elapsed=10m15.502s eta=13m53.551s
INFO [02-09|00:33:27.924] Pruning state data                       nodes=41,972,281 size=10.55GiB  elapsed=10m23.502s eta=14m3.389s
INFO [02-09|00:33:35.924] Pruning state data                       nodes=42,001,414 size=10.55GiB  elapsed=10m31.503s eta=14m13.192s
INFO [02-09|00:33:43.925] Pruning state data                       nodes=42,029,987 size=10.56GiB  elapsed=10m39.504s eta=14m22.976s
INFO [02-09|00:33:51.925] Pruning state data                       nodes=42,777,042 size=10.75GiB  elapsed=10m47.504s eta=14m7.245s
INFO [02-09|00:34:00.950] Pruning state data                       nodes=42,865,413 size=10.77GiB  elapsed=10m56.529s eta=14m15.927s
INFO [02-09|00:34:08.956] Pruning state data                       nodes=42,918,719 size=10.79GiB  elapsed=11m4.534s  eta=14m24.453s
INFO [02-09|00:34:22.816] Pruning state data                       nodes=42,952,925 size=10.79GiB  elapsed=11m18.394s eta=14m41.243s
INFO [02-09|00:34:30.818] Pruning state data                       nodes=42,998,715 size=10.81GiB  elapsed=11m26.397s eta=14m49.961s
INFO [02-09|00:34:38.828] Pruning state data                       nodes=43,046,476 size=10.82GiB  elapsed=11m34.407s eta=14m58.572s
INFO [02-09|00:34:46.893] Pruning state data                       nodes=43,107,656 size=10.83GiB  elapsed=11m42.472s eta=15m6.729s
INFO [02-09|00:34:55.038] Pruning state data                       nodes=43,168,834 size=10.85GiB  elapsed=11m50.616s eta=15m14.934s
INFO [02-09|00:35:03.039] Pruning state data                       nodes=43,446,900 size=10.92GiB  elapsed=11m58.618s eta=15m14.705s
```

When the node completes, it will emit the following log and resume normal operation:

```bash
INFO [02-09|00:42:16.009] Pruning state data                       nodes=93,649,812 size=23.53GiB  elapsed=19m11.588s eta=1m2.658s
INFO [02-09|00:42:24.009] Pruning state data                       nodes=95,045,956 size=23.89GiB  elapsed=19m19.588s eta=45.149s
INFO [02-09|00:42:32.009] Pruning state data                       nodes=96,429,410 size=24.23GiB  elapsed=19m27.588s eta=28.041s
INFO [02-09|00:42:40.009] Pruning state data                       nodes=97,811,804 size=24.58GiB  elapsed=19m35.588s eta=11.204s
INFO [02-09|00:42:45.359] Pruned state data                        nodes=98,744,430 size=24.82GiB  elapsed=19m40.938s
INFO [02-09|00:42:45.360] Compacting database                      range=0x00-0x10 elapsed="2.157µs"
INFO [02-09|00:43:12.311] Compacting database                      range=0x10-0x20 elapsed=26.951s
INFO [02-09|00:43:38.763] Compacting database                      range=0x20-0x30 elapsed=53.402s
INFO [02-09|00:44:04.847] Compacting database                      range=0x30-0x40 elapsed=1m19.486s
INFO [02-09|00:44:31.194] Compacting database                      range=0x40-0x50 elapsed=1m45.834s
INFO [02-09|00:45:31.580] Compacting database                      range=0x50-0x60 elapsed=2m46.220s
INFO [02-09|00:45:58.465] Compacting database                      range=0x60-0x70 elapsed=3m13.104s
INFO [02-09|00:51:17.593] Compacting database                      range=0x70-0x80 elapsed=8m32.233s
INFO [02-09|00:56:19.679] Compacting database                      range=0x80-0x90 elapsed=13m34.319s
INFO [02-09|00:56:46.011] Compacting database                      range=0x90-0xa0 elapsed=14m0.651s
INFO [02-09|00:57:12.370] Compacting database                      range=0xa0-0xb0 elapsed=14m27.010s
INFO [02-09|00:57:38.600] Compacting database                      range=0xb0-0xc0 elapsed=14m53.239s
INFO [02-09|00:58:06.311] Compacting database                      range=0xc0-0xd0 elapsed=15m20.951s
INFO [02-09|00:58:35.484] Compacting database                      range=0xd0-0xe0 elapsed=15m50.123s
INFO [02-09|00:59:05.449] Compacting database                      range=0xe0-0xf0 elapsed=16m20.089s
INFO [02-09|00:59:34.365] Compacting database                      range=0xf0-     elapsed=16m49.005s
INFO [02-09|00:59:34.367] Database compaction finished             elapsed=16m49.006s
INFO [02-09|00:59:34.367] State pruning successful                 pruned=24.82GiB elapsed=39m34.749s
INFO [02-09|00:59:34.367] Completed offline pruning. Re-initializing blockchain.
INFO [02-09|00:59:34.387] Loaded most recent local header          number=10,671,401 hash=b52d0a..7bd166 age=40m29s
INFO [02-09|00:59:34.387] Loaded most recent local full block      number=10,671,401 hash=b52d0a..7bd166 age=40m29s
INFO [02-09|00:59:34.387] Initializing snapshots                   async=true
DEBUG[02-09|00:59:34.390] Reinjecting stale transactions           count=0
INFO [02-09|00:59:34.395] Transaction pool price threshold updated price=470,000,000,000
INFO [02-09|00:59:34.396] Transaction pool price threshold updated price=225,000,000,000
INFO [02-09|00:59:34.396] Transaction pool price threshold updated price=0
INFO [02-09|00:59:34.396] lastAccepted = 0xb52d0a1302e4055b487c3a0243106b5e13a915c6e178da9f8491cebf017bd166
INFO [02-09|00:59:34] <C Chain> snow/engine/snowman/transitive.go#67: initializing consensus engine
INFO [02-09|00:59:34] <C Chain> snow/engine/snowman/bootstrap/bootstrapper.go#220: Starting bootstrap...
INFO [02-09|00:59:34] chains/manager.go#246: creating chain:
    ID: 2oYMBNV4eNHyqk2fjjV5nVQLDbtmNJzq5s3qs3Lo6ftnC6FByM
    VMID:jvYyfQTxGMJLuGWa55kdP2p2zSUYsQ5Raupu4TW34ZAUBAbtq
INFO [02-09|00:59:34.425] Enabled APIs: eth, eth-filter, net, web3, internal-eth, internal-blockchain, internal-transaction, avax
DEBUG[02-09|00:59:34.425] Allowed origin(s) for WS RPC interface [*]
INFO [02-09|00:59:34] api/server/server.go#203: adding route /ext/bc/2q9e4r6Mu3U68nU1fYjgbR6JvwrRx36CohpAX5UQxse55x1Q5/avax
INFO [02-09|00:59:34] api/server/server.go#203: adding route /ext/bc/2q9e4r6Mu3U68nU1fYjgbR6JvwrRx36CohpAX5UQxse55x1Q5/rpc
INFO [02-09|00:59:34] api/server/server.go#203: adding route /ext/bc/2q9e4r6Mu3U68nU1fYjgbR6JvwrRx36CohpAX5UQxse55x1Q5/ws
INFO [02-09|00:59:34] <X Chain> vms/avm/vm.go#437: Fee payments are using Asset with Alias: AVAX, AssetID: FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z
INFO [02-09|00:59:34] <X Chain> vms/avm/vm.go#229: address transaction indexing is disabled
INFO [02-09|00:59:34] <X Chain> snow/engine/avalanche/transitive.go#71: initializing consensus engine
INFO [02-09|00:59:34] <X Chain> snow/engine/avalanche/bootstrap/bootstrapper.go#258: Starting bootstrap...
INFO [02-09|00:59:34] api/server/server.go#203: adding route /ext/bc/2oYMBNV4eNHyqk2fjjV5nVQLDbtmNJzq5s3qs3Lo6ftnC6FByM
INFO [02-09|00:59:34] <P Chain> snow/engine/snowman/bootstrap/bootstrapper.go#445: waiting for the remaining chains in this subnet to finish syncing
INFO [02-09|00:59:34] api/server/server.go#203: adding route /ext/bc/2oYMBNV4eNHyqk2fjjV5nVQLDbtmNJzq5s3qs3Lo6ftnC6FByM/wallet
INFO [02-09|00:59:34] api/server/server.go#203: adding route /ext/bc/2oYMBNV4eNHyqk2fjjV5nVQLDbtmNJzq5s3qs3Lo6ftnC6FByM/events
INFO [02-09|00:59:34] <P Chain> snow/engine/common/bootstrapper.go#235: Bootstrapping started syncing with 1 vertices in the accepted frontier
INFO [02-09|00:59:46] <X Chain> snow/engine/common/bootstrapper.go#235: Bootstrapping started syncing with 2 vertices in the accepted frontier
INFO [02-09|00:59:49] <C Chain> snow/engine/common/bootstrapper.go#235: Bootstrapping started syncing with 1 vertices in the accepted frontier
INFO [02-09|00:59:49] <X Chain> snow/engine/avalanche/bootstrap/bootstrapper.go#473: bootstrapping fetched 55 vertices. Executing transaction state transitions...
INFO [02-09|00:59:49] <X Chain> snow/engine/common/queue/jobs.go#171: executed 55 operations
INFO [02-09|00:59:49] <X Chain> snow/engine/avalanche/bootstrap/bootstrapper.go#484: executing vertex state transitions...
INFO [02-09|00:59:49] <X Chain> snow/engine/common/queue/jobs.go#171: executed 55 operations
INFO [02-09|01:00:07] <C Chain> snow/engine/snowman/bootstrap/bootstrapper.go#406: bootstrapping fetched 1241 blocks. Executing state transitions...
```

At this point, the node will go into bootstrapping and (once bootstrapping completes) resume consensus and operate as normal.

Disk Space Considerations[​](#disk-space-considerations "Direct link to heading")
---------------------------------------------------------------------------------

To ensure the node does not enter an inconsistent state, the bloom filter used for pruning is persisted to `offline-pruning-data-directory` for the duration of the operation. This directory should have `offline-pruning-bloom-filter-size` available in disk space (default 512 MB).

The underlying database (LevelDB) uses deletion markers (tombstones) to identify newly deleted keys. These markers are temporarily persisted to disk until they are removed during a process known as compaction. This will lead to an increase in disk usage during pruning. If your node runs out of disk space during pruning, you may safely restart the pruning operation. This may succeed as restarting the node triggers compaction.

If restarting the pruning operation does not succeed, additional disk space should be provisioned.

# Run Avalanche Node in Background (/docs/nodes/maintain/run-as-background-service)

---
title: Run Avalanche Node in Background
---

This page demonstrates how to set up a `avalanchego.service` file to enable a manually deployed validator node to run in the background of a server instead of in the terminal directly.

Make sure that AvalancheGo is already installed on your machine.

Steps[​](#steps "Direct link to heading")
-----------------------------------------

### Fuji Testnet Config[​](#fuji-testnet-config "Direct link to heading")

Run this command in your terminal to create the `avalanchego.service` file

```bash
sudo nano /etc/systemd/system/avalanchego.service
```

Paste the following configuration into the `avalanchego.service` file

Remember to modify the values of:

- _**user=**_
- _**group=**_
- _**WorkingDirectory=**_
- _**ExecStart=**_

For those that you have configured on your Server:

```toml
[Unit]
Description=Avalanche Node service
After=network.target

[Service]
User='YourUserHere'
Group='YourUserHere'
Restart=always
PrivateTmp=true
TimeoutStopSec=60s
TimeoutStartSec=10s
StartLimitInterval=120s
StartLimitBurst=5
WorkingDirectory=/Your/Path/To/avalanchego
ExecStart=/Your/Path/To/avalanchego/./avalanchego \  
   --network-id=fuji \
   --api-metrics-enabled=true 

[Install]
WantedBy=multi-user.target
```

Press **Ctrl + X** then **Y** then **Enter** to save and exit.

Now, run:

```bash
sudo systemctl daemon-reload
```

### Mainnet Config[​](#mainnet-config "Direct link to heading")

Run this command in your terminal to create the `avalanchego.service` file

```bash
sudo nano /etc/systemd/system/avalanchego.service
```

Paste the following configuration into the `avalanchego.service` file

```toml
[Unit]
Description=Avalanche Node service
After=network.target

[Service]
User='YourUserHere'
Group='YourUserHere'
Restart=always
PrivateTmp=true
TimeoutStopSec=60s
TimeoutStartSec=10s
StartLimitInterval=120s
StartLimitBurst=5
WorkingDirectory=/Your/Path/To/avalanchego
ExecStart=/Your/Path/To/avalanchego/./avalanchego \
   --api-metrics-enabled=true

[Install]
WantedBy=multi-user.target
```

Press **Ctrl + X** then **Y** then **Enter** to save and exit.

Now, run:

```bash
sudo systemctl daemon-reload
```

Start the Node[​](#start-the-node "Direct link to heading")
-----------------------------------------------------------

This command makes your node start automatically in case of a reboot, run it:

```bash
sudo systemctl enable avalanchego
```

To start the node, run:

```bash
sudo systemctl start avalanchego
sudo systemctl status avalanchego
```

Output:

```bash
socopower@avalanche-node-01:~$ sudo systemctl status avalanchego
● avalanchego.service - Avalanche Node service
     Loaded: loaded (/etc/systemd/system/avalanchego.service; enabled; vendor p>
     Active: active (running) since Tue 2023-08-29 23:14:45 UTC; 5h 46min ago
   Main PID: 2226 (avalanchego)
      Tasks: 27 (limit: 38489)
     Memory: 8.7G
        CPU: 5h 50min 31.165s
     CGroup: /system.slice/avalanchego.service
             └─2226 /usr/local/bin/avalanchego/./avalanchego --network-id=fuji

Aug 30 03:02:50 avalanche-node-01 avalanchego[2226]: INFO [08-30|03:02:50.685] >
Aug 30 03:02:51 avalanche-node-01 avalanchego[2226]: INFO [08-30|03:02:51.185] >
Aug 30 03:03:09 avalanche-node-01 avalanchego[2226]: [08-30|03:03:09.380] INFO >
Aug 30 03:03:23 avalanche-node-01 avalanchego[2226]: [08-30|03:03:23.983] INFO >
Aug 30 03:05:15 avalanche-node-01 avalanchego[2226]: [08-30|03:05:15.192] INFO >
Aug 30 03:05:15 avalanche-node-01 avalanchego[2226]: [08-30|03:05:15.237] INFO >
Aug 30 03:05:15 avalanche-node-01 avalanchego[2226]: [08-30|03:05:15.238] INFO >
Aug 30 03:05:19 avalanche-node-01 avalanchego[2226]: [08-30|03:05:19.809] INFO >
Aug 30 03:05:19 avalanche-node-01 avalanchego[2226]: [08-30|03:05:19.809] INFO >
Aug 30 05:00:47 avalanche-node-01 avalanchego[2226]: [08-30|05:00:47.001] INFO
```

To see the synchronization process, you can run the following command:

```bash
sudo journalctl -fu avalanchego
```


# Upgrade Your AvalancheGo Node (/docs/nodes/maintain/upgrade)

---
title: Upgrade Your AvalancheGo Node
---

Backup Your Node[​](#backup-your-node "Direct link to heading")
---------------------------------------------------------------

Before upgrading your node, it is recommended you backup your staker files which are used to identify your node on the network. In the default installation, you can copy them by running following commands:

```bash
cd
cp ~/.avalanchego/staking/staker.crt .
cp ~/.avalanchego/staking/staker.key .
```

Then download `staker.crt` and `staker.key` files and keep them somewhere safe and private. If anything happens to your node or the machine node runs on, these files can be used to fully recreate your node.

If you use your node for development purposes and have keystore users on your node, you should back up those too.

Node Installed Using the Installer Script[​](#node-installed-using-the-installer-script "Direct link to heading")
-----------------------------------------------------------------------------------------------------------------

If you installed your node using the [installer script](/docs/nodes/using-install-script/installing-avalanche-go), to upgrade your node, just run the installer script again.

```bash
./avalanchego-installer.sh
```

It will detect that you already have AvalancheGo installed:

```bash
AvalancheGo installer
---------------------
Preparing environment...
Found 64bit Intel/AMD architecture...
Found AvalancheGo systemd service already installed, switching to upgrade mode.
Stopping service...
```

It will then upgrade your node to the latest version, and after it's done, start the node back up, and print out the information about the latest version:

```bash
Node upgraded, starting service...
New node version:
avalanche/1.1.1 [network=mainnet, database=v1.0.0, commit=f76f1fd5f99736cf468413bbac158d6626f712d2]
Done!
```

And that is it, your node is upgraded to the latest version.

If you installed your node manually, proceed with the rest of the tutorial.

Stop the Old Node Version[​](#stop-the-old-node-version "Direct link to heading")
---------------------------------------------------------------------------------

After the backup is secured, you may start upgrading your node. Begin by stopping the currently running version.

### Node Running from Terminal[​](#node-running-from-terminal "Direct link to heading")

If your node is running in a terminal stop it by pressing `ctrl+c`.

### Node Running as a Service[​](#node-running-as-a-service "Direct link to heading")

If your node is running as a service, stop it by entering: `sudo systemctl stop avalanchego.service`

(your service may be named differently, `avalanche.service`, or similar)

### Node Running in Background[​](#node-running-in-background "Direct link to heading")

If your node is running in the background (by running with `nohup`, for example) then find the process running the node by running `ps aux | grep avalanche`. This will produce output like:

```bash
ubuntu  6834  0.0  0.0   2828   676 pts/1    S+   19:54   0:00 grep avalanche
ubuntu  2630 26.1  9.4 2459236 753316 ?      Sl   Dec02 1220:52 /home/ubuntu/build/avalanchego
```

In this example, second line shows information about your node. Note the process id, in this case, `2630`. Stop the node by running `kill -2 2630`.

Now we are ready to download the new version of the node. You can either download the source code and then build the binary program, or you can download the pre-built binary. You don't need to do both.

Downloading pre-built binary is easier and recommended if you're just looking to run your own node and stake on it.

Building the node [from source](/docs/nodes/maintain/upgrade#build-from-source) is recommended if you're a developer looking to experiment and build on Avalanche.

Download Pre-Built Binary[​](#download-pre-built-binary "Direct link to heading")
---------------------------------------------------------------------------------

If you want to download a pre-built binary instead of building it yourself, go to our [releases page](https://github.com/ava-labs/avalanchego/releases), and select the release you want (probably the latest one.)

<Callout title="Note">
If you have a node, you can subscribe to the [avalanche notify service](/docs/nodes/maintain/enroll-in-avalanche-notify) with your node ID to be notified about new releases.

In addition, or if you don't have a node ID, you can get release notifications from github. To do so, you can go to our [repository](https://github.com/ava-labs/avalanchego) and look on the top-right corner for the **Watch** option. After you click on it, select **Custom**, and then **Releases**. Press **Apply** and it is done.
</Callout>

Under `Assets`, select the appropriate file.

For MacOS:  
Download: `avalanchego-macos-<VERSION>.zip`  
Unzip: `unzip avalanchego-macos-<VERSION>.zip`  
The resulting folder, `avalanchego-<VERSION>`, contains the binaries.

For Linux on PCs or cloud providers:  
Download: `avalanchego-linux-amd64-<VERSION>.tar.gz`  
Unzip: `tar -xvf avalanchego-linux-amd64-<VERSION>.tar.gz`  
The resulting folder, `avalanchego-<VERSION>-linux`, contains the binaries.

For Linux on Arm64-based computers:  
Download: `avalanchego-linux-arm64-<VERSION>.tar.gz`  
Unzip: `tar -xvf avalanchego-linux-arm64-<VERSION>.tar.gz`  
The resulting folder, `avalanchego-<VERSION>-linux`, contains the binaries.

You are now ready to run the new version of the node.

### Running the Node from Terminal[​](#running-the-node-from-terminal "Direct link to heading")

If you are using the pre-built binaries on MacOS:

```bash
./avalanchego-<VERSION>/build/avalanchego
```

If you are using the pre-built binaries on Linux:

```bash
./avalanchego-<VERSION>-linux/avalanchego
```

Add `nohup` at the start of the command if you want to run the node in the background.

### Running the Node as a Service[​](#running-the-node-as-a-service "Direct link to heading")

If you're running the node as a service, you need to replace the old binaries with the new ones.

```bash
cp -r avalanchego-<VERSION>-linux/* <DIRECTORY_WITH_OLD_BINARIES>
```

and then restart the service with: `sudo systemctl start avalanchego.service`.

Build from Source[​](#build-from-source "Direct link to heading")
-----------------------------------------------------------------

First clone our GitHub repo (you can skip this step if you've done this before):

```bash
git clone https://github.com/ava-labs/avalanchego.git
```

<Callout title="Note">
The repository cloning method used is HTTPS, but SSH can be used too:

`git clone git@github.com:ava-labs/avalanchego.git`

You can find more about SSH and how to use it [here](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/about-ssh).
</Callout>

Then move to the AvalancheGo directory:

```bash
cd avalanchego
```

Pull the latest code:

```bash
git pull
```

<Callout title="Note">
If the master branch has not been updated with the latest release tag, you can get to it directly via first running `git fetch --all --tags` and then `git checkout --force tags/<tag>` (where `<tag>` is the latest release tag; for example `v1.3.2`) instead of `git pull`.

Note that your local copy will be in a 'detached HEAD' state, which is not an issue if you do not make changes to the source that you want push back to the repository (in which case you should check out to a branch and to the ordinary merges).

Note also that the `--force` flag will disregard any local changes you might have.
</Callout>

Check that your local code is up to date. Do:

```bash
git rev-parse HEAD
```

and check that the first 7 characters printed match the Latest commit field on our [GitHub](https://github.com/ava-labs/avalanchego).

<Callout title="Note">
If you used the `git checkout tags/<tag>` then these first 7 characters should match commit hash of that tag.
</Callout>

Now build the binary: 
```bash
./scripts/build.sh
```

This should print: `Build Successful`

You can check what version you're running by doing:

```bash
./build/avalanchego --version
```

You can run your node with:

```bash
./build/avalanchego
```

# Amazon Web Services (/docs/nodes/on-third-party-services/amazon-web-services)

---
title: Amazon Web Services
description: Learn how to run a node on Amazon Web Services.
---

Introduction[​](#introduction "Direct link to heading")
-------------------------------------------------------

This tutorial will guide you through setting up an Avalanche node on [Amazon Web Services (AWS)](https://aws.amazon.com/). Cloud services like AWS are a good way to ensure that your node is highly secure, available, and accessible.

To get started, you'll need:

- An AWS account
- A terminal with which to SSH into your AWS machine
- A place to securely store and back up files

This tutorial assumes your local machine has a Unix style terminal. If you're on Windows, you'll have to adapt some of the commands used here.

Log Into AWS[​](#log-into-aws "Direct link to heading")
-------------------------------------------------------

Signing up for AWS is outside the scope of this article, but Amazon has instructions [here](https://aws.amazon.com/premiumsupport/knowledge-center/create-and-activate-aws-account).

It is _highly_ recommended that you set up Multi-Factor Authentication on your AWS root user account to protect it. Amazon has documentation for this [here](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_mfa_enable_virtual.html#enable-virt-mfa-for-root).

Once your account is set up, you should create a new EC2 instance. An EC2 is a virtual machine instance in AWS's cloud. Go to the [AWS Management Console](https://console.aws.amazon.com/) and enter the EC2 dashboard.

![AWS Management Console.png](/images/amazon1.png)

To log into the EC2 instance, you will need a key on your local machine that grants access to the instance. First, create that key so that it can be assigned to the EC2 instance later on. On the bar on the left side, under **Network & Security**, select **Key Pairs.**

![Select &quot;Key Pairs&quot; under the &quot;Network &amp; Security&quot; drop-down.](/images/amazon2.png)

Select **Create key pair** to launch the key pair creation wizard.

![Select "Create key pair."](/images/amazon3.png)

Name your key `avalanche`. If your local machine has MacOS or Linux, select the `pem` file format. If it's Windows, use the `ppk` file format. Optionally, you can add tags for the key pair to assist with tracking.

![Create a key pair that will later be assigned to your EC2 instance.](/images/amazon4.png)

Click `Create key pair`. You should see a success message, and the key file should be downloaded to your local machine. Without this file, you will not be able to access your EC2 instance. **Make a copy of this file and put it on a separate storage medium such as an external hard drive. Keep this file secret; do not share it with others.**

![Success message after creating a key pair.](/images/amazon5.png)

Create a Security Group[​](#create-a-security-group "Direct link to heading")
-----------------------------------------------------------------------------

An AWS Security Group defines what internet traffic can enter and leave your EC2 instance. Think of it like a firewall. Create a new Security Group by selecting **Security Groups** under the **Network & Security** drop-down.

![Select "Security Groups" underneath "Network & Security."](/images/amazon6.png)

This opens the Security Groups panel. Click **Create security group** in the top right of the Security Groups panel.

![Select "Create security group."](/images/amazon7.png)

You'll need to specify what inbound traffic is allowed. Allow SSH traffic from your IP address so that you can log into your EC2 instance (each time your ISP changes your IP address, you will need to modify this rule). Allow TCP traffic on port 9651 so your node can communicate with other nodes on the network. Allow TCP traffic on port 9650 from your IP so you can make API calls to your node. **It's important that you only allow traffic on the SSH and API port from your IP.** If you allow incoming traffic from anywhere, this could be used to brute force entry to your node (SSH port) or used as a denial of service attack vector (API port). Finally, allow all outbound traffic.

![Your inbound and outbound rules should look like this.](/images/amazon8.png)

Add a tag to the new security group with key `Name` and value`Avalanche Security Group`. This will enable us to know what this security group is when we see it in the list of security groups.

![Tag the security group so you can identify it later.](/images/amazon9.png)

Click `Create security group`. You should see the new security group in the list of security groups.

Launch an EC2 Instance[​](#launch-an-ec2-instance "Direct link to heading")
---------------------------------------------------------------------------

Now you're ready to launch an EC2 instance. Go to the EC2 Dashboard and select **Launch instance**.

![Select "Launch Instance."](/images/amazon10.png)

Select **Ubuntu 20.04 LTS (HVM), SSD Volume Type** for the operating system.

![Select Ubuntu 20.04 LTS.](/images/amazon11.png)

Next, choose your instance type. This defines the hardware specifications of the cloud instance. In this tutorial we set up a **c5.2xlarge**. This should be more than powerful enough since Avalanche is a lightweight consensus protocol. To create a c5.2xlarge instance, select the **Compute-optimized** option from the filter drop-down menu.

![Filter by compute optimized.](/images/amazon12.png)

Select the checkbox next to the c5.2xlarge instance in the table.

![Select c5.2xlarge.](/images/amazon13.png)

Click the **Next: Configure Instance Details** button in the bottom right-hand corner.

![Configure instance details](/images/amazon14.png)

The instance details can stay as their defaults.

<Callout title="Note">
When setting up a node as a validator, it is crucial to select the appropriate AWS instance type to ensure the node can efficiently process transactions and manage the network load. The recommended instance types are as follows:

- For a minimal stake, start with a compute-optimized instance such as c6, c6i, c6a, c7 and similar.
- Use a 2xlarge instance size for the minimal stake configuration.
- As the staked amount increases, choose larger instance sizes to accommodate the additional workload. For every order of magnitude increase in stake, move up one instance size. For example, for a 20k AVAX stake, a 4xlarge instance is suitable.
</Callout>

### Optional: Using Reserved Instances[​](#optional-using-reserved-instances "Direct link to heading")

By default, you will be charged hourly for running your EC2 instance. For a long term usage that is not optimal.

You could save money by using a **Reserved Instance**. With a reserved instance, you pay upfront for an entire year of EC2 usage, and receive a lower per-hour rate in exchange for locking in. If you intend to run a node for a long time and don't want to risk service interruptions, this is a good option to save money. Again, do your own research before selecting this option.

### Add Storage, Tags, Security Group[​](#add-storage-tags-security-group "Direct link to heading")

Click the **Next: Add Storage** button in the bottom right corner of the screen.

You need to add space to your instance's disk. You should start with at least 700GB of disk space. Although upgrades to reduce disk usage are always in development, on average the database will continually grow, so you need to constantly monitor disk usage on the node and increase disk space if needed.

Note that the image below shows 100GB as disk size, which was appropriate at the time the screenshot was taken. You should check the current [recommended disk space size](https://github.com/ava-labs/avalanchego#installation) before entering the actual value here.

![Select disk size.](/images/amazon15.png)

Click **Next: Add Tags** in the bottom right corner of the screen to add tags to the instance. Tags enable us to associate metadata with our instance. Add a tag with key `Name` and value `My Avalanche Node`. This will make it clear what this instance is on your list of EC2 instances.

![Add a tag with key "Name" and value "My Avalanche Node."](/images/amazon16.png)

Now assign the security group created earlier to the instance. Choose **Select an existing security group** and choose the security group created earlier.

![Choose the security group created earlier.](/images/amazon17.png)

Finally, click **Review and Launch** in the bottom right. A review page will show the details of the instance you're about to launch. Review those, and if all looks good, click the blue **Launch** button in the bottom right corner of the screen.

You'll be asked to select a key pair for this instance. Select **Choose an existing key pair** and then select the `avalanche` key pair you made earlier in the tutorial. Check the box acknowledging that you have access to the `.pem` or `.ppk` file created earlier (make sure you've backed it up!) and then click **Launch Instances**.

![Use the key pair created earlier.](/images/amazon18.png)

You should see a new pop up that confirms the instance is launching!

![Your instance is launching!](/images/amazon19.png)

### Assign an Elastic IP[​](#assign-an-elastic-ip "Direct link to heading")

By default, your instance will not have a fixed IP. Let's give it a fixed IP through AWS's Elastic IP service. Go back to the EC2 dashboard. Under **Network & Security,** select **Elastic IPs**.

![Select "Elastic IPs" under "Network & Security."](/images/amazon20.png)

Select **Allocate Elastic IP address**.

![Select "Allocate Elastic IP address."](/images/amazon21.png)

Select the region your instance is running in, and choose to use Amazon's pool of IPv4 addresses. Click **Allocate**.

![Settings for the Elastic IP.](/images/amazon22.png)

Select the Elastic IP you just created from the Elastic IP manager. From the **Actions** drop-down, choose **Associate Elastic IP address**.

![Under "Actions" select "Associate Elastic IP address."](/images/amazon23.png)

Select the instance you just created. This will associate the new Elastic IP with the instance and give it a public IP address that won't change.

![Assign the Elastic IP to your EC2 instance.](/images/amazon24.png)

Set Up AvalancheGo[​](#set-up-avalanchego "Direct link to heading")
-------------------------------------------------------------------

Go back to the EC2 Dashboard and select `Running Instances`.

![Go to your running instances.](/images/amazon25.png)

Select the newly created EC2 instance. This opens a details panel with information about the instance.

![Details about your new instance.](/images/amazon26.png)

Copy the `IPv4 Public IP` field to use later. From now on we call this value `PUBLICIP`.

**Remember: the terminal commands below assume you're running Linux. Commands may differ for MacOS or other operating systems. When copy-pasting a command from a code block, copy and paste the entirety of the text in the block.**

Log into the AWS instance from your local machine. Open a terminal (try shortcut `CTRL + ALT + T`) and navigate to the directory containing the `.pem` file you downloaded earlier.

Move the `.pem` file to `$HOME/.ssh` (where `.pem` files generally live) with:

Add it to the SSH agent so that we can use it to SSH into your EC2 instance, and mark it as read-only.

```bash
ssh-add ~/.ssh/avalanche.pem; chmod 400 ~/.ssh/avalanche.pem
```

SSH into the instance. (Remember to replace `PUBLICIP` with the public IP field from earlier.)

If the permissions are **not** set correctly, you will see the following error.

![Make sure you set the permissions correctly.](/images/amazon27.png)

You are now logged into the EC2 instance.

![You're on the EC2 instance.](/images/amazon28.png)

If you have not already done so, update the instance to make sure it has the latest operating system and security updates:

```bash
sudo apt update; sudo apt upgrade -y; sudo reboot
```

This also reboots the instance. Wait 5 minutes, then log in again by running this command on your local machine:

You're logged into the EC2 instance again. Now we'll need to set up our Avalanche node. To do this, follow the [Set Up Avalanche Node With Installer](/docs/nodes/using-install-script/installing-avalanche-go) tutorial which automates the installation process. You will need the `PUBLICIP` we set up earlier.

Your AvalancheGo node should now be running and in the process of bootstrapping, which can take a few hours. To check if it's done, you can issue an API call using `curl`. If you're making the request from the EC2 instance, the request is:

```bash
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"info.isBootstrapped",
    "params": {
        "chain":"X"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info
```

Once the node is finished bootstrapping, the response will be:

```json
{
    "jsonrpc": "2.0",
    "result": {
        "isBootstrapped": true
    },
    "id": 1
}
```

You can continue on, even if AvalancheGo isn't done bootstrapping.

In order to make your node a validator, you'll need its node ID. To get it, run:

```bash
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"info.getNodeID"
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info
```

The response contains the node ID.

```json
{"jsonrpc":"2.0","result":{"nodeID":"NodeID-DznHmm3o7RkmpLkWMn9NqafH66mqunXbM"},"id":1}
```

In the above example the node ID is`NodeID-DznHmm3o7RkmpLkWMn9NqafH66mqunXbM`. Copy your node ID for later. Your node ID is not a secret, so you can just paste it into a text editor.

AvalancheGo has other APIs, such as the [Health API](/docs/api-reference/health-api), that may be used to interact with the node. Some APIs are disabled by default. To enable such APIs, modify the ExecStart section of `/etc/systemd/system/avalanchego.service` (created during the installation process) to include flags that enable these endpoints. Don't manually enable any APIs unless you have a reason to.

![Some APIs are disabled by default.](/images/amazon29.png)

Back up the node's staking key and certificate in case the EC2 instance is corrupted or otherwise unavailable. The node's ID is derived from its staking key and certificate. If you lose your staking key or certificate then your node will get a new node ID, which could cause you to become ineligible for a staking reward if your node is a validator. **It is very strongly advised that you copy your node's staking key and certificate**. The first time you run a node, it will generate a new staking key/certificate pair and store them in directory `/home/ubuntu/.avalanchego/staking`.

Exit out of the SSH instance by running:

Now you're no longer connected to the EC2 instance; you're back on your local machine.

To copy the staking key and certificate to your machine, run the following command. As always, replace `PUBLICIP`.

```bash
scp -r ubuntu@PUBLICIP:/home/ubuntu/.avalanchego/staking ~/aws_avalanche_backup
```

Now your staking key and certificate are in directory `~/aws_avalanche_backup` . **The contents of this directory are secret.** You should hold this directory on storage not connected to the internet (like an external hard drive.)

### Upgrading Your Node[​](#upgrading-your-node "Direct link to heading")

AvalancheGo is an ongoing project and there are regular version upgrades. Most upgrades are recommended but not required. Advance notice will be given for upgrades that are not backwards compatible. To update your node to the latest version, SSH into your AWS instance as before and run the installer script again.

```bash
./avalanchego-installer.sh
```

Your machine is now running the newest AvalancheGo version. To see the status of the AvalancheGo service, run `sudo systemctl status avalanchego.`

Increase Volume Size[​](#increase-volume-size "Direct link to heading")
-----------------------------------------------------------------------

If you need to increase the volume size, follow these instructions from AWS:

- [Request modifications to your EBS volumes](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/requesting-ebs-volume-modifications.html)
- [Extend a Linux file system after resizing a volume](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/recognize-expanded-volume-linux.html)

Wrap Up[​](#wrap-up "Direct link to heading")
---------------------------------------------

That's it! You now have an AvalancheGo node running on an AWS EC2 instance. We recommend setting up [node monitoring](/docs/nodes/maintain/monitoring)for your AvalancheGo node. We also recommend setting up AWS billing alerts so you're not surprised when the bill arrives. If you have feedback on this tutorial, or anything else, send us a message on [Discord](https://chat.avalabs.org/).

# AWS Marketplace (/docs/nodes/on-third-party-services/aws-marketplace)

---
title: AWS Marketplace
description: Learn how to run a node on AWS Marketplace.
---

## How to Launch an Avalanche Validator using AWS

<iframe
  width="560"
  height="315"
  src="https://youtu.be/4RPmgpbC_Cc"
  title="YouTube video player"
  frameBorder="0"
  allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
  allowFullScreen
></iframe>

With the intention of enabling developers and entrepreneurs to on-ramp into the Avalanche ecosystem with as little friction as possible, Ava Labs recently launched an offering to deploy an Avalanche Validator node via the AWS Marketplace. This tutorial will show the main steps required to get this node running and validating on the Avalanche Fuji testnet.

Product Overview[​](#product-overview "Direct link to heading")
---------------------------------------------------------------

The Avalanche Validator node is available via [the AWS Marketplace](https://aws.amazon.com/marketplace/pp/prodview-nd6wgi2bhhslg). There you'll find a high level product overview. This includes a product description, pricing information, usage instructions, support information and customer reviews. After reviewing this information you want to click the "Continue to Subscribe" button.

Subscribe to This Software[​](#subscribe-to-this-software "Direct link to heading")
-----------------------------------------------------------------------------------

Once on the "Subscribe to this Software" page you will see a button which enables you to subscribe to this AWS Marketplace offering. In addition you'll see Terms of service including the seller's End User License Agreement and the [AWS Privacy Notice](https://aws.amazon.com/privacy/). After reviewing these you want to click on the "Continue to Configuration" button.

Configure This Software[​](#configure-this-software "Direct link to heading")
-----------------------------------------------------------------------------

This page lets you choose a fulfillment option and software version to launch this software. No changes are needed as the default settings are sufficient. Leave the `Fulfillment Option` as `64-bit (x86) Amazon Machine Image (AMI)`. The software version is the latest build of [the AvalancheGo full node](https://github.com/ava-labs/avalanchego/releases), `v1.9.5 (Dec 22, 2022)`, AKA `Banff.5`. This will always show the latest version. Also, the Region to deploy in can be left as `US East (N. Virginia)`. On the right you'll see the software and infrastructure pricing. Lastly, click the "Continue to Launch" button.

Launch This Software[​](#launch-this-software "Direct link to heading")
-----------------------------------------------------------------------

Here you can review the launch configuration details and follow the instructions to launch the Avalanche Validator Node. The changes are very minor. Leave the action as "Launch from Website." The EC2 Instance Type should remain `c5.2xlarge`. The primary change you'll need to make is to choose a keypair which will enable you to `ssh` into the newly created EC2 instance to run `curl` commands on the Validator node. You can search for existing Keypairs or you can create a new keypair and download it to your local machine. If you create a new keypair you'll need to move the keypair to the appropriate location, change the permissions and add it to the OpenSSH authentication agent. For example, on MacOS it would look similar to the following:

```bash
# In this example we have a keypair called avalanche.pem which was downloaded from AWS to ~/Downloads/avalanche.pem
# Confirm the file exists with the following command
test -f ~/Downloads/avalanche.pem && echo "Avalanche.pem exists."

# Running the above command will output the following:
# Avalanche.pem exists.

# Move the avalanche.pem keypair from the ~/Downloads directory to the hidden ~/.ssh directory
mv ~/Downloads/avalanche.pem ~/.ssh

# Next add the private key identity to the OpenSSH authentication agent
ssh-add ~/.ssh/avalanche.pem;

# Change file modes or Access Control Lists
sudo chmod 600 ~/.ssh/avalanche.pem
```

Once these steps are complete you are ready to launch the Validator node on EC2. To make that happen click the "Launch" button

![launch successful](/images/aws1.png)

You now have an Avalanche node deployed on an AWS EC2 instance! Copy the `AMI ID` and click on the `EC2 Console` link for the next step.

EC2 Console[​](#ec2-console "Direct link to heading")
-----------------------------------------------------

Now take the `AMI ID` from the previous step and input it into the search bar on the EC2 Console. This will bring you to the dashboard where you can find the EC2 instances public IP address.

![AMI instance](/images/aws2.png)

Copy that public IP address and open a Terminal or command line prompt. Once you have the new Terminal open `ssh` into the EC2 instance with the following command.

Node Configuration[​](#node-configuration "Direct link to heading")
-------------------------------------------------------------------

### Switch to Fuji Testnet[​](#switch-to-fuji-testnet "Direct link to heading")

By default the Avalanche Node available through the AWS Marketplace syncs the Mainnet. If this is what you are looking for, you can skip this step.

For this tutorial you want to sync and validate the Fuji Testnet. Now that you're `ssh`ed into the EC2 instance you can make the required changes to sync Fuji instead of Mainnet.

First, confirm that the node is syncing the Mainnet by running the `info.getNetworkID` command.

#### `info.getNetworkID` Request[​](#infogetnetworkid-request "Direct link to heading")

```bash
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"info.getNetworkID",
    "params": {
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info
```

#### `info.getNetworkID` Response[​](#infogetnetworkid-response "Direct link to heading")

The returned `networkID` will be 1 which is the network ID for Mainnet.

```json
{
  "jsonrpc": "2.0",
  "result": {
    "networkID": "1"
  },
  "id": 1
}
```

Now you want to edit `/etc/avalanchego/conf.json` and change the `"network-id"` property from `"mainnet"` to `"fuji"`. To see the contents of `/etc/avalanchego/conf.json` you can `cat` the file.

```bash
cat /etc/avalanchego/conf.json
{
  "api-keystore-enabled": false,
  "http-host": "0.0.0.0",
  "log-dir": "/var/log/avalanchego",
  "db-dir": "/data/avalanchego",
  "api-admin-enabled": false,
  "public-ip-resolution-service": "opendns",
  "network-id": "mainnet"
}
```

Edit that `/etc/avalanchego/conf.json` with your favorite text editor and change the value of the `"network-id"` property from `"mainnet"` to `"fuji"`. Once that's complete, save the file and restart the Avalanche node via `sudo systemctl restart avalanchego`. You can then call the `info.getNetworkID` endpoint to confirm the change was successful.

#### `info.getNetworkID` Request[​](#infogetnetworkid-request-1 "Direct link to heading")

```bash
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"info.getNetworkID",
    "params": {
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info
```

#### `info.getNetworkID` Response[​](#infogetnetworkid-response-1 "Direct link to heading")

The returned `networkID` will be 5 which is the network ID for Fuji.

```json
{
  "jsonrpc": "2.0",
  "result": {
    "networkID": "5"
  },
  "id": 1
}
```

Next you run the `info.isBoostrapped` command to confirm if the Avalanche Validator node has finished bootstrapping.

### `info.isBootstrapped` Request[​](#infoisbootstrapped-request "Direct link to heading")

```bash
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"info.isBootstrapped",
    "params": {
        "chain":"P"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info
```

Once the node is finished bootstrapping, the response will be:

### `info.isBootstrapped` Response[​](#infoisbootstrapped-response "Direct link to heading")

```json
{
    "jsonrpc": "2.0",
    "result": {
        "isBootstrapped": true
    },
    "id": 1
}
```

**Note** that initially the response is `false` because the network is still syncing.  
When you're adding your node as a Validator on the Avalanche Mainnet you'll want to wait for this response to return `true` so that you don't suffer from any downtime while validating. For this tutorial you're not going to wait for it to finish syncing as it's not strictly necessary.

### `info.getNodeID` Request[​](#infogetnodeid-request "Direct link to heading")

Next, you want to get the NodeID which will be used to add the node as a Validator. To get the node's ID you call the `info.getNodeID` jsonrpc endpoint.

```bash
curl --location --request POST 'http://127.0.0.1:9650/ext/info' \
--header 'Content-Type: application/json' \
--data-raw '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"info.getNodeID",
    "params" :{
    }
}'
```

### `info.getNodeID` Response[​](#infogetnodeid-response "Direct link to heading")

Take a note of the `nodeID` value which is returned as you'll need to use it in the next step when adding a validator via the Avalanche Web Wallet. In this case the `nodeID` is `NodeID-Q8Gfaaio9FAqCmZVEXDq9bFvNPvDi7rt5`

```json
{
  "jsonrpc": "2.0",
  "result": {
    "nodeID": "NodeID-Q8Gfaaio9FAqCmZVEXDq9bFvNPvDi7rt5",
    "nodePOP": {
      "publicKey": "0x85675db18b326a9585bfd43892b25b71bf01b18587dc5fac136dc5343a9e8892cd6c49b0615ce928d53ff5dc7fd8945d",
      "proofOfPossession": "0x98a56f092830161243c1f1a613ad68a7f1fb25d2462ecf85065f22eaebb4e93a60e9e29649a32252392365d8f628b2571174f520331ee0063a94473f8db6888fc3a722be330d5c51e67d0d1075549cb55376e1f21d1b48f859ef807b978f65d9"
    }
  },
  "id": 1
}
```

Add Node as Validator on Fuji via Core web[​](#add-node-as-validator-on-fuji-via-core-web "Direct link to heading")
-------------------------------------------------------------------------------------------------------------------

For adding the new node as a Validator on the Fuji testnet's Primary Network you can use the [Core web](https://core.app/) [connected](https://support.avax.network/en/articles/6639869-core-web-how-do-i-connect-to-core-web) to [Core extension](https://core.app). If you don't have a Core extension already, check out this [guide](https://support.avax.network/en/articles/6100129-core-extension-how-do-i-create-a-new-wallet). If you'd like to import an existing wallet to Core extension, follow [these steps](https://support.avax.network/en/articles/6078933-core-extension-how-do-i-access-my-existing-account).

![Core web](/images/aws3.png)

Core web is a free, all-in-one command center that gives users a more intuitive and comprehensive way to view assets, and use dApps across the Avalanche network, its various Avalanche L1s, and Ethereum. Core web is optimized for use with the Core browser extension and Core mobile (available on both iOS & Android). Together, they are key components of the Core product suite that brings dApps, NFTs, Avalanche Bridge, Avalanche L1s, L2s, and more, directly to users.

### Switching to Testnet Mode[​](#switching-to-testnet-mode "Direct link to heading")

By default, Core web and Core extension are connected to Mainnet. For the sake of this demo, you want to connect to the Fuji Testnet.

#### On Core Extension[​](#on-core-extension "Direct link to heading")

From the hamburger menu on the top-left corner, choose Advanced, and then toggle the Testnet Mode on.

![](/images/aws4.gif)

You can follow the same steps for switching back to Mainnet.

#### On Core web[​](#on-core-web "Direct link to heading")

Click on the Settings button top-right corner of the page, then toggle Testnet Mode on.

![](/images/aws5.gif)

You can follow the same steps for switching back to Mainnet.

### Adding the Validator[​](#adding-the-validator "Direct link to heading")

<Callout title="Note">
- Node ID: A unique ID derived from each individual node's staker certificate. Use the `NodeID` which was returned in the `info.getNodeID` response. In this example it's `NodeID-Q8Gfaaio9FAqCmZVEXDq9bFvNPvDi7rt5`  
- Staking End Date: Your AVAX tokens will be locked until this date.
- Stake Amount: The amount of AVAX to lock for staking. On Mainnet, the minimum required amount is 2,000 AVAX. On Testnet the minimum required amount is 1 AVAAX.  
- Delegation Fee: You will claim this % of the rewards from the delegators on your node.  
- Reward Address: A reward address is the destination address of the accumulated staking rewards.
</Callout>

To add a node as a Validator, first select the Stake tab on Core web, in the left hand nav menu. Next click the Validate button, and select Get Started.

![](/images/aws6.gif)

This page will open up.

![](/images/aws7.png)

Choose the desired Staking Amount, then click Next.

![](/images/aws8.png)

Enter you Node ID, then click Next.

![](/images/aws9.png)

Here, you'll need to choose the staking duration. There are predefined values, like 1 day, 1 month and so on. You can also choose a custom period of time. For this example, 22 days were chosen.

![](/images/aws10.png)

Choose the address that the network will send rewards to. Make sure it's the correct address because once the transaction is submitted this cannot be changed later or undone. You can choose the wallet's P-Chain address, or a custom P-Chain address. After entering the address, click Next.

![](/images/aws11.png)

Other individuals can stake to your validator and receive rewards too, known as "delegating." You will claim this percent of the rewards from the delegators on your node. Click Next.

![](/images/aws12.png)

After entering all these details, a summary of your validation will show up. If everything is correct, you can proceed and click on Submit Validation. A new page will open up, prompting you to accept the transaction. Here, please approve the transaction.

![](/images/aws13.png)

After the transaction is approved, you will see a message saying that your validation transaction was submitted.

![](/images/aws14.png)

If you click on View on explorer, a new browser tab will open with the details of the `AddValidatorTx`. It will show details such as the total value of AVAX transferred, any AVAX which were burned, the blockchainID, the blockID, the NodeID of the validator, and the total time which has elapsed from the entire Validation period.

![](/images/aws15.png)

Confirm That the Node is a Pending Validator on Fuji[​](#confirm-that-the-node-is-a-pending-validator-on-fuji "Direct link to heading")
---------------------------------------------------------------------------------------------------------------------------------------

As a last step you can call the `platform.getPendingvalidators` endpoint to confirm that the Avalanche node which was recently spun up on AWS is no in the pending validators queue where it will stay for 5 minutes.

### `platform.getPendingValidators` Request[​](#platformgetpendingvalidators-request "Direct link to heading")

```bash
curl --location --request POST 'https://api.avax-test.network/ext/bc/P' \
--header 'Content-Type: application/json' \
--data-raw '{
    "jsonrpc": "2.0",
    "method": "platform.getPendingValidators",
    "params": {
        "subnetID": "11111111111111111111111111111111LpoYY",
        "nodeIDs": []
    },
    "id": 1
}'
```

### `platform.getPendingValidators` Response[​](#platformgetpendingvalidators-response "Direct link to heading")

```json
{
  "jsonrpc": "2.0",
  "result": {
    "validators": [
      {
        "txID": "4d7ZboCrND4FjnyNaF3qyosuGQsNeJ2R4KPJhHJ55VCU1Myjd",
        "startTime": "1673411918",
        "endTime": "1675313170",
        "stakeAmount": "1000000000",
        "nodeID": "NodeID-Q8Gfaaio9FAqCmZVEXDq9bFvNPvDi7rt5",
        "delegationFee": "2.0000",
        "connected": false,
        "delegators": null
      }
    ],
    "delegators": []
  },
  "id": 1
}
```

You can also pass in the `NodeID` as a string to the `nodeIDs` array in the request body.

```bash
curl --location --request POST 'https://api.avax-test.network/ext/bc/P' \
--header 'Content-Type: application/json' \
--data-raw '{
    "jsonrpc": "2.0",
    "method": "platform.getPendingValidators",
    "params": {
        "subnetID": "11111111111111111111111111111111LpoYY",
        "nodeIDs": ["NodeID-Q8Gfaaio9FAqCmZVEXDq9bFvNPvDi7rt5"]
    },
    "id": 1
}'
```

This will filter the response by the `nodeIDs` array which will save you time by no longer requiring you to search through the entire response body for the NodeIDs.

```json
{
  "jsonrpc": "2.0",
  "result": {
    "validators": [
      {
        "txID": "4d7ZboCrND4FjnyNaF3qyosuGQsNeJ2R4KPJhHJ55VCU1Myjd",
        "startTime": "1673411918",
        "endTime": "1675313170",
        "stakeAmount": "1000000000",
        "nodeID": "NodeID-Q8Gfaaio9FAqCmZVEXDq9bFvNPvDi7rt5",
        "delegationFee": "2.0000",
        "connected": false,
        "delegators": null
      }
    ],
    "delegators": []
  },
  "id": 1
}
```

After 5 minutes the node will officially start validating the Avalanche Fuji testnet and you will no longer see it in the response body for the `platform.getPendingValidators` endpoint. Now you will access it via the `platform.getCurrentValidators` endpoint.

### `platform.getCurrentValidators` Request[​](#platformgetcurrentvalidators-request "Direct link to heading")

```bash
curl --location --request POST 'https://api.avax-test.network/ext/bc/P' \
--header 'Content-Type: application/json' \
--data-raw '{
    "jsonrpc": "2.0",
    "method": "platform.getCurrentValidators",
    "params": {
        "subnetID": "11111111111111111111111111111111LpoYY",
        "nodeIDs": ["NodeID-Q8Gfaaio9FAqCmZVEXDq9bFvNPvDi7rt5"]
    },
    "id": 1
}'
```

### `platform.getCurrentValidators` Response[​](#platformgetcurrentvalidators-response "Direct link to heading")

```json
{
  "jsonrpc": "2.0",
  "result": {
    "validators": [
      {
        "txID": "2hy57Z7KiZ8L3w2KonJJE1fs5j4JDzVHLjEALAHaXPr6VMeDhk",
        "startTime": "1673411918",
        "endTime": "1675313170",
        "stakeAmount": "1000000000",
        "nodeID": "NodeID-Q8Gfaaio9FAqCmZVEXDq9bFvNPvDi7rt5",
        "rewardOwner": {
          "locktime": "0",
          "threshold": "1",
          "addresses": [
            "P-fuji1tgj2c3k56enytw5d78rt0tsq3lzg8wnftffwk7"
          ]
        },
        "validationRewardOwner": {
          "locktime": "0",
          "threshold": "1",
          "addresses": [
            "P-fuji1tgj2c3k56enytw5d78rt0tsq3lzg8wnftffwk7"
          ]
        },
        "delegationRewardOwner": {
          "locktime": "0",
          "threshold": "1",
          "addresses": [
            "P-fuji1tgj2c3k56enytw5d78rt0tsq3lzg8wnftffwk7"
          ]
        },
        "potentialReward": "5400963",
        "delegationFee": "2.0000",
        "uptime": "0.0000",
        "connected": false,
        "delegators": null
      }
    ]
  },
  "id": 1
}
```

Mainnet[​](#mainnet "Direct link to heading")
---------------------------------------------

All of these steps can be applied to Mainnet. However, the minimum required Avax token amounts to become a validator is 2,000 on the Mainnet. For more information, please read [this doc](/docs/nodes/validate/how-to-stake#validators).

Maintenance[​](#maintenance "Direct link to heading")
-----------------------------------------------------

AWS one click is meant to be used in automated environments, not as an end-user solution. You can still manage it manually, but it is not as easy as an Ubuntu instance or using the script:

- AvalancheGo binary is at `/usr/local/bin/avalanchego`
- Main node config is at `/etc/avalanchego/conf.json`
- Working directory is at `/home/avalanche/.avalanchego/ (and belongs to avalanchego user)`
- Database is at `/data/avalanchego`
- Logs are at `/var/log/avalanchego`

For a simple upgrade you would need to place the new binary at `/usr/local/bin/`. If you run an Avalanche L1, you would also need to place the VM binary into `/home/avalanche/.avalanchego/plugins`.

You can also look at using [this guide](https://docs.aws.amazon.com/systems-manager/latest/userguide/automation-tutorial-update-ami.html), but that won't address updating the Avalanche L1, if you have one.

Summary[​](#summary "Direct link to heading")
---------------------------------------------

Avalanche is the first decentralized smart contracts platform built for the scale of global finance, with near-instant transaction finality. Now with an Avalanche Validator node available as a one-click install from the AWS Marketplace developers and entrepreneurs can on-ramp into the Avalanche ecosystem in a matter of minutes. If you have any questions or want to follow up in any way please join our Discord server at [https://discord.gg/avax](https://discord.gg/avax/). For more developer resources please check out our [Developer Documentation](/docs/).

# Google Cloud (/docs/nodes/on-third-party-services/google-cloud)

---
title: Google Cloud
description: Learn how to run an Avalanche node on Google Cloud.
---

<Callout type="warn">
This document was written by a community member, some information may be outdated.
</Callout>

Introduction[​](#introduction "Direct link to heading")
-------------------------------------------------------

Google's Cloud Platform (GCP) is a scalable, trusted and reliable hosting platform. Google operates a significant amount of it's own global networking infrastructure. It's [fiber network](https://cloud.google.com/blog/products/networking/google-cloud-networking-in-depth-cloud-cdn) can provide highly stable and consistent global connectivity. In this article, we will leverage GCP to deploy a node on which Avalanche can installed via [terraform](https://www.terraform.io/). Leveraging `terraform` may seem like overkill, it should set you apart as an operator and administrator as it will enable you greater flexibility and provide the basis on which you can easily build further automation.

Conventions[​](#conventions "Direct link to heading")
-----------------------------------------------------

- `Items` highlighted in this manor are GCP parlance and can be searched for further reference in the Google documentation for their cloud products.

Important Notes[​](#important-notes "Direct link to heading")
-------------------------------------------------------------

- The machine type used in this documentation is for reference only and the actual sizing you use will depend entirely upon the amount that is staked and delegated to the node.

Architectural Description[​](#architectural-description "Direct link to heading")
---------------------------------------------------------------------------------

This section aims to describe the architecture of the system that the steps in the [Setup Instructions](#-setup-instructions) section deploy when enacted. This is done so that the executor can not only deploy the reference architecture, but also understand and potentially optimize it for their needs.

### Project[​](#project "Direct link to heading")

We will create and utilize a single GCP `Project` for deployment of all resources.

#### Service Enablement[​](#service-enablement "Direct link to heading")

Within our GCP project we will need to enable the following Cloud Services:

- `Compute Engine`
- `IAP`

### Networking[​](#networking "Direct link to heading")

#### Compute Network[​](#compute-network "Direct link to heading")

We will deploy a single `Compute Network` object. This unit is where we will deploy all subsequent networking objects. It provides a logical boundary and securitization context should you wish to deploy other chain stacks or other infrastructure in GCP.

#### Public IP[​](#public-ip "Direct link to heading")

Avalanche requires that a validator communicate outbound on the same public IP address that it advertises for other peers to connect to it on. Within GCP this precludes the possibility of us using a Cloud NAT Router for the outbound communications and requires us to bind the public IP that we provision to the interface of the machine. We will provision a single `EXTERNAL` static IPv4 `Compute Address`.

#### Avalanche L1s[​](#avalanche-l1s "Direct link to heading")

For the purposes of this documentation we will deploy a single `Compute Subnetwork` in the US-EAST1 `Region` with a /24 address range giving us 254 IP addresses (not all usable but for the sake of generalized documentation).

### Compute[​](#compute "Direct link to heading")

#### Disk[​](#disk "Direct link to heading")

We will provision a single 400GB `PD-SSD` disk that will be attached to our VM.

#### Instance[​](#instance "Direct link to heading")

We will deploy a single `Compute Instance` of size `e2-standard-8`. Observations of operations using this machine specification suggest it is memory over provisioned and could be brought down to 16GB using custom machine specification; but please review and adjust as needed (the beauty of compute virtualization!!).

#### Zone[​](#zone "Direct link to heading")

We will deploy our instance into the `US-EAST1-B` `Zone`

#### Firewall[​](#firewall "Direct link to heading")

We will provision the following `Compute Firewall` rules:

- IAP INGRESS for SSH (TCP 22) - this only allows GCP IAP sources inbound on SSH.
- P2P INGRESS for AVAX Peers (TCP 9651)

These are obviously just default ports and can be tailored to your needs as you desire.

Setup Instructions[​](#-setup-instructions "Direct link to heading")
--------------------------------------------------------------------

### GCP Account[​](#gcp-account "Direct link to heading")

1.  If you don't already have a GCP account go create one [here](https://console.cloud.google.com/freetrial)

You will get some free bucks to run a trial, the trial is feature complete but your usage will start to deplete your free bucks so turn off anything you don't need and/or add a credit card to your account if you intend to run things long term to avoid service shutdowns.

### Project[​](#project-1 "Direct link to heading")

Login to the GCP `Cloud Console` and create a new `Project` in your organization. Let's use the name `my-avax-nodes` for the sake of this setup.

1.  ![Select Project Dropdown](/images/cloud1.png)

2.  ![Click New Project Button](/images/cloud2.png)

3.  ![Create New Project](/images/cloud3.png)

### Terraform State[​](#terraform-state "Direct link to heading")

Terraform uses a state files to compose a differential between current infrastructure configuration and the proposed plan. You can store this state in a variety of different places, but using GCP storage is a reasonable approach given where we are deploying so we will stick with that.

1.  ![Select Cloud Storage Browser](/images/cloud4.png)

2.  ![Create New Bucket](/images/cloud5.png)

Authentication to GCP from terraform has a few different options which are laid out [here](https://www.terraform.io/language/settings/backends/gcs). Please chose the option that aligns with your context and ensure those steps are completed before continuing.

<Callout title="Note">
Depending upon how you intend to execute your terraform operations you may or may not need to enable public access to the bucket. Obviously, not exposing the bucket for `public` access (even if authenticated) is preferable. If you intend to simply run terraform commands from your local machine then you will need to open the access up. I recommend to employ a full CI/CD pipeline using GCP Cloud Build which if utilized will mean the bucket can be marked as `private`. A full walk through of Cloud Build setup in this context can be found [here](https://cloud.google.com/architecture/managing-infrastructure-as-code)
</Callout>


### Clone GitHub Repository[​](#clone-github-repository "Direct link to heading")

I have provided a rudimentary terraform construct to provision a node on which to run Avalanche which can be found [here](https://github.com/meaghanfitzgerald/deprecated-avalanche-docs/tree/master/static/scripts). Documentation below assumes you are using this repository but if you have another terraform skeleton similar steps will apply.

### Terraform Configuration[​](#terraform-configuration "Direct link to heading")

1.  If running terraform locally, please [install](https://learn.hashicorp.com/tutorials/terraform/install-cli) it.
2.  In this repository, navigate to the `terraform` directory.
3.  Under the `projects` directory, rename the `my-avax-project` directory to match your GCP project name that you created (not required, but nice to be consistent)
4.  Under the folder you just renamed locate the `terraform.tfvars` file.
5.  Edit this file and populate it with the values which make sense for your context and save it.
6.  Locate the `backend.tf` file in the same directory.
7.  Edit this file ensuring to replace the `bucket` property with the GCS bucket name that you created earlier.

If you do not with to use cloud storage to persist terraform state then simply switch the `backend` to some other desirable provider.

### Terraform Execution[​](#terraform-execution "Direct link to heading")

Terraform enables us to see what it would do if we were to run it without actually applying any changes... this is called a `plan` operation. This plan is then enacted (optionally) by an `apply`.

#### Plan[​](#plan "Direct link to heading")

1.  In a terminal which is able to execute the `tf` binary, `cd` to the ~`my-avax-project` directory that you renamed in step 3 of `Terraform Configuration`.
2.  Execute the command `tf plan`
3.  You should see a JSON output to the stdout of the terminal which lays out the operations that terraform will execute to apply the intended state.

#### Apply[​](#apply "Direct link to heading")

1.  In a terminal which is able to execute the `tf` binary, `cd` to the ~`my-avax-project` directory that you renamed in step 3 of `Terraform Configuration`.
2.  Execute the command `tf apply`

If you want to ensure that terraform does **exactly** what you saw in the `apply` output, you can optionally request for the `plan` output to be saved to a file to feed to `apply`. This is generally considered best practice in highly fluid environments where rapid change is occurring from multiple sources.

Conclusion[​](#conclusion "Direct link to heading")
---------------------------------------------------

Establishing CI/CD practices using tools such as GitHub and Terraform to manage your infrastructure assets is a great way to ensure base disaster recovery capabilities and to ensure you have a place to embed any ~tweaks you have to make operationally removing the potential to miss them when you have to scale from 1 node to 10. Having an automated pipeline also gives you a place to build a bigger house... what starts as your interest in building and managing a single AVAX node today can quickly change into you building an infrastructure operation for many different chains working with multiple different team members. I hope this may have inspired you to take a leap into automation in this context!

# Latitude (/docs/nodes/on-third-party-services/latitude)

---
title: Latitude
description: Learn how to run an Avalanche node on Latitude.sh.
---

Introduction[​](#introduction "Direct link to heading")
-------------------------------------------------------

This tutorial will guide you through setting up an Avalanche node on [Latitude.sh](https://latitude.sh/). Latitude.sh provides high-performance lighting-fast bare metal servers to ensure that your node is highly secure, available, and accessible.

To get started, you'll need:

- A Latitude.sh account
- A terminal with which to SSH into your Latitude.sh machine

For the instructions on creating an account and server with Latitude.sh, please reference their [GitHub tutorial](https://github.com/NottherealIllest/Latitude.sh-post/blob/main/avalanhe/avax-copy.md) , or visit [this page](https://www.latitude.sh/dashboard/signup) to sign up and create your first project.

This tutorial assumes your local machine has a Unix-style terminal. If you're on Windows, you'll have to adapt some of the commands used here.

Configuring Your Server[​](#configuring-your-server "Direct link to heading")
-----------------------------------------------------------------------------

### Create a Latitude.sh Account[​](#create-a-latitudesh-account "Direct link to heading")

At this point your account has been verified, and you have created a new project and deployed the server according to the instructions linked above.

### Access Your Server & Further Steps[​](#access-your-server--further-steps "Direct link to heading")

All your Latitude.sh credentials are available by clicking the `server` under your project, and can be used to access your Latitude.sh machine from your local machine using a terminal.

<Callout title="Note">
You will need to install the `avalanche node installer script` directly in the server's terminal.
</Callout>

After gaining access, we'll need to set up our Avalanche node. To do this, follow the instructions here to install and run your node [Set Up Avalanche Node With Installer](/docs/nodes/using-install-script/installing-avalanche-go).

Your AvalancheGo node should now be running and in the process of bootstrapping, which can take a few hours. To check if it's done, you can issue an API call using `curl`. The request is:

```bash
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"info.isBootstrapped",
    "params": {
        "chain":"X"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info
```

Once the node is finished bootstrapping, the response will be:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "isBootstrapped": true
  },
  "id": 1
}
```

You can continue on, even if AvalancheGo isn't done bootstrapping. In order to make your node a validator, you'll need its node ID. To get it, run:

```bash
curl -X POST --data '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "info.getNodeID"
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info
```

The response contains the node ID.

```json
{
  "jsonrpc": "2.0",
  "result": { "nodeID": "KhDnAoZDW8iRJ3F26iQgK5xXVFMPcaYeu" },
  "id": 1
}
```

In the above example the node ID is `NodeID-KhDnAoZDW8iRJ3F26iQgK5xXVFMPcaYeu`.

AvalancheGo has other APIs, such as the [Health API](/docs/api-reference/health-api), that may be used to interact with the node. Some APIs are disabled by default. To enable such APIs, modify the ExecStart section of `/etc/systemd/system/avalanchego.service` (created during the installation process) to include flags that enable these endpoints. Don't manually enable any APIs unless you have a reason to.

Exit out of the SSH server by running:

### Upgrading Your Node[​](#upgrading-your-node "Direct link to heading")

AvalancheGo is an ongoing project and there are regular version upgrades. Most upgrades are recommended but not required. Advance notice will be given for upgrades that are not backwards compatible. To update your node to the latest version, SSH into your server using a terminal and run the installer script again.

```bash
./avalanchego-installer.sh
```

Your machine is now running the newest AvalancheGo version. To see the status of the AvalancheGo service, run `sudo systemctl status avalanchego.`

Wrap Up[​](#wrap-up "Direct link to heading")
---------------------------------------------

That's it! You now have an AvalancheGo node running on a Latitude.sh machine. We recommend setting up [node monitoring](/docs/nodes/maintain/monitoring) for your AvalancheGo node.

# Microsoft Azure (/docs/nodes/on-third-party-services/microsoft-azure)

---
title: Microsoft Azure
description: How to run an Avalanche node on Microsoft Azure.
---

<Callout type="warn">
This document was written by a community member, some information may be out of date.
</Callout>

Running a validator and staking with Avalanche provides extremely competitive rewards of between 9.69% and 11.54% depending on the length you stake for. The maximum rate is earned by staking for a year, whilst the lowest rate for 14 days. There is also no slashing, so you don't need to worry about a hardware failure or bug in the client which causes you to lose part or all of your stake. Instead with Avalanche you only need to currently maintain at least 80% uptime to receive rewards. If you fail to meet this requirement you don't get slashed, but you don't receive the rewards. **You also do not need to put your private keys onto a node to begin validating on that node.** Even if someone breaks into your cloud environment and gains access to the node, the worst they can do is turn off the node.

Not only does running a validator node enable you to receive rewards in AVAX, but later you will also be able to validate other Avalanche L1s in the ecosystem as well and receive rewards in the token native to their Avalanche L1s.

Hardware requirements to run a validator are relatively modest: 8 CPU cores, 16 GB of RAM and 1 TB SSD. It also doesn't use enormous amounts of energy. Avalanche's [revolutionary consensus mechanism](/docs/quick-start/avalanche-consensus) is able to scale to millions of validators participating in consensus at once, offering unparalleled decentralisation.

Currently the minimum amount required to stake to become a validator is 2,000 AVAX. Alternatively, validators can also charge a small fee to enable users to delegate their stake with them to help towards running costs.
In this article we will step through the process of configuring a node on Microsoft Azure. This tutorial assumes no prior experience with Microsoft Azure and will go through each step with as few assumptions possible.

At the time of this article, spot pricing for a virtual machine with 2 Cores and 8 GB memory costs as little as 0.01060perhourwhichworksoutatabout0.01060 per hour which works out at about 113.44 a year, **a saving of 83.76%! compared to normal pay as you go prices.** In comparison a virtual machine in AWS with 2 Cores and 4 GB Memory with spot pricing is around $462 a year.

Initial Subscription Configuration[​](#initial-subscription-configuration "Direct link to heading")
---------------------------------------------------------------------------------------------------

### Set up 2 Factor[​](#set-up-2-factor "Direct link to heading")

First you will need a Microsoft Account, if you don't have one already you will see an option to create one at the following link. If you already have one, make sure to set up 2 Factor authentication to secure your node by going to the following link and then selecting "Two-step verification" and following the steps provided.

[https://account.microsoft.com/security](https://account.microsoft.com/security)

![Image for post](/images/azure1.png)

Once two factor has been configured log into the Azure portal by going to [https://portal.azure.com](https://portal.azure.com/) and signing in with your Microsoft account. When you login you won't have a subscription, so we need to create one first. Select "Subscriptions" as highlighted below:

![Image for post](/images/azure2.png)

Then select "+ Add" to add a new subscription

![Image for post](/images/azure3.png)

If you want to use Spot Instance VM Pricing (which will be considerably cheaper) you can't use a Free Trial account (and you will receive an error upon validation), so **make sure to select Pay-As-You-Go.**

![Image for post](/images/azure4.png)

Enter your billing details and confirm identity as part of the sign-up process, when you get to Add technical support select the without support option (unless you want to pay extra for support) and press Next.

![Image for post](/images/azure5.png)

Create a Virtual Machine[​](#create-a-virtual-machine "Direct link to heading")
-------------------------------------------------------------------------------

Now that we have a subscription, we can create the Ubuntu Virtual Machine for our Avalanche Node. Select the Icon in the top left for the Menu and choose "+ Create a resource"

![Image for post](/images/azure6.png)

Select Ubuntu Server 18.04 LTS (this will normally be under the popular section or alternatively search for it in the marketplace)

![Image for post](/images/azure7.png)

This will take you to the Create a virtual machine page as shown below:

![Image for post](/images/azure8.png)

First, enter a virtual machine a name, this can be anything but in my example, I have called it Avalanche (This will also automatically change the resource group name to match)

Then select a region from the drop-down list. Select one of the recommended ones in a region that you prefer as these tend to be the larger ones with most features enabled and cheaper prices. In this example I have selected North Europe.

![Image for post](/images/azure9.png)

You have the option of using spot pricing to save significant amounts on running costs. Spot instances use a supply and demand market price structure. As demand for instances goes up, the price for the spot instance goes up. If there is insufficient capacity, then your VM will be turned off. The chances of this happening are incredibly low though, especially if you select the Capacity only option. Even in the unlikely event it does get turned off temporarily you only need to maintain at least 80% up time to receive the staking rewards and there is no slashing implemented in Avalanche.

Select Yes for Azure Spot instance, select Eviction type to Capacity Only and **make sure to set the eviction policy to Stop / Deallocate. This is very important otherwise the VM will be deleted**

![Image for post](/images/azure10.png)

Choose "Select size" to change the Virtual Machine size, and from the menu select D2s\_v4 under the D-Series v4 selection (This size has 2 Cores, 8 GB Memory and enables Premium SSDs). You can use F2s\_v2 instances instead, with are 2 Cores, 4 GB Memory and enables Premium SSDs) but the spot price actually works out cheaper for the larger VM currently with spot instance prices. You can use [this link](https://azure.microsoft.com/en-us/pricing/details/virtual-machines/linux/) to view the prices across the different regions.

![Image for post](/images/azure11.png)

Once you have selected the size of the Virtual Machine, select "View pricing history and compare prices in nearby regions" to see how the spot price has changed over the last 3 months, and whether it's cheaper to use a nearby region which may have more spare capacity.

![Image for post](/images/azure12.png)

At the time of this article, spot pricing for D2s\_v4 in North Europe costs 0.07975perhour,oraround0.07975 per hour, or around 698.61 a year. With spot pricing, the price falls to 0.01295perhour,whichworksoutatabout0.01295 per hour, which works out at about 113.44 a year, **a saving of 83.76%!**

There are some regions which are even cheaper, East US for example is 0.01060perhouroraround0.01060 per hour or around 92.86 a year!

![Image for post](/images/azure13.png)

Below you can see the price history of the VM over the last 3 months for North Europe and regions nearby.

![Image for post](/images/azure14.png)

### Cheaper Than Amazon AWS[​](#cheaper-than-amazon-aws "Direct link to heading")

As a comparison a c5.large instance costs 0.085USDperhouronAWS.Thistotals 0.085 USD per hour on AWS. This totals ~745 USD per year. Spot instances can save 62%, bringing that total down to $462.

The next step is to change the username for the VM, to align with other Avalanche tutorials change the username to Ubuntu. Otherwise you will need to change several commands later in this article and swap out Ubuntu with your new username.

![Image for post](/images/azure15.png)

### Disks[​](#disks "Direct link to heading")

Select Next: Disks to then configure the disks for the instance. There are 2 choices for disks, either Premium SSD which offer greater performance with a 64 GB disk costs around 10amonth,orthereisthestandardSSDwhichofferslowerperformanceandisaround10 a month, or there is the standard SSD which offers lower performance and is around 5 a month. You also have to pay $0.002 per 10,000 transaction units (reads / writes and deletes) with the Standard SSD, whereas with Premium SSDs everything is included. Personally, I chose the Premium SSD for greater performance, but also because the disks are likely to be heavily used and so may even work out cheaper in the long run.

Select Next: Networking to move onto the network configuration

![Image for post](/images/azure16.png)

### Network Config[​](#network-config "Direct link to heading")

You want to use a Static IP so that the public IP assigned to the node doesn't change in the event it stops. Under Public IP select "Create new"

![Image for post](/images/azure17.png)

Then select "Static" as the Assignment type

![Image for post](/images/azure19.png)

Then we need to configure the network security group to control access inbound to the Avalanche node. Select "Advanced" as the NIC network security group type and select "Create new"

![Image for post](/images/azure20.png)

For security purposes you want to restrict who is able to remotely connect to your node. To do this you will first want to find out what your existing public IP is. This can be done by going to google and searching for "what's my IP"

![Image for post](/images/azure21.png)

It's likely that you have been assigned a dynamic public IP for your home, unless you have specifically requested it, and so your assigned public IP may change in the future. It's still recommended to restrict access to your current IP though, and then in the event your home IP changes and you are no longer able to remotely connect to the VM, you can just update the network security rules with your new public IP so you are able to connect again.

NOTE: If you need to change the network security group rules after deployment if your home IP has changed, search for "avalanche-nsg" and you can modify the rule for SSH and Port 9650 with the new IP. **Port 9651 needs to remain open to everyone** though as that's how it communicates with other Avalanche nodes.

![Image for post](/images/azure22.png)

Now that you have your public IP select the default allow ssh rule on the left under inbound rules to modify it. Change Source from "Any" to "IP Addresses" and then enter in your Public IP address that you found from google in the Source IP address field. Change the Priority towards the bottom to 100 and then press Save.

![Image for post](/images/azure23.png)

Then select "+ Add an inbound rule" to add another rule for RPC access, this should also be restricted to only your IP. Change Source to "IP Addresses" and enter in your public IP returned from google into the Source IP field. This time change the "Destination port ranges" field to 9650 and select "TCP" as the protocol. Change the priority to 110 and give it a name of "Avalanche\_RPC" and press Add.

![Image for post](/images/azure24.png)

Select "+ Add an inbound rule" to add a final rule for the Avalanche Protocol so that other nodes can communicate with your node. This rule needs to be open to everyone so keep "Source" set to "Any." Change the Destination port range to "9651" and change the protocol to "TCP." Enter a priority of 120 and a name of Avalanche\_Protocol and press Add.

![Image for post](/images/azure25.png)

The network security group should look like the below (albeit your public IP address will be different) and press OK.

![Image for post](/images/azure26.png)

Leave the other settings as default and then press "Review + create" to create the Virtual machine.

![Image for post](/images/azure27.png)

First it will perform a validation test. If you receive an error here, make sure you selected Pay-As-You-Go subscription model and you are not using the Free Trial subscription as Spot instances are not available. Verify everything looks correct and press "Create"

![Image for post](/images/azure28.png)

You should then receive a prompt asking you to generate a new key pair to connect your virtual machine. Select "Download private key and create resource" to download the private key to your PC.

![Image for post](/images/azure29.png)

Once your deployment has finished, select "Go to resource"

![Image for post](/images/azure30.png)

Change the Provisioned Disk Size[​](#change-the-provisioned-disk-size "Direct link to heading")
-----------------------------------------------------------------------------------------------

By default, the Ubuntu VM will be provisioned with a 30 GB Premium SSD. You should increase this to 250 GB, to allow for database growth.

![Image for post](/images/azure31.png)

To change the Disk size, the VM needs to be stopped and deallocated. Select "Stop" and wait for the status to show deallocated. Then select "Disks" on the left.

![Image for post](/images/azure32.png)

Select the Disk name that's current provisioned to modify it

![Image for post](/images/azure33.png)

Select "Size + performance" on the left under settings and change the size to 250 GB and press "Resize"

![Image for post](/images/azure34.png)

Doing this now will also extend the partition automatically within Ubuntu. To go back to the virtual machine overview page, select Avalanche in the navigation setting.

![Image for post](/images/azure35.png)

Then start the VM

![Image for post](/images/azure36.png)

Connect to the Avalanche Node[​](#connect-to-the-avalanche-node "Direct link to heading")
-----------------------------------------------------------------------------------------

The following instructions show how to connect to the Virtual Machine from a Windows 10 machine. For instructions on how to connect from a Ubuntu machine see the [AWS tutorial](/docs/nodes/on-third-party-services/amazon-web-services).

On your local PC, create a folder on the root of the C: drive called Avalanche and then move the Avalanche\_key.pem file you downloaded before into the folder. Then right click the file and select Properties. Go to the security tab and select "Advanced" at the bottom

![Image for post](/images/azure37.png)

Select "Disable inheritance" and then "Remove all inherited permissions from this object" to remove all existing permissions on that file.

![Image for post](/images/azure38.png)

Then select "Add" to add a new permission and choose "Select a principal" at the top. From the pop-up box enter in your user account that you use to log into your machine. In this example I log on with a local user called Seq, you may have a Microsoft account that you use to log in, so use whatever account you login to your PC with and press "Check Names" and it should underline it to verify and press OK.

![Image for post](/images/azure39.png)

Then from the permissions section make sure only "Read & Execute" and "Read" are selected and press OK.

![Image for post](/images/azure40.png)

It should look something like the below, except with a different PC name / user account. This just means the key file can't be modified or accessed by any other accounts on this machine for security purposes so they can't access your Avalanche Node.

![Image for post](/images/azure41.png)

### Find your Avalanche Node Public IP[​](#find-your-avalanche-node-public-ip "Direct link to heading")

From the Azure Portal make a note of your static public IP address that has been assigned to your node.

![Image for post](/images/azure42.png)

To log onto the Avalanche node, open command prompt by searching for `cmd` and selecting "Command Prompt" on your Windows 10 machine.

![Image for post](/images/azure43.png)

Then use the following command and replace the EnterYourAzureIPHere with the static IP address shown on the Azure portal.

ssh -i C:\\Avalanche\\Avalanche\_key.pem ubuntu@EnterYourAzureIPHere

for my example its:

ssh -i C:\\Avalanche\\Avalanche\_key.pem

The first time you connect you will receive a prompt asking to continue, enter yes.

![Image for post](/images/azure44.png)

You should now be connected to your Node.

![Image for post](/images/azure45.png)

The following section is taken from Colin's excellent tutorial for [configuring an Avalanche Node on Amazon's AWS](/docs/nodes/on-third-party-services/amazon-web-services).

### Update Linux with Security Patches[​](#update-linux-with-security-patches "Direct link to heading")

Now that we are on our node, it's a good idea to update it to the latest packages. To do this, run the following commands, one-at-a-time, in order:

```
sudo apt update
sudo apt upgrade -y
sudo reboot
```

![Image for post](/images/azure46.png)

This will make our instance up to date with the latest security patches for our operating system. This will also reboot the node. We'll give the node a minute or two to boot back up, then log in again, same as before.

### Set up the Avalanche Node[​](#set-up-the-avalanche-node "Direct link to heading")

Now we'll need to set up our Avalanche node. To do this, follow the [Set Up Avalanche Node With Installer](/docs/nodes/using-install-script/installing-avalanche-go) tutorial which automates the installation process. You will need the "IPv4 Public IP" copied from the Azure Portal we set up earlier.

Once the installation is complete, our node should now be bootstrapping! We can run the following command to take a peek at the latest status of the AvalancheGo node:

```
sudo systemctl status avalanchego
```

To check the status of the bootstrap, we'll need to make a request to the local RPC using `curl`. This request is as follows:

```
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"info.isBootstrapped",
    "params": {
        "chain":"X"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info
```

The node can take some time (upward of an hour at this moment writing) to bootstrap. Bootstrapping means that the node downloads and verifies the history of the chains. Give this some time. Once the node is finished bootstrapping, the response will be:

```
{
    "jsonrpc": "2.0",
    "result": {
        "isBootstrapped": true
    },
    "id": 1
}
```

We can always use `sudo systemctl status avalanchego` to peek at the latest status of our service as before, as well.

### Get Your NodeID[​](#get-your-nodeid "Direct link to heading")

We absolutely must get our NodeID if we plan to do any validating on this node. This is retrieved from the RPC as well. We call the following curl command to get our NodeID.

```
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"info.getNodeID"
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info
```

If all is well, the response should look something like:

```
{"jsonrpc":"2.0","result":{"nodeID":"NodeID-Lve2PzuCvXZrqn8Stqwy9vWZux6VyGUCR"},"id":1}
```

That portion that says, "NodeID-Lve2PzuCvXZrqn8Stqwy9vWZux6VyGUCR" is our NodeID, the entire thing. Copy that and keep that in our notes. There's nothing confidential or secure about this value, but it's an absolute must for when we submit this node to be a validator.

### Backup Your Staking Keys[​](#backup-your-staking-keys "Direct link to heading")

The last thing that should be done is backing up our staking keys in the untimely event that our instance is corrupted or terminated. It's just good practice for us to keep these keys. To back them up, we use the following command:

```
scp -i C:\Avalanche\avalanche_key.pem -r ubuntu@EnterYourAzureIPHere:/home/ubuntu/.avalanchego/staking C:\Avalanche
```

As before, we'll need to replace "EnterYourAzureIPHere" with the appropriate value that we retrieved. This backs up our staking key and staking certificate into the C:\\Avalanche folder we created before.

![Image for post](/images/azure47.png)

# Avalanche L1 Nodes (/docs/nodes/run-a-node/avalanche-l1-nodes)

---
title: Avalanche L1 Nodes
description: Learn how to run an Avalanche node that tracks an Avalanche L1.
---

This article describes how to run a node that tracks an Avalanche L1. It requires building AvalancheGo, adding Virtual Machine binaries as plugins to your local data directory, and running AvalancheGo to track these binaries.

This tutorial specifically covers tracking an Avalanche L1 built with Avalanche's [Subnet-EVM](https://github.com/ava-labs/subnet-evm), the default [Virtual Machine](/docs/quick-start/virtual-machines) run by Avalanche L1s on Avalanche.

## Build AvalancheGo

It is recommended that you must complete [this comprehensive guide](/docs/nodes/run-a-node/from-source) which demonstrates how to build and run a basic Avalanche node from source.

## Build Avalanche L1 Binaries

After building AvalancheGo successfully,

<Steps>
<Step>
Clone [Subnet-EVM](https://github.com/ava-labs/subnet-evm):

```bash
cd $GOPATH/src/github.com/ava-labs
git clone https://github.com/ava-labs/subnet-evm.git
```
</Step>

<Step>
In the Subnet-EVM directory, run the build script, and save it in the `plugins` folder of your `.avalanchego` data directory. Name the plugin after the `VMID` of the Avalanche L1 you wish to track. The `VMID` of the WAGMI Avalanche L1 is the value beginning with **srEX...**

```bash
cd $GOPATH/src/github.com/ava-labs/subnet-evm
./scripts/build.sh ~/.avalanchego/plugins/srEXiWaHuhNyGwPUi444Tu47ZEDwxTWrbQiuD7FmgSAQ6X7Dy
```

<Accordions>
<Accordion title="Where can I find Avalanche L1 parameters like VMID?">
VMID, Avalanche L1 ID (SubnetID), ChainID, and all other parameters can be found in the "Chain Info" section of the Avalanche L1 Explorer.

- [Avalanche Mainnet](https://subnets.avax.network/c-chain)
- [Fuji Testnet](https://subnets-test.avax.network/c-chain)
</Accordion>
</Accordions>
</Step>

<Step>
Create a file named `config.json` and add a `track-subnets` field that is populated with the `SubnetID` you wish to track. The `SubnetID` of the WAGMI Avalanche L1 is the value beginning with **28nr...**

```bash
cd ~/.avalanchego
echo '{"track-subnets": "28nrH5T2BMvNrWecFcV3mfccjs6axM1TVyqe79MCv2Mhs8kxiY"}' > config.json
```
</Step>
</Steps>

## Run the Node

Run AvalancheGo with the `—config-file` flag to start your node and ensure it tracks the Avalanche L1s included in the configuration file.

```bash
cd $GOPATH/src/github.com/ava-labs/avalanchego
./build/avalanchego --config-file ~/.avalanchego/config.json --network-id=fuji
```

<Callout title="Note">
Note: The above command includes the `--network-id=fuji` command because the WAGMI Avalanche L1 is deployed on Fuji Testnet.
</Callout>

<Accordions>
<Accordion title="Run L1 Node Without The Config File">
If you would prefer to track Avalanche L1s using a command line flag, you can instead use the `--track-subnets` flag. For example:

```bash
./build/avalanchego --track-subnets 28nrH5T2BMvNrWecFcV3mfccjs6axM1TVyqe79MCv2Mhs8kxiY --network-id=fuji
```
</Accordion>
</Accordions>

You should now see terminal filled with logs and information to suggest the node is properly running and has began bootstrapping to the network.

## Bootstrapping and RPC Details

It may take a few hours for the node to fully [bootstrap](/docs/nodes/run-a-node/from-source#bootstrapping) to the Avalanche Primary Network and tracked Avalanche L1s.

When finished bootstrapping, the endpoint will be:

```bash
localhost:9650/ext/bc/<BlockchainID>/rpc
```

if run locally, or:

```bash
XXX.XX.XX.XXX:9650/ext/bc/<BlockchainID>/rpc
```

if run on a cloud provider. The “X”s should be replaced with the public IP of your EC2 instance.

For more information on the requests available at these endpoints, please see the [Subnet-EVM API Reference](/docs/api-reference/subnet-evm-api) documentation.

Because each node is also tracking the Primary Network, those [RPC endpoints](/docs/nodes/run-a-node/from-source#rpc) are available as well.


# Common Errors (/docs/nodes/run-a-node/common-errors)

---
title: Common Errors
description: Common errors while running a node and their solutions.
---

If you experience any issues building your node, here are some common errors and possible solutions.

### Failed to Connect to Bootstrap Nodes[​](#failed-to-connect-to-bootstrap-nodes "Direct link to heading")

Error: `WARN node/node.go:291 failed to connect to bootstrap nodes`

This error can occur when the node doesn't have access to the Internet or if the NodeID is already being used by a different node in the network. This can occur when an old instance is running and not terminated.

### Cannot Query Unfinalized Data[​](#cannot-query-unfinalized-data "Direct link to heading")

Error: `err="cannot query unfinalized data"`

There may be a number of reasons for this issue, but it is likely that the node is not connected properly to other validators, which is usually caused by networking misconfiguration (wrong public IP, closed p2p port 9651).

# Using Source Code (/docs/nodes/run-a-node/from-source)

---
title: Using Source Code
description: Learn how to run an Avalanche node from AvalancheGo Source code.
---

The following steps walk through downloading the AvalancheGo source code and locally building the binary program. If you would like to run your node using a pre-built binary, follow [this](/docs/nodes/run-a-node/using-binary) guide.

## Install Dependencies

- Install [gcc](https://gcc.gnu.org/)
- Install [go](https://go.dev/doc/install)

## Build the Node Binary

<Steps>
<Step>Set the `$GOPATH`. You can follow [this](https://github.com/golang/go/wiki/SettingGOPATH) guide.</Step>
 
<Step>
Create a directory in your `$GOPATH`:

```bash
mkdir -p $GOPATH/src/github.com/ava-labs
```
</Step>

<Step>
In the `$GOPATH`, clone [AvalancheGo](https://github.com/ava-labs/avalanchego), the consensus engine and node implementation that is the core of the Avalanche Network.

```bash
cd $GOPATH/src/github.com/ava-labs
git clone https://github.com/ava-labs/avalanchego.git
```
</Step>

<Step>
From the `avalanchego` directory, run the build script:

```bash
cd $GOPATH/src/github.com/ava-labs/avalanchego
./scripts/build.sh
```
</Step>
</Steps>

## Start the Node

<Callout title="Note">
To be able to make API calls to your node from other machines, include the argument `--http-host=` when starting the node.
</Callout>

For running a node on the Avalanche Mainnet:

```bash
cd $GOPATH/src/github.com/ava-labs/avalanchego
./build/avalanchego
```

For running a node on the Fuji Testnet:

```bash
cd $GOPATH/src/github.com/ava-labs/avalanchego
./build/avalanchego --network-id=fuji
```

<Callout title="Note">
To kill the node, press `Ctrl + C`.
</Callout>

## Bootstrapping

A new node needs to catch up to the latest network state before it can participate in consensus and serve API calls. This process (called bootstrapping) currently takes several days for a new node connected to Mainnet, and a day or so for a new node connected to Fuji Testnet. When a given chain is done bootstrapping, it will print logs like this:

```bash
[09-09|17:01:45.295] INFO <C Chain> snowman/transitive.go:392 consensus starting {"lastAcceptedBlock": "2qaFwDJtmCCbMKP4jRpJwH8EFws82Q2yC1HhWgAiy3tGrpGFeb"}
[09-09|17:01:46.199] INFO <P Chain> snowman/transitive.go:392 consensus starting {"lastAcceptedBlock": "2ofmPJuWZbdroCPEMv6aHGvZ45oa8SBp2reEm9gNxvFjnfSGFP"}
[09-09|17:01:51.628] INFO <X Chain> snowman/transitive.go:334 consensus starting {"lenFrontier": 1}
```

### Check Bootstrapping Progress[​](#check-bootstrapping-progress "Direct link to heading")

To check if a given chain is done bootstrapping, in another terminal window call [`info.isBootstrapped`](/docs/api-reference/info-api#infoisbootstrapped) by copying and pasting the following command:

```bash
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"info.isBootstrapped",
    "params": {
        "chain":"X"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info
```

If this returns `true`, the chain is bootstrapped; otherwise, it returns `false`. If you make other API calls to a chain that is not done bootstrapping, it will return `API call rejected because chain is not done bootstrapping`. If you are still experiencing issues please contact us on [Discord.](https://chat.avalabs.org/)

<Callout title="Note">
The 3 chains will bootstrap in the following order: P-chain, X-chain, C-chain.
</Callout>

Learn more about bootstrapping [here](/docs/nodes/maintain/bootstrapping).

## RPC

When finished bootstrapping, the X, P, and C-Chain RPC endpoints will be:

```bash
localhost:9650/ext/bc/P
localhost:9650/ext/bc/X
localhost:9650/ext/bc/C/rpc
```

if run locally, or

```bash
XXX.XX.XX.XXX:9650/ext/bc/P
XXX.XX.XX.XXX:9650/ext/bc/X
XXX.XX.XX.XXX:9650/ext/bc/C/rpc
```

if run on a cloud provider. The “XXX.XX.XX.XXX" should be replaced with the public IP of your EC2 instance.

For more information on the requests available at these endpoints, please see the [AvalancheGo API Reference](/docs/api-reference/p-chain/api) documentation.

## Going Further

Your Avalanche node will perform consensus on its own, but it is not yet a validator on the network. This means that the rest of the network will not query your node when sampling the network during consensus. If you want to add your node as a validator, check out [Add a Validator](/docs/nodes/validate/node-validator) to take it a step further.

Also check out the [Maintain](/docs/nodes/maintain/bootstrapping) section to learn about how to maintain and customize your node to fit your needs.

To track an Avalanche L1 with your node, head to the [Avalanche L1 Node](/docs/nodes/run-a-node/avalanche-l1-nodes) tutorial.

# Using Pre-Built Binary (/docs/nodes/run-a-node/using-binary)

---
title: Using Pre-Built Binary
description: Learn how to run an Avalanche node from a pre-built binary program.
---

## Download Binary

To download a pre-built binary instead of building from source code, go to the official [AvalancheGo releases page](https://github.com/ava-labs/avalanchego/releases), and select the desired version.

Scroll down to the **Assets** section, and select the appropriate file. You can follow below rules to find out the right binary.

### For MacOS

Download the `avalanchego-macos-<VERSION>.zip` file and unzip using the below command:

```bash
unzip avalanchego-macos-<VERSION>.zip
```

The resulting folder, `avalanchego-<VERSION>`, contains the binaries.

### Linux (PCs or Cloud Providers)

Download the `avalanchego-linux-amd64-<VERSION>.tar.gz` file and unzip using the below command:

```bash
tar -xvf avalanchego-linux-amd64-<VERSION>.tar.gz
```

The resulting folder, `avalanchego-<VERSION>-linux`, contains the binaries.

### Linux (Arm64)

Download the `avalanchego-linux-arm64-<VERSION>.tar.gz` file and unzip using the below command:

```bash
tar -xvf avalanchego-linux-arm64-<VERSION>.tar.gz
```

The resulting folder, `avalanchego-<VERSION>-linux`, contains the binaries.

## Start the Node

<Callout title="Note">
To be able to make API calls to your node from other machines, include the argument `--http-host=` when starting the node.
</Callout>

### MacOS

For running a node on the Avalanche Mainnet:

```bash
./avalanchego-<VERSION>/build/avalanchego
```

For running a node on the Fuji Testnet:

```bash
./avalanchego-<VERSION>/build/avalanchego --network-id=fuji
```

### Linux

For running a node on the Avalanche Mainnet:

```bash
./avalanchego-<VERSION>-linux/avalanchego
```

For running a node on the Fuji Testnet:

```bash
./avalanchego-<VERSION>-linux/avalanchego --network-id=fuji
```

## Bootstrapping

A new node needs to catch up to the latest network state before it can participate in consensus and serve API calls. This process (called bootstrapping) currently takes several days for a new node connected to Mainnet, and a day or so for a new node connected to Fuji Testnet. When a given chain is done bootstrapping, it will print logs like this:

```bash
[09-09|17:01:45.295] INFO <C Chain> snowman/transitive.go:392 consensus starting {"lastAcceptedBlock": "2qaFwDJtmCCbMKP4jRpJwH8EFws82Q2yC1HhWgAiy3tGrpGFeb"}
[09-09|17:01:46.199] INFO <P Chain> snowman/transitive.go:392 consensus starting {"lastAcceptedBlock": "2ofmPJuWZbdroCPEMv6aHGvZ45oa8SBp2reEm9gNxvFjnfSGFP"}
[09-09|17:01:51.628] INFO <X Chain> snowman/transitive.go:334 consensus starting {"lenFrontier": 1}
```

### Check Bootstrapping Progress[​](#check-bootstrapping-progress "Direct link to heading")

To check if a given chain is done bootstrapping, in another terminal window call [`info.isBootstrapped`](/docs/api-reference/info-api#infoisbootstrapped) by copying and pasting the following command:

```bash
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"info.isBootstrapped",
    "params": {
        "chain":"X"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info
```

If this returns `true`, the chain is bootstrapped; otherwise, it returns `false`. If you make other API calls to a chain that is not done bootstrapping, it will return `API call rejected because chain is not done bootstrapping`. If you are still experiencing issues please contact us on [Discord.](https://chat.avalabs.org/)

<Callout title="Note">
The 3 chains will bootstrap in the following order: P-chain, X-chain, C-chain.
</Callout>

Learn more about bootstrapping [here](/docs/nodes/maintain/bootstrapping).

## RPC

When finished bootstrapping, the X, P, and C-Chain RPC endpoints will be:

```bash
localhost:9650/ext/bc/P
localhost:9650/ext/bc/X
localhost:9650/ext/bc/C/rpc
```

if run locally, or

```bash
XXX.XX.XX.XXX:9650/ext/bc/P
XXX.XX.XX.XXX:9650/ext/bc/X
XXX.XX.XX.XXX:9650/ext/bc/C/rpc
```

if run on a cloud provider. The “XXX.XX.XX.XXX" should be replaced with the public IP of your EC2 instance.

For more information on the requests available at these endpoints, please see the [AvalancheGo API Reference](/docs/api-reference/p-chain/api) documentation.

## Going Further

Your Avalanche node will perform consensus on its own, but it is not yet a validator on the network. This means that the rest of the network will not query your node when sampling the network during consensus. If you want to add your node as a validator, check out [Add a Validator](/docs/nodes/validate/node-validator) to take it a step further.

Also check out the [Maintain](/docs/nodes/maintain/bootstrapping) section to learn about how to maintain and customize your node to fit your needs.

To track an Avalanche L1 with your node, head to the [Avalanche L1 Node](/docs/nodes/run-a-node/avalanche-l1-nodes) tutorial.

# Using Docker (/docs/nodes/run-a-node/using-docker)

---
title: Using Docker
description: Learn how to run an Avalanche node using Docker.
---

## Prerequisites

Before beginning, you must ensure that:
- Docker is installed on your system
- You need to clone the [AvalancheGo repository](https://github.com/ava-labs/avalanchego)
- You need to install [GCC](https://gcc.gnu.org/) and [Go](https://go.dev/doc/install)
- Docker daemon is running on your machine

You can verify your Docker installation by running:
```bash
docker --version
```

## Building the Docker Image

To build the Docker image for the latest `avalanchego` branch:

1. Navigate to the project directory
2. Execute the build script:
   ```bash
   ./scripts/build_image.sh
   ```

This script will create a Docker image containing the latest version of AvalancheGo.

## Verifying the Build

After the build completes, verify the image was created successfully:

```bash
docker image ls
```

You should see an image with:
- Repository: `avaplatform/avalanchego`
- Tag: `xxxxxxxx` (where `xxxxxxxx` is the shortened commit hash of the source code used for the build)

## Running AvalancheGo Node

To start an AvalancheGo node, run the following command:

```bash
docker run -ti -p 9650:9650 -p 9651:9651 avaplatform/avalanchego:xxxxxxxx /avalanchego/build/avalanchego
```

This command:
- Creates an interactive container (`-ti`)
- Maps the following ports:
  - `9650`: HTTP API port
  - `9651`: P2P networking port
- Uses the built AvalancheGo image
- Executes the AvalancheGo binary inside the container

## Port Configuration

The default ports used by AvalancheGo are:
- `9650`: HTTP API
- `9651`: P2P networking

Ensure these ports are available on your host machine and not blocked by firewalls.


# Installing AvalancheGo (/docs/nodes/using-install-script/installing-avalanche-go)

---
title: Installing AvalancheGo
description: Learn how to install AvalancheGo on your system.
---

## Running the Script

So, now that you prepared your system and have the info ready, let's get to it.

To download and run the script, enter the following in the terminal:

```bash
wget -nd -m https://raw.githubusercontent.com/ava-labs/avalanche-docs/master/scripts/avalanchego-installer.sh;\
chmod 755 avalanchego-installer.sh;\
./avalanchego-installer.sh
```

And we're off! The output should look something like this:

<Accordions>
<Accordion title="Click to see the Terminal output">
```bash
AvalancheGo installer
---------------------
Preparing environment...
Found arm64 architecture...
Looking for the latest arm64 build...
Will attempt to download:
 https://github.com/ava-labs/avalanchego/releases/download/v1.1.1/avalanchego-linux-arm64-v1.1.1.tar.gz
avalanchego-linux-arm64-v1.1.1.tar.gz 100%[=========================================================================>]  29.83M  75.8MB/s    in 0.4s
2020-12-28 14:57:47 URL:https://github-production-release-asset-2e65be.s3.amazonaws.com/246387644/f4d27b00-4161-11eb-8fb2-156a992fd2c8?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAIWNJYAX4CSVEH53A%2F20201228%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20201228T145747Z&X-Amz-Expires=300&X-Amz-Signature=ea838877f39ae940a37a076137c4c2689494c7e683cb95a5a4714c062e6ba018&X-Amz-SignedHeaders=host&actor_id=0&key_id=0&repo_id=246387644&response-content-disposition=attachment%3B%20filename%3Davalanchego-linux-arm64-v1.1.1.tar.gz&response-content-type=application%2Foctet-stream [31283052/31283052] -> "avalanchego-linux-arm64-v1.1.1.tar.gz" [1]
Unpacking node files...
avalanchego-v1.1.1/plugins/
avalanchego-v1.1.1/plugins/evm
avalanchego-v1.1.1/avalanchego
Node files unpacked into /home/ubuntu/avalanche-node
```
</Accordion>
</Accordions>

And then the script will prompt you for information about the network environment:

```bash
To complete the setup some networking information is needed.
Where is the node installed:
1) residential network (dynamic IP)
2) cloud provider (static IP)
Enter your connection type [1,2]:
```

Enter `1` if you have dynamic IP, and `2` if you have a static IP. If you are on a static IP, it will try to auto-detect the IP and ask for confirmation.

```bash
Detected '3.15.152.14' as your public IP. Is this correct? [y,n]:
```

Confirm with `y`, or `n` if the detected IP is wrong (or empty), and then enter the correct IP at the next prompt.

Next, you have to set up RPC port access for your node. Those are used to query the node for its internal state, to send commands to the node, or to interact with the platform and its chains (sending transactions, for example). You will be prompted:

```bash
RPC port should be public (this is a public API node) or private (this is a validator)? [public, private]:
```

- `private`: this setting only allows RPC requests from the node machine itself.
- `public`: this setting exposes the RPC port to all network interfaces.

As this is a sensitive setting you will be asked to confirm if choosing `public`. Please read the following note carefully:

<Callout title="Note">
If you choose to allow RPC requests on any network interface you will need to set up a firewall to only let through RPC requests from known IP addresses, otherwise your node will be accessible to anyone and might be overwhelmed by RPC calls from malicious actors! If you do not plan to use your node to send RPC calls remotely, enter `private`.
</Callout>

The script will then prompt you to choose whether to enable state sync setting or not:

```bash
Do you want state sync bootstrapping to be turned on or off? [on, off]:
```

Turning state sync on will greatly increase the speed of bootstrapping, but will sync only the current network state. If you intend to use your node for accessing historical data (archival node) you should select `off`. Otherwise, select `on`. Validators can be bootstrapped with state sync turned on.

The script will then continue with system service creation and finish with starting the service.

<Accordions>
<Accordion title="Click to see the final output">
```bash
Created symlink /etc/systemd/system/multi-user.target.wants/avalanchego.service → /etc/systemd/system/avalanchego.service.

Done!

Your node should now be bootstrapping.
Node configuration file is /home/ubuntu/.avalanchego/configs/node.json
C-Chain configuration file is /home/ubuntu/.avalanchego/configs/chains/C/config.json
Plugin directory, for storing subnet VM binaries, is /home/ubuntu/.avalanchego/plugins
To check that the service is running use the following command (q to exit):
sudo systemctl status avalanchego
To follow the log use (ctrl-c to stop):
sudo journalctl -u avalanchego -f

Reach us over on https://discord.gg/avax if you're having problems.
```
</Accordion>
</Accordions>

The script is finished, and you should see the system prompt again.

## Post Installation

AvalancheGo should be running in the background as a service. You can check that it's running with:

```bash
sudo systemctl status avalanchego
```

Below is an example of what the node's latest logs should look like:

<Accordions>
<Accordion title="Click to expand and see the Logs">
```bash
● avalanchego.service - AvalancheGo systemd service
Loaded: loaded (/etc/systemd/system/avalanchego.service; enabled; vendor preset: enabled)
Active: active (running) since Tue 2021-01-05 10:38:21 UTC; 51s ago
Main PID: 2142 (avalanchego)
Tasks: 8 (limit: 4495)
Memory: 223.0M
CGroup: /system.slice/avalanchego.service
└─2142 /home/ubuntu/avalanche-node/avalanchego --public-ip-resolution-service=opendns --http-host=

Jan 05 10:38:45 ip-172-31-30-64 avalanchego[2142]: INFO [01-05|10:38:45] <P Chain> avalanchego/vms/platformvm/vm.go#322: initializing last accepted block as 2FUFPVPxbTpKNn39moGSzsmGroYES4NZRdw3mJgNvMkMiMHJ9e
Jan 05 10:38:45 ip-172-31-30-64 avalanchego[2142]: INFO [01-05|10:38:45] <P Chain> avalanchego/snow/engine/snowman/transitive.go#58: initializing consensus engine
Jan 05 10:38:45 ip-172-31-30-64 avalanchego[2142]: INFO [01-05|10:38:45] avalanchego/api/server.go#143: adding route /ext/bc/11111111111111111111111111111111LpoYY
Jan 05 10:38:45 ip-172-31-30-64 avalanchego[2142]: INFO [01-05|10:38:45] avalanchego/api/server.go#88: HTTP API server listening on ":9650"
Jan 05 10:38:58 ip-172-31-30-64 avalanchego[2142]: INFO [01-05|10:38:58] <P Chain> avalanchego/snow/engine/common/bootstrapper.go#185: Bootstrapping started syncing with 1 vertices in the accepted frontier
Jan 05 10:39:02 ip-172-31-30-64 avalanchego[2142]: INFO [01-05|10:39:02] <P Chain> avalanchego/snow/engine/snowman/bootstrap/bootstrapper.go#210: fetched 2500 blocks
Jan 05 10:39:04 ip-172-31-30-64 avalanchego[2142]: INFO [01-05|10:39:04] <P Chain> avalanchego/snow/engine/snowman/bootstrap/bootstrapper.go#210: fetched 5000 blocks
Jan 05 10:39:06 ip-172-31-30-64 avalanchego[2142]: INFO [01-05|10:39:06] <P Chain> avalanchego/snow/engine/snowman/bootstrap/bootstrapper.go#210: fetched 7500 blocks
Jan 05 10:39:09 ip-172-31-30-64 avalanchego[2142]: INFO [01-05|10:39:09] <P Chain> avalanchego/snow/engine/snowman/bootstrap/bootstrapper.go#210: fetched 10000 blocks
Jan 05 10:39:11 ip-172-31-30-64 avalanchego[2142]: INFO [01-05|10:39:11] <P Chain> avalanchego/snow/engine/snowman/bootstrap/bootstrapper.go#210: fetched 12500 blocks
```
</Accordion>
</Accordions>

Note the `active (running)` which indicates the service is running OK. You may need to press `q` to return to the command prompt.

To find out your NodeID, which is used to identify your node to the network, run the following command:

```bash
sudo journalctl -u avalanchego | grep "NodeID"
```

It will produce output like:

```bash
Jan 05 10:38:38 ip-172-31-30-64 avalanchego[2142]: INFO [01-05|10:38:38] avalanchego/node/node.go#428: Set node's ID to 6seStrauyCnVV7NEVwRbfaT9B6EnXEzfY
```

Prepend `NodeID-` to the value to get, for example, `NodeID-6seStrauyCnVV7NEVwRbfaT9B6EnXEzfY`. Store that; it will be needed for staking or looking up your node.

Your node should be in the process of bootstrapping now. You can monitor the progress by issuing the following command:

```bash
sudo journalctl -u avalanchego -f
```

Press `ctrl+C` when you wish to stop reading node output.

# Managing AvalancheGo (/docs/nodes/using-install-script/managing-avalanche-go)

---
title: Managing AvalancheGo
description: Learn how to start, stop and upgrade your AvalancheGo node
---

## Stop Your Node

To stop AvalancheGo, run:

```bash
sudo systemctl stop avalanchego
```

## Start Your Node

To start your node again, run:

```bash
sudo systemctl start avalanchego
```

## Upgrade Your Node

AvalancheGo is an ongoing project and there are regular version upgrades. Most upgrades are recommended but not required. Advance notice will be given for upgrades that are not backwards compatible. When a new version of the node is released, you will notice log lines like:

```bash
Jan 08 10:26:45 ip-172-31-16-229 avalanchego[6335]: INFO [01-08|10:26:45] avalanchego/network/peer.go#526: beacon 9CkG9MBNavnw7EVSRsuFr7ws9gascDQy3 attempting to connect with newer version avalanche/1.1.1. You may want to update your client
```

It is recommended to always upgrade to the latest version, because new versions bring bug fixes, new features and upgrades.

To upgrade your node, just run the installer script again:

```bash
./avalanchego-installer.sh
```

It will detect that you already have AvalancheGo installed:

```bash
AvalancheGo installer
---------------------
Preparing environment...
Found 64bit Intel/AMD architecture...
Found AvalancheGo systemd service already installed, switching to upgrade mode.
Stopping service...
```

It will then upgrade your node to the latest version, and after it's done, start the node back up, and print out the information about the latest version:

```bash
Node upgraded, starting service...
New node version:
avalanche/1.1.1 [network=mainnet, database=v1.0.0, commit=f76f1fd5f99736cf468413bbac158d6626f712d2]
Done!
```


# Node Config and Maintenance (/docs/nodes/using-install-script/node-config-maintenance)

---
title: Node Config and Maintenance
description: Advanced options for configuring and maintaining your AvalancheGo node.
---

## Advanced Node Configuration

Without any additional arguments, the script installs the node in a most common configuration. But the script also enables various advanced options to be configured, via the command line prompts. Following is a list of advanced options and their usage:

- `admin` - [Admin API](/docs/api-reference/admin-api) will be enabled
- `archival` - disables database pruning and preserves the complete transaction history
- `state-sync` - if `on` state-sync for the C-Chain is used, if `off` it will use regular transaction replay to bootstrap; state-sync is much faster, but has no historical data
- `db-dir` - use to provide the full path to the location where the database will be stored
- `fuji` - node will connect to Fuji testnet instead of the Mainnet
- `index` - [Index API](/docs/api-reference/index-api) will be enabled
- `ip` - use `dynamic`, `static` arguments, of enter a desired IP directly to be used as the public IP node will advertise to the network
- `rpc` - use `any` or `local` argument to select any or local network interface to be used to listen for RPC calls
- `version` - install a specific node version, instead of the latest. See [here](#using-a-previous-version) for usage.

<Callout title="Note">
Configuring the `index` and `archival` options on an existing node will require a fresh bootstrap to recreate the database.
</Callout>

Complete script usage can be displayed by entering:

```bash
./avalanchego-installer.sh --help
```

### Unattended Installation[​](#unattended-installation "Direct link to heading")

If you want to use the script in an automated environment where you cannot enter the data at the prompts you must provide at least the `rpc` and `ip` options. For example:

```bash
./avalanchego-installer.sh --ip 1.2.3.4 --rpc local
```

### Usage Examples[​](#usage-examples "Direct link to heading")

- To run a Fuji node with indexing enabled and autodetected static IP:        
    ```bash
    ./avalanchego-installer.sh --fuji --ip static --index
    ```   
- To run an archival Mainnet node with dynamic IP and database located at `/home/node/db`:      
    ```bash
    ./avalanchego-installer.sh --archival --ip dynamic --db-dir /home/node/db
    ```  
- To use C-Chain state-sync to quickly bootstrap a Mainnet node, with dynamic IP and local RPC only:       
    ```bash
    ./avalanchego-installer.sh --state-sync on --ip dynamic --rpc local
    ```   
- To reinstall the node using node version 1.7.10 and use specific IP and local RPC only:     
    ```bash
    ./avalanchego-installer.sh --reinstall --ip 1.2.3.4 --version v1.7.10 --rpc local
    ```

Node Configuration[​](#node-configuration "Direct link to heading")
-------------------------------------------------------------------

The file that configures node operation is `~/.avalanchego/configs/node.json`. You can edit it to add or change configuration options. The documentation of configuration options can be found [here](/docs/nodes/configure/configs-flags). Configuration may look like this:

```json
{
  "public-ip-resolution-service": "opendns",
  "http-host": ""
}
```

Note that the configuration file needs to be a properly formatted `JSON` file, so switches should formatted differently than they would be for the command line. Therefore, don't enter options like `--public-ip-resolution-service=opendns` as shown in the example above.

The script also creates an empty C-Chain config file, located at `~/.avalanchego/configs/chains/C/config.json`. By editing that file, you can configure the C-Chain, as described in detail [here](/docs/nodes/configure/configs-flags).

Using a Previous Version[​](#using-a-previous-version "Direct link to heading")
-------------------------------------------------------------------------------

The installer script can also be used to install a version of AvalancheGo other than the latest version.

To see a list of available versions for installation, run:

```bash
./avalanchego-installer.sh --list
```

It will print out a list, something like:

```bash
AvalancheGo installer
---------------------
Available versions:
v1.3.2
v1.3.1
v1.3.0
v1.2.4-arm-fix
v1.2.4
v1.2.3-signed
v1.2.3
v1.2.2
v1.2.1
v1.2.0
```

To install a specific version, run the script with `--version` followed by the tag of the version. For example:

```bash
./avalanchego-installer.sh --version v1.3.1
```

<Callout type="warn">
Note that not all AvalancheGo versions are compatible. You should generally run the latest version. Running a version other than latest may lead to your node not working properly and, for validators, not receiving a staking reward.
</Callout>

Thanks to community member [Jean Zundel](https://github.com/jzu) for the inspiration and help implementing support for installing non-latest node versions.

Reinstall and Script Update[​](#reinstall-and-script-update "Direct link to heading")
-------------------------------------------------------------------------------------

The installer script gets updated from time to time, with new features and capabilities added. To take advantage of new features or to recover from modifications that made the node fail, you may want to reinstall the node. To do that, fetch the latest version of the script from the web with:

```bash
wget -nd -m https://raw.githubusercontent.com/ava-labs/builders-hub/master/scripts/avalanchego-installer.sh
```

After the script has updated, run it again with the `--reinstall` config flag:

```bash
./avalanchego-installer.sh --reinstall
```

This will delete the existing service file, and run the installer from scratch, like it was started for the first time. Note that the database and NodeID will be left intact.

Removing the Node Installation[​](#removing-the-node-installation "Direct link to heading")
-------------------------------------------------------------------------------------------

If you want to remove the node installation from the machine, you can run the script with the `--remove` option, like this:

```bash
./avalanchego-installer.sh --remove
```

This will remove the service, service definition file and node binaries. It will not remove the working directory, node ID definition or the node database. To remove those as well, you can type:


<Callout type="warn">
Please note that this is irreversible and the database and node ID will be deleted!
</Callout>

What Next?[​](#what-next "Direct link to heading")
--------------------------------------------------

That's it, you're running an AvalancheGo node! Congratulations! Let us know you did it on our [X](https://x.com/avax), [Telegram](https://t.me/avalancheavax) or [Reddit](https://www.reddit.com/r/Avax/)!

If you're on a residential network (dynamic IP), don't forget to set up port forwarding. If you're on a cloud service provider, you're good to go.

Now you can [interact with your node](/docs/api-reference/standards/guides/issuing-api-calls), [stake your tokens](/docs/nodes/validate/what-is-staking), or level up your installation by setting up [node monitoring](/docs/nodes/maintain/monitoring) to get a better insight into what your node is doing. Also, you might want to use our [Postman Collection](/docs/tooling/avalanche-postman/add-postman-collection) to more easily issue commands to your node.

Finally, if you haven't already, it is a good idea to [back up](/docs/nodes/maintain/backup-restore) important files in case you ever need to restore your node to a different machine.

If you have any questions, or need help, feel free to contact us on our [Discord](https://chat.avalabs.org/) server.

# Preparing Your Environment (/docs/nodes/using-install-script/preparing-environment)

---
title: Preparing Your Environment
description: Learn how to prepare your environment before using install script.
---

We have a shell (bash) script that installs AvalancheGo on your computer. This script sets up full, running node in a matter of minutes with minimal user input required. Script can also be used for unattended, automated installs.

This install script assumes:

- AvalancheGo is not running and not already installed as a service
- User running the script has superuser privileges (can run `sudo`)

Environment Considerations[​](#environment-considerations "Direct link to heading")
-----------------------------------------------------------------------------------

If you run a different flavor of Linux, the script might not work as intended. It assumes `systemd` is used to run system services. Other Linux flavors might use something else, or might have files in different places than is assumed by the script. It will probably work on any distribution that uses `systemd` but it has been developed for and tested on Ubuntu.

If you have a node already running on the computer, stop it before running the script. Script won't touch the node working directory so you won't need to bootstrap the node again.

### Node Running from Terminal[​](#node-running-from-terminal "Direct link to heading")

If your node is running in a terminal stop it by pressing `ctrl+C`.

### Node Running as a Service[​](#node-running-as-a-service "Direct link to heading")

If your node is already running as a service, then you probably don't need this script. You're good to go.

### Node Running in the Background[​](#node-running-in-the-background "Direct link to heading")

If your node is running in the background (by running with `nohup`, for example) then find the process running the node by running `ps aux | grep avalanche`. This will produce output like:

```bash
ubuntu  6834  0.0  0.0   2828   676 pts/1    S+   19:54   0:00 grep avalanche
ubuntu  2630 26.1  9.4 2459236 753316 ?      Sl   Dec02 1220:52 /home/ubuntu/build/avalanchego
```

Look for line that doesn't have `grep` on it. In this example, that is the second line. It shows information about your node. Note the process id, in this case, `2630`. Stop the node by running `kill -2 2630`.

### Node Working Files[​](#node-working-files "Direct link to heading")

If you previously ran an AvalancheGo node on this computer, you will have local node files stored in `$HOME/.avalanchego` directory. Those files will not be disturbed, and node set up by the script will continue operation with the same identity and state it had before. That being said, for your node's security, back up `staker.crt` and `staker.key` files, found in `$HOME/.avalanchego/staking` and store them somewhere secure. You can use those files to recreate your node on a different computer if you ever need to. Check out this [tutorial](/docs/nodes/maintain/backup-restore) for backup and restore procedure.

Networking Considerations[​](#networking-considerations "Direct link to heading")
---------------------------------------------------------------------------------

To run successfully, AvalancheGo needs to accept connections from the Internet on the network port `9651`. Before you proceed with the installation, you need to determine the networking environment your node will run in.

### Running on a Cloud Provider[​](#running-on-a-cloud-provider "Direct link to heading")

If your node is running on a cloud provider computer instance, it will have a static IP. Find out what that static IP is, or set it up if you didn't already. The script will try to find out the IP by itself, but that might not work in all environments, so you will need to check the IP or enter it yourself.

### Running on a Home Connection[​](#running-on-a-home-connection "Direct link to heading")

If you're running a node on a computer that is on a residential internet connection, you have a dynamic IP; that is, your IP will change periodically. The install script will configure the node appropriately for that situation. But, for a home connection, you will need to set up inbound port forwarding of port `9651` from the internet to the computer the node is installed on.

As there are too many models and router configurations, we cannot provide instructions on what exactly to do, but there are online guides to be found (like [this](https://www.noip.com/support/knowledgebase/general-port-forwarding-guide/), or [this](https://www.howtogeek.com/66214/how-to-forward-ports-on-your-router/) ), and your service provider support might help too.

<Callout type="warn">
Please note that a fully connected Avalanche node maintains and communicates over a couple of thousand of live TCP connections. For some low-powered and older home routers that might be too much to handle. If that is the case you may experience lagging on other computers connected to the same router, node getting benched, failing to sync and similar issues.
</Callout>

# How to Stake (/docs/nodes/validate/how-to-stake)

---
title: How to Stake
description: Learn how to stake on Avalanche.
---

Staking Parameters on Avalanche[​](#staking-parameters-on-avalanche "Direct link to heading")
---------------------------------------------------------------------------------------------

When a validator is done validating the [Primary Network](http://support.avalabs.org/en/articles/4135650-what-is-the-primary-network), it receives back the AVAX tokens it staked. It may receive a reward for helping to secure the network. A validator only receives a [validation reward](http://support.avalabs.org/en/articles/4587396-what-are-validator-staking-rewards) if it is sufficiently responsive and correct during the time it validates. Read the [Avalanche token white paper](https://www.avalabs.org/whitepapers) to learn more about AVAX and the mechanics of staking.

<Callout type="warn">
Staking rewards are sent to your wallet address at the end of the staking term **as long as all of these parameters are met**.
</Callout>

### Mainnet[​](#mainnet "Direct link to heading")

- The minimum amount that a validator must stake is 2,000 AVAX
- The minimum amount that a delegator must delegate is 25 AVAX
- The minimum amount of time one can stake funds for validation is 2 weeks
- The maximum amount of time one can stake funds for validation is 1 year
- The minimum amount of time one can stake funds for delegation is 2 weeks
- The maximum amount of time one can stake funds for delegation is 1 year
- The minimum delegation fee rate is 2%
- The maximum weight of a validator (their own stake + stake delegated to them) is the minimum of 3 million AVAX and 5 times the amount the validator staked. For example, if you staked 2,000 AVAX to become a validator, only 8000 AVAX can be delegated to your node total (not per delegator)

A validator will receive a staking reward if they are online and response for more than 80% of their validation period, as measured by a majority of validators, weighted by stake. **You should aim for your validator be online and responsive 100% of the time.**

You can call API method `info.uptime` on your node to learn its weighted uptime and what percentage of the network currently thinks your node has an uptime high enough to receive a staking reward. See [here.](/docs/api-reference/info-api#infouptime) You can get another opinion on your node's uptime from Avalanche's [Validator Health dashboard](https://stats.avax.network/dashboard/validator-health-check/). If your reported uptime is not close to 100%, there may be something wrong with your node setup, which may jeopardize your staking reward. If this is the case, please see [here](#why-is-my-uptime-low) or contact us on [Discord](https://discord.gg/avax/) so we can help you find the issue. Note that only checking the uptime of your validator as measured by non-staking nodes, validators with small stake, or validators that have not been online for the full duration of your validation period can provide an inaccurate view of your node's true uptime.

### Fuji Testnet[​](#fuji-testnet "Direct link to heading")

On Fuji Testnet, all staking parameters are the same as those on Mainnet except the following ones:

- The minimum amount that a validator must stake is 1 AVAX
- The minimum amount that a delegator must delegate is 1 AVAX
- The minimum amount of time one can stake funds for validation is 24 hours
- The minimum amount of time one can stake funds for delegation is 24 hours

Validators[​](#validators "Direct link to heading")
---------------------------------------------------

**Validators** secure Avalanche, create new blocks, and process transactions. To achieve consensus, validators repeatedly sample each other. The probability that a given validator is sampled is proportional to its stake.

When you add a node to the validator set, you specify:

- Your node's ID
- Your node's BLS key and BLS signature
- When you want to start and stop validating
- How many AVAX you are staking
- The address to send any rewards to
- Your delegation fee rate (see below)

<Callout title="Note">
The minimum amount that a validator must stake is 2,000 AVAX.
</Callout>

<Callout type="warn">
Note that once you issue the transaction to add a node as a validator, there is no way to change the parameters. **You can't remove your stake early or change the stake amount, node ID, or reward address.**

Please make sure you're using the correct values in the API calls below. If you're not sure, ask for help on [Discord](https://discord.gg/avax/). If you want to add more tokens to your own validator, you can delegate the tokens to this node - but you cannot increase the base validation amount (so delegating to yourself goes against your delegation cap).
</Callout>

### Running a Validator[​](#running-a-validator "Direct link to heading")

If you're running a validator, it's important that your node is well connected to ensure that you receive a reward.

When you issue the transaction to add a validator, the staked tokens and transaction fee (which is 0) are deducted from the addresses you control. When you are done validating, the staked funds are returned to the addresses they came from. If you earned a reward, it is sent to the address you specified when you added yourself as a validator.

#### Allow API Calls[​](#allow-api-calls "Direct link to heading")

To make API calls to your node from remote machines, allow traffic on the API port (`9650` by default), and run your node with argument `--http-host=`

You should disable all APIs you will not use via command-line arguments. You should configure your network to only allow access to the API port from trusted machines (for example, your personal computer.)

#### Why Is My Uptime Low?[​](#why-is-my-uptime-low "Direct link to heading")

Every validator on Avalanche keeps track of the uptime of other validators. Every validator has a weight (that is the amount staked on it.) The more weight a validator has, the more influence they have when validators vote on whether your node should receive a staking reward. You can call API method `info.uptime` on your node to learn its weighted uptime and what percentage of the network stake currently thinks your node has an uptime high enough to receive a staking reward.

You can also see the connections a node has by calling `info.peers`, as well as the uptime of each connection. **This is only one node's point of view**. Other nodes may perceive the uptime of your node differently. Just because one node perceives your uptime as being low does not mean that you will not receive staking rewards.

If your node's uptime is low, make sure you're setting config option `--public-ip=[NODE'S PUBLIC IP]` and that your node can receive incoming TCP traffic on port 9651.

#### Secret Management[​](#secret-management "Direct link to heading")

The only secret that you need on your validating node is its Staking Key, the TLS key that determines your node's ID. The first time you start a node, the Staking Key is created and put in `$HOME/.avalanchego/staking/staker.key`. You should back up this file (and `staker.crt`) somewhere secure. Losing your Staking Key could jeopardize your validation reward, as your node will have a new ID.

You do not need to have AVAX funds on your validating node. In fact, it's best practice to **not** have a lot of funds on your node. Almost all of your funds should be in "cold" addresses whose private key is not on any computer.

#### Monitoring[​](#monitoring "Direct link to heading")

Follow this [tutorial](/docs/nodes/maintain/monitoring) to learn how to monitor your node's uptime, general health, etc.

### Reward Formula[​](#reward-formula "Direct link to heading")

Consider a validator which stakes a $Stake$ amount of Avax for $StakingPeriod$ seconds.

Assume that at the start of the staking period there is a $Supply$ amount of Avax in the Primary Network.

The maximum amount of Avax is $MaximumSupply$ . Then at the end of its staking period, a responsive validator receives a reward calculated as follows:

$$
Reward = \left(MaximumSupply - Supply \right) \times \frac{Stake}{Supply} \times \frac{Staking Period}{Minting Period} \times EffectiveConsumptionRate
$$

where,

$$
EffectiveConsumptionRate = 
$$

$$
\frac{MinConsumptionRate}{PercentDenominator} \times \left(1- \frac{Staking Period}{Minting Period}\right) + \frac{MaxConsumptionRate}{PercentDenominator} \times \frac{Staking Period}{Minting Period}
$$

<Callout title="Note">
Note that $StakingPeriod$ is the staker's entire staking period, not just the staker's uptime, that is the aggregated time during which the staker has been responsive. The uptime comes into play only to decide whether a staker should be rewarded; to calculate the actual reward, only the staking period duration is taken into account.
</Callout>

$EffectiveConsumptionRate$ is a linear combination of $MinConsumptionRate$ and $MaxConsumptionRate$.
$MinConsumptionRate$ and $MaxConsumptionRate$ bound $EffectiveConsumptionRate$ because 

$$
MinConsumptionRate \leq EffectiveConsumptionRate \leq MaxConsumptionRate
$$

The larger $StakingPeriod$ is, the closer $EffectiveConsumptionRate$ is to $MaxConsumptionRate$.

A staker achieves the maximum reward for its stake if $StakingPeriod$ = $Minting Period$.

The reward is:

$$
Max Reward = \left(MaximumSupply - Supply \right) \times \frac{Stake}{Supply} \times \frac{MaxConsumptionRate}{PercentDenominator}
$$

Delegators[​](#delegators "Direct link to heading")
---------------------------------------------------

A delegator is a token holder, who wants to participate in staking, but chooses to trust an existing validating node through delegation.

When you delegate stake to a validator, you specify:

- The ID of the node you're delegating to
- When you want to start/stop delegating stake (must be while the validator is validating)
- How many AVAX you are staking
- The address to send any rewards to

<Callout title="Note">
The minimum amount that a delegator must delegate is 25 AVAX.
</Callout>

<Callout type="warn">
Note that once you issue the transaction to add your stake to a delegator, there is no way to change the parameters. **You can't remove your stake early or change the stake amount, node ID, or reward address.** If you're not sure, ask for help on [Discord](https://discord.gg/avax/).
</Callout>

### Delegator Rewards[​](#delegator-rewards "Direct link to heading")

If the validator that you delegate tokens to is sufficiently correct and responsive, you will receive a reward when you are done delegating. Delegators are rewarded according to the same function as validators. However, the validator that you delegate to keeps a portion of your reward specified by the validator's delegation fee rate.

When you issue the transaction to delegate tokens, the staked tokens and transaction fee are deducted from the addresses you control. When you are done delegating, the staked tokens are returned to your address. If you earned a reward, it is sent to the address you specified when you delegated tokens. Rewards are sent to delegators right after the delegation ends with the return of staked tokens, and before the validation period of the node they're delegating to is complete.

FAQ[​](#faq "Direct link to heading")
-------------------------------------

### Is There a Tool to Check the Health of a Validator?[​](#is-there-a-tool-to-check-the-health-of-a-validator "Direct link to heading")

Yes, just enter your node's ID in the Avalanche Stats [Validator Health Dashboard](https://stats.avax.network/dashboard/validator-health-check/?nodeid=NodeID-Jp4dLMTHd6huttS1jZhqNnBN9ZMNmTmWC).

### How Is It Determined Whether a Validator Receives a Staking Reward?[​](#how-is-it-determined-whether-a-validator-receives-a-staking-reward "Direct link to heading")

When a node leaves the validator set, the validators vote on whether the leaving node should receive a staking reward or not. If a validator calculates that the leaving node was responsive for more than the required uptime (currently 80%), the validator will vote for the leaving node to receive a staking reward. Otherwise, the validator will vote that the leaving node should not receive a staking reward. The result of this vote, which is weighted by stake, determines whether the leaving node receives a reward or not.

Each validator only votes "yes" or "no." It does not share its data such as the leaving node's uptime.

Each validation period is considered separately. That is, suppose a node joins the validator set, and then leaves. Then it joins and leaves again. The node's uptime during its first period in the validator set does not affect the uptime calculation in the second period, hence, has no impact on whether the node receives a staking reward for its second period in the validator set.

### How Are Delegation Fees Distributed To Validators?[​](#how-are-delegation-fees-distributed-to-validators "Direct link to heading")

If a validator is online for 80% of a delegation period, they receive a % of the reward (the fee) earned by the delegator. The P-Chain used to distribute this fee as a separate UTXO per delegation period. After the [Cortina Activation](https://medium.com/avalancheavax/cortina-x-chain-linearization-a1d9305553f6), instead of sending a fee UTXO for each successful delegation period, fees are now batched during a node's entire validation period and are distributed when it is unstaked.

### Error: Couldn't Issue TX: Validator Would Be Over Delegated[​](#error-couldnt-issue-tx-validator-would-be-over-delegated "Direct link to heading")

This error occurs whenever the delegator can not delegate to the named validator. This can be caused by the following.

- The delegator `startTime` is before the validator `startTime`
- The delegator `endTime` is after the validator `endTime`
- The delegator weight would result in the validator total weight exceeding its maximum weight

# Turn Node Into Validator (/docs/nodes/validate/node-validator)

---
title: Turn Node Into Validator
description: This tutorial will show you how to add a node to the validator set of Primary Network on Avalanche.
---

## Introduction

The [Primary Network](/docs/quick-start/primary-network)
is inherent to the Avalanche platform and validates Avalanche's built-in
blockchains. In this
tutorial, we'll add a node to the Primary Network on Avalanche.

The P-Chain manages metadata on Avalanche. This includes tracking which nodes
are in which Avalanche L1s, which blockchains exist, and which Avalanche L1s are validating
which blockchains. To add a validator, we'll issue
[transactions](http://support.avalabs.org/en/articles/4587384-what-is-a-transaction)
to the P-Chain.

<Callout type="warn">
Note that once you issue the transaction to add a node as a validator, there is
no way to change the parameters. **You can't remove your stake early or change
the stake amount, node ID, or reward address.** Please make sure you're using
the correct values in the API calls below. If you're not sure, feel free to join
our [Discord](https://chat.avalabs.org/) to ask questions.
</Callout>

## Requirements

You've completed [Run an Avalanche Node](/docs/nodes/run-a-node/from-source) and are familiar with
[Avalanche's architecture](/docs/quick-start/primary-network). In this
tutorial, we use [AvalancheJS](/docs/tooling/avalanche-js) and
[Avalanche's Postman collection](/docs/tooling/avalanchego-postman-collection) 
to help us make API calls.

In order to ensure your node is well-connected, make sure that your node can
receive and send TCP traffic on the staking port (`9651` by default) and your node
has a public IP address(it's optional to set --public-ip=[YOUR NODE'S PUBLIC IP HERE]
when executing the AvalancheGo binary, as by default, the node will attempt to perform
NAT traversal to get the node's IP according to its router). Failing to do either of
these may jeopardize your staking reward.

## Add a Validator with Core extension

First, we show you how to add your node as a validator by using [Core web](https://core.app).

### Retrieve the Node ID, the BLS signature and the BLS key

Get this info by calling [`info.getNodeID`](/docs/api-reference/info-api#infogetnodeid):

```bash
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"info.getNodeID"
}' -H 'content-type:application/json' 127.0.0.1:9650/ext/info
```

The response has your node's ID, the BLS key (public key) and the BLS signature (proof of possession):

```json
{
  "jsonrpc": "2.0",
  "result": {
    "nodeID": "NodeID-5mb46qkSBj81k9g9e4VFjGGSbaaSLFRzD",
    "nodePOP": {
      "publicKey": "0x8f95423f7142d00a48e1014a3de8d28907d420dc33b3052a6dee03a3f2941a393c2351e354704ca66a3fc29870282e15",
      "proofOfPossession": "0x86a3ab4c45cfe31cae34c1d06f212434ac71b1be6cfe046c80c162e057614a94a5bc9f1ded1a7029deb0ba4ca7c9b71411e293438691be79c2dbf19d1ca7c3eadb9c756246fc5de5b7b89511c7d7302ae051d9e03d7991138299b5ed6a570a98"
    }
  },
  "id": 1
}
```

### Add as a Validator

Connect [Core extension](https://core.app) to [Core web](https://core.app), and go the 'Staking' tab. 
Here, choose 'Validate' from the menu.

Fill out the staking parameters. They are explained in more detail in [this doc](/docs/nodes/validate/how-to-stake). When you've 
filled in all the staking parameters and double-checked them, click `Submit Validation`. Make sure the staking period is at
least 2 weeks, the delegation fee rate is at least 2%, and you're staking at
least 2,000 AVAX on Mainnet (1 AVAX on Fuji Testnet). A full guide about this can be found 
[here](https://support.avax.network/en/articles/8117267-core-web-how-do-i-validate-in-core-stake).

You should see a success message, and your balance should be updated.

Go back to the `Stake` tab, and you'll see here an overview of your validation,
with information like the amount staked, staking time, and more.

![Staking Overview](/images/node-validator.png)

Calling
[`platform.getPendingValidators`](/docs/api-reference/p-chain/api#platformgetpendingvalidators)
verifies that your transaction was accepted. Note that this API call should be
made before your node's validation start time, otherwise, the return will not
include your node's id as it is no longer pending.

You can also call
[`platform.getCurrentValidators`](/docs/api-reference/p-chain/api#platformgetcurrentvalidators)
to check that your node's id is included in the response.

That's it!

## Add a Validator with AvalancheJS

We can also add a node to the validator set using [AvalancheJS](/docs/tooling/avalanche-js).

### Install AvalancheJS

To use AvalancheJS, you can clone the repo:

```bash
git clone https://github.com/ava-labs/avalanchejs.git
```

<Callout title="Note">
The repository cloning method used is HTTPS, but SSH can be used too:

`git clone git@github.com:ava-labs/avalanchejs.git`

You can find more about SSH and how to use it
[here](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/about-ssh).
</Callout>

or add it to an existing project:

```bash
yarn add @avalabs/avalanchejs
```

For this tutorial we will use [`ts-node`](https://www.npmjs.com/package/ts-node)
to run the example scripts directly from an AvalancheJS directory.

### Fuji Workflow

In this section, we will use Fuji Testnet to show how to add a node to the validator set.

Open your AvalancheJS directory and select the
[**`examples/p-chain`**](https://github.com/ava-labs/avalanchejs/tree/master/examples/p-chain)
folder to view the source code for the examples scripts.

We will use the
[**`validate.ts`**](https://github.com/ava-labs/avalanchejs/blob/master/examples/p-chain/validate.ts)
script to add a validator.

#### Add Necessary Environment Variables

Locate the `.env.example` file at the root of AvalancheJS, and remove `.example`
from the title. Now, this will be the `.env` file for global variables.

Add the private key and the P-Chain address associated with it.
The API URL is already set to Fuji (`https://api.avax-test.network/`).

![env Variables](/images/validator-avalanchejs-1.png)

#### Retrieve the Node ID, the BLS signature and the BLS key

Get this info by calling [`info.getNodeID`](/docs/api-reference/info-api#infogetnodeid):

```bash
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"info.getNodeID"
}' -H 'content-type:application/json' 127.0.0.1:9650/ext/info
```

The response has your node's ID, the BLS key (public key) and the BLS signature (proof of possession):

```json
{
  "jsonrpc": "2.0",
  "result": {
    "nodeID": "NodeID-JXJNyJXhgXzvVGisLkrDiZvF938zJxnT5",
    "nodePOP": {
      "publicKey": "0xb982b485916c1d74e3b749e7ce49730ac0e52d28279ce4c5c989d75a43256d3012e04b1de0561276631ea6c2c8dc4429",
      "proofOfPossession": "0xb6cdf3927783dba3245565bd9451b0c2a39af2087fdf401956489b42461452ec7639b9082195b7181907177b1ea09a6200a0d32ebbc668d9c1e9156872633cfb7e161fbd0e75943034d28b25ec9d9cdf2edad4aaf010adf804af8f6d0d5440c5"
    }
  },
  "id": 1
}
```

#### Fill in the Node ID, the BLS signature and the BLS key

After retrieving this data, go to `examples/p-chain/validate.ts`.

Replace the `nodeID`, `blsPublicKey` and `blsSignature` with your 
own node's values.

![Replaced values](/images/validator-avalanchejs-2.png)

#### Settings for Validation

Next we need to specify the node's validation period and delegation fee.

#### Validation Period

The validation period is set by default to 21 days, the start date
being the date and time the transaction is issued. The start date
cannot be modified.

The end date can be adjusted in the code.

Let's say we want the validation period to end after 50 days.
You can achieve this by adding the number of desired days to
`endTime.getDate()`, in this case `50`.

```ts
// move ending date 50 days into the future
endTime.setDate(endTime.getDate() + 50);
```

Now let's say you want the staking period to end on a specific 
date and time, for example May 15, 2024, at 11:20 AM.
It can be achieved as shown in the code below.

```ts
const startTime = await new PVMApi().getTimestamp();
const startDate = new Date(startTime.timestamp);
const start = BigInt(startDate.getTime() / 1000);

// Set the end time to a specific date and time
const endTime = new Date('2024-05-15T11:20:00'); // May 15, 2024, at 11:20 AM
const end = BigInt(endTime.getTime() / 1000);
```

#### Delegation Fee Rate

Avalanche allows for delegation of stake. This parameter is the percent fee this
validator charges when others delegate stake to them. For example, if
`delegationFeeRate` is `10` and someone delegates to this validator, then when
the delegation period is over, 10% of the reward goes to the validator and the
rest goes to the delegator, if this node meets the validation reward
requirements.

The delegation fee on AvalancheJS is set `20`. To change this, you need
to provide the desired fee percent as a parameter to `newAddPermissionlessValidatorTx`,
which is by default `1e4 * 20`.

For example, if you'd want it to be `10`, the updated code would look like this:

```ts
const tx = newAddPermissionlessValidatorTx(
  context,
  utxos,
  [bech32ToBytes(P_CHAIN_ADDRESS)],
  nodeID,
  PrimaryNetworkID.toString(),
  start,
  end,
  BigInt(1e9),
  [bech32ToBytes(P_CHAIN_ADDRESS)],
  [bech32ToBytes(P_CHAIN_ADDRESS)],
  1e4 * 10, // delegation fee, replaced 20 with 10
  undefined,
  1,
  0n,
  blsPublicKey,
  blsSignature,
);
```

#### Stake Amount

Set the amount being locked for validation when calling
`newAddPermissionlessValidatorTx` by replacing `weight` with a number
in the unit of nAVAX. For example, `2 AVAX` would be `2e9 nAVAX`.

```ts
const tx = newAddPermissionlessValidatorTx(
  context,
  utxos,
  [bech32ToBytes(P_CHAIN_ADDRESS)],
  nodeID,
  PrimaryNetworkID.toString(),
  start,
  end,
  BigInt(2e9), // the amount to stake
  [bech32ToBytes(P_CHAIN_ADDRESS)],
  [bech32ToBytes(P_CHAIN_ADDRESS)],
  1e4 * 10,
  undefined,
  1,
  0n,
  blsPublicKey,
  blsSignature,
);
```

#### Execute the Code

Now that we have made all of the necessary changes to the example script, it's
time to add a validator to the Fuji Network.

Run the command:

```bash
node --loader ts-node/esm examples/p-chain/validate.ts
```

The response:

```bash
laviniatalpas@Lavinias-MacBook-Pro avalanchejs % node --loader ts-node/esm examples/p-chain/validate.ts
(node:87616) ExperimentalWarning: `--experimental-loader` may be removed in the future; instead use `register()`:
--import 'data:text/javascript,import { register } from "node:module"; import { pathToFileURL } from "node:url"; register("ts-node/esm", pathToFileURL("./"));'
(Use `node --trace-warnings ...` to show where the warning was created)
{ txID: 'RVe3CFRieRbBvKXKPu24Zbt1QehdyGVT6X4tPWVBeACPX3Ab8' }
```

We can check the transaction's status by running the example script with
[`platform.getTxStatus`](/docs/api-reference/p-chain/api#platformgettxstatus)
or looking up the validator directly on the 
[explorer](https://subnets-test.avax.network/validators/NodeID-JXJNyJXhgXzvVGisLkrDiZvF938zJxnT5).

![Added Validator](/images/validator-avalanchejs-3.png)

### Mainnet Workflow

The Fuji workflow above can be adapted to Mainnet with the following modifications:

- `AVAX_PUBLIC_URL` should be `https://api.avax.network/`.
- `P_CHAIN_ADDRESS` should be the Mainnet P-Chain address.
- Set the correct amount to stake.
- The `blsPublicKey`, `blsSignature` and `nodeID` need to be the ones for your Mainnet Node.


# Validate vs. Delegate (/docs/nodes/validate/validate-vs-delegate)

---
title: Validate vs. Delegate
description: Understand the difference between validation and delegation.
---

Validation[​](#validation "Direct link to heading")
---------------------------------------------------

Validation in the context of staking refers to the act of running a node on the blockchain network to validate transactions and secure the network.

- **Stake Requirement**: To become a validator on the Avalanche network, one must stake a minimum amount of 2,000 AVAX tokens on the Mainnet (1 AVAX on the Fuji Testnet).
- **Process**: Validators participate in achieving consensus by repeatedly sampling other validators. The probability of being sampled is proportional to the validator's stake, meaning the more tokens a validator stakes, the more influential they are in the consensus process.
- **Rewards**: Validators are eligible to receive rewards for their efforts in securing the network. To receive rewards, a validator must be online and responsive for more than 80% of their validation period.

Delegation[​](#delegation "Direct link to heading")
---------------------------------------------------

Delegation allows token holders who do not wish to run their own validator node to still participate in staking by "delegating" their tokens to an existing validator node.

- **Stake Requirement**: To delegate on the Avalanche network, a minimum of 25 AVAX tokens is required on the Mainnet (1 AVAX on the Fuji Testnet).
- **Process**: Delegators choose a specific validator node to delegate their tokens to, trusting that the validator will behave correctly and help secure the network on their behalf.
- **Rewards**: Delegators are also eligible to receive rewards for their stake. The validator they delegate to shares a portion of the reward with them, according to the validator's delegation fee rate.

Key Differences[​](#key-differences "Direct link to heading")
-------------------------------------------------------------

- **Responsibilities**: Validators actively run a node, validate transactions, and actively participate in securing the network. Delegators, on the other hand, do not run a node themselves but entrust their tokens to a validator to participate on their behalf.
- **Stake Requirement**: Validators have a higher minimum stake requirement compared to delegators, as they take on more responsibility in the network.
- **Rewards Distribution**: Validators receive rewards directly for their validation efforts. Delegators receive rewards indirectly through the validator they delegate to, sharing a portion of the validator's reward.

In summary, validation involves actively participating in securing the network by running a node, while delegation allows token holders to participate passively by trusting their stake to a chosen validator. Both validators and delegators can earn rewards, but validators have higher stakes and more direct involvement in the Avalanche network.

# What Is Staking? (/docs/nodes/validate/what-is-staking)

---
title: What Is Staking?
description: Learn about staking and how it works in Avalanche.
---

Staking is the process where users lock up their tokens to support a blockchain network and, in return, receive rewards. It is an essential part of proof-of-stake (PoS) consensus mechanisms used by many blockchain networks, including Avalanche. PoS systems require participants to stake a certain amount of tokens as collateral to participate in the network and validate transactions.

How Does Proof-of-Stake Work?[​](#how-does-proof-of-stake-work "Direct link to heading")
----------------------------------------------------------------------------------------

To resist [sybil attacks](https://support.avalabs.org/en/articles/4064853-what-is-a-sybil-attack), a decentralized network must require that network influence is paid with a scarce resource. This makes it infeasibly expensive for an attacker to gain enough influence over the network to compromise its security. On Avalanche, the scarce resource is the native token, [AVAX](/docs/quick-start/avax-token). For a node to validate a blockchain on Avalanche, it must stake AVAX.

# Fuji Testnet (/docs/quick-start/networks/fuji-testnet)

---
title: Fuji Testnet
description: Learn about the official Testnet for the Avalanche ecosystem.
---

Fuji's infrastructure imitates Avalanche Mainnet. It's comprised of a [Primary Network](/docs/quick-start/primary-network) formed by instances of X, P, and C-Chain, as well as many test Avalanche L1s.

## When to Use Fuji

Fuji provides users with a platform to simulate the conditions found in the Mainnet environment. It enables developers to deploy demo Smart Contracts, allowing them to test and refine their applications before deploying them on the [Primary Network](/docs/quick-start/primary-network).

Users interested in experimenting with Avalanche can receive free testnet AVAX, allowing them to explore the platform without any risk. These testnet tokens have no value in the real world and are only meant for experimentation purposes within the Fuji test network.

To receive testnet tokens, users can request funds from the [Avalanche Faucet](/docs/dapps/smart-contract-dev/get-test-funds). If there's already an AVAX balance greater than zero on Mainnet, paste the C-Chain address there, and request test tokens. Otherwise, please request a faucet coupon on [Guild](https://guild.xyz/avalanche). Admins and mods on the official [Discord](https://discord.com/invite/RwXY7P6) can provide testnet AVAX if developers are unable to obtain it from the other two options.

## Add Avalanche C-Chain Testnet to Wallet

- **Network Name**: Avalanche Fuji C-Chain
- **RPC URL**: https://api.avax-test.network/ext/bc/C/rpc
- **WebSocket URL**: wss://api.avax-test.network/ext/bc/C/ws
- **ChainID**: `43113`
- **Symbol**: `AVAX`
- **Explorer**: https://subnets-test.avax.network/c-chain

Head over to explorer linked above and select "Add Avalanche C-Chain to Wallet" under "Chain Info" to automatically add the network.

## Additional Details

- Fuji Testnet has its own dedicated [block explorer](https://subnets-test.avax.network/).
- The Public API endpoint for Fuji is not the same as Mainnet. More info is available in the [Public API Server](/docs/tooling/rpc-providers) documentation.
- You can run a Fuji validator node by staking only **1 Fuji AVAX**.


# Avalanche Mainnet (/docs/quick-start/networks/mainnet)

---
title: Avalanche Mainnet
description: Learn about the Avalanche Mainnet.
---

The Avalanche Mainnet refers to the main network of the Avalanche blockchain where real transactions and smart contract executions occur. It is the final and production-ready version of the blockchain where users can interact with the network and transact with real world assets.

A _network of networks_, Avalanche Mainnet includes the [Primary Network](/docs/quick-start/primary-network) formed by the X, P, and C-Chain, as well as all in-production [Avalanche L1s](/docs/quick-start/avalanche-l1s).

These Avalanche L1s are independent blockchain sub-networks that can be tailored to specific application use cases, use their own consensus mechanisms, define their own token economics, and be run by different [virtual machines](/docs/quick-start/virtual-machines).

## Add Avalanche C-Chain Mainnet to Wallet

- **Network Name**: Avalanche Mainnet C-Chain
- **RPC URL**: https://api.avax.network/ext/bc/C/rpc
- **WebSocket URL**: wss://api.avax.network/ext/bc/C/ws
- **ChainID**: `43114`
- **Symbol**: `AVAX`
- **Explorer**: https://subnets.avax.network/c-chain

Head over to explorer linked above and select "Add Avalanche C-Chain to Wallet" under "Chain Info" to automatically add the network.

# CLI Commands (/docs/tooling/avalanche-cli/cli-commands)

---
title: "CLI Commands"
description: "Complete list of Avalanche CLI commands and their usage."
edit_url: https://github.com/ava-labs/avalanche-cli/edit/main/cmd/commands.md
---

<a id="avalanche-blockchain"></a>
## avalanche blockchain

The blockchain command suite provides a collection of tools for developing
and deploying Blockchains.

To get started, use the blockchain create command wizard to walk through the
configuration of your very first Blockchain. Then, go ahead and deploy it
with the blockchain deploy command. You can use the rest of the commands to
manage your Blockchain configurations and live deployments.

**Usage:**
```bash
avalanche blockchain [subcommand] [flags]
```

**Subcommands:**

- [`addValidator`](#avalanche-blockchain-addvalidator): The blockchain addValidator command adds a node as a validator to
an L1 of the user provided deployed network. If the network is proof of 
authority, the owner of the validator manager contract must sign the 
transaction. If the network is proof of stake, the node must stake the L1's
staking token. Both processes will issue a RegisterL1ValidatorTx on the P-Chain.

This command currently only works on Blockchains deployed to either the Fuji
Testnet or Mainnet.
- [`changeOwner`](#avalanche-blockchain-changeowner): The blockchain changeOwner changes the owner of the deployed Blockchain.
- [`changeWeight`](#avalanche-blockchain-changeweight): The blockchain changeWeight command changes the weight of a L1 Validator.

The L1 has to be a Proof of Authority L1.
- [`configure`](#avalanche-blockchain-configure): AvalancheGo nodes support several different configuration files.
Each network (a Subnet or an L1) has their own config which applies to all blockchains/VMs in the network (see https://build.avax.network/docs/nodes/configure/avalanche-l1-configs)
Each blockchain within the network can have its own chain config (see https://build.avax.network/docs/nodes/chain-configs/c-chain https://github.com/ava-labs/subnet-evm/blob/master/plugin/evm/config/config.go for subnet-evm options).
A chain can also have special requirements for the AvalancheGo node configuration itself (see https://build.avax.network/docs/nodes/configure/configs-flags).
This command allows you to set all those files.
- [`create`](#avalanche-blockchain-create): The blockchain create command builds a new genesis file to configure your Blockchain.
By default, the command runs an interactive wizard. It walks you through
all the steps you need to create your first Blockchain.

The tool supports deploying Subnet-EVM, and custom VMs. You
can create a custom, user-generated genesis with a custom VM by providing
the path to your genesis and VM binaries with the --genesis and --vm flags.

By default, running the command with a blockchainName that already exists
causes the command to fail. If you'd like to overwrite an existing
configuration, pass the -f flag.
- [`delete`](#avalanche-blockchain-delete): The blockchain delete command deletes an existing blockchain configuration.
- [`deploy`](#avalanche-blockchain-deploy): The blockchain deploy command deploys your Blockchain configuration locally, to Fuji Testnet, or to Mainnet.

At the end of the call, the command prints the RPC URL you can use to interact with the Subnet.

Avalanche-CLI only supports deploying an individual Blockchain once per network. Subsequent
attempts to deploy the same Blockchain to the same network (local, Fuji, Mainnet) aren't
allowed. If you'd like to redeploy a Blockchain locally for testing, you must first call
avalanche network clean to reset all deployed chain state. Subsequent local deploys
redeploy the chain with fresh state. You can deploy the same Blockchain to multiple networks,
so you can take your locally tested Blockchain and deploy it on Fuji or Mainnet.
- [`describe`](#avalanche-blockchain-describe): The blockchain describe command prints the details of a Blockchain configuration to the console.
By default, the command prints a summary of the configuration. By providing the --genesis
flag, the command instead prints out the raw genesis file.
- [`export`](#avalanche-blockchain-export): The blockchain export command write the details of an existing Blockchain deploy to a file.

The command prompts for an output path. You can also provide one with
the --output flag.
- [`import`](#avalanche-blockchain-import): Import blockchain configurations into avalanche-cli.

This command suite supports importing from a file created on another computer,
or importing from blockchains running public networks
(e.g. created manually or with the deprecated subnet-cli)
- [`join`](#avalanche-blockchain-join): The blockchain join command configures your validator node to begin validating a new Blockchain.

To complete this process, you must have access to the machine running your validator. If the
CLI is running on the same machine as your validator, it can generate or update your node's
config file automatically. Alternatively, the command can print the necessary instructions
to update your node manually. To complete the validation process, the Blockchain's admins must add
the NodeID of your validator to the Blockchain's allow list by calling addValidator with your
NodeID.

After you update your validator's config, you need to restart your validator manually. If
you provide the --avalanchego-config flag, this command attempts to edit the config file
at that path.

This command currently only supports Blockchains deployed on the Fuji Testnet and Mainnet.
- [`list`](#avalanche-blockchain-list): The blockchain list command prints the names of all created Blockchain configurations. Without any flags,
it prints some general, static information about the Blockchain. With the --deployed flag, the command
shows additional information including the VMID, BlockchainID and SubnetID.
- [`publish`](#avalanche-blockchain-publish): The blockchain publish command publishes the Blockchain's VM to a repository.
- [`removeValidator`](#avalanche-blockchain-removevalidator): The blockchain removeValidator command stops a whitelisted blockchain network validator from
validating your deployed Blockchain.

To remove the validator from the Subnet's allow list, provide the validator's unique NodeID. You can bypass
these prompts by providing the values with flags.
- [`stats`](#avalanche-blockchain-stats): The blockchain stats command prints validator statistics for the given Blockchain.
- [`upgrade`](#avalanche-blockchain-upgrade): The blockchain upgrade command suite provides a collection of tools for
updating your developmental and deployed Blockchains.
- [`validators`](#avalanche-blockchain-validators): The blockchain validators command lists the validators of a blockchain and provides
several statistics about them.
- [`vmid`](#avalanche-blockchain-vmid): The blockchain vmid command prints the virtual machine ID (VMID) for the given Blockchain.

**Flags:**

```bash
-h, --help             help for blockchain
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-blockchain-addvalidator"></a>
### addValidator

The blockchain addValidator command adds a node as a validator to
an L1 of the user provided deployed network. If the network is proof of 
authority, the owner of the validator manager contract must sign the 
transaction. If the network is proof of stake, the node must stake the L1's
staking token. Both processes will issue a RegisterL1ValidatorTx on the P-Chain.

This command currently only works on Blockchains deployed to either the Fuji
Testnet or Mainnet.

**Usage:**
```bash
avalanche blockchain addValidator [subcommand] [flags]
```

**Flags:**

```bash
--aggregator-allow-private-peers        allow the signature aggregator to connect to peers with private IP (default true)
--aggregator-extra-endpoints strings    endpoints for extra nodes that are needed in signature aggregation
--aggregator-log-level string           log level to use with signature aggregator (default "Debug")
--aggregator-log-to-stdout              use stdout for signature aggregator logs
--balance float                         set the AVAX balance of the validator that will be used for continuous fee on P-Chain
--blockchain-genesis-key                use genesis allocated key to pay fees for completing the validator's registration (blockchain gas token)
--blockchain-key string                 CLI stored key to use to pay fees for completing the validator's registration (blockchain gas token)
--blockchain-private-key string         private key to use to pay fees for completing the validator's registration (blockchain gas token)
--bls-proof-of-possession string        set the BLS proof of possession of the validator to add
--bls-public-key string                 set the BLS public key of the validator to add
--cluster string                        operate on the given cluster
--create-local-validator                create additional local validator and add it to existing running local node
--default-duration                      (for Subnets, not L1s) set duration so as to validate until primary validator ends its period
--default-start-time                    (for Subnets, not L1s) use default start time for subnet validator (5 minutes later for fuji & mainnet, 30 seconds later for devnet)
--default-validator-params              (for Subnets, not L1s) use default weight/start/duration params for subnet validator
--delegation-fee uint16                 (PoS only) delegation fee (in bips) (default 100)
--devnet                                operate on a devnet network
--disable-owner string                  P-Chain address that will able to disable the validator with a P-Chain transaction
--endpoint string                       use the given endpoint for network operations
-e, --ewoq                              use ewoq key [fuji/devnet only]
-f, --fuji                              testnet                         operate on fuji (alias to testnet
-h, --help                              help for addValidator
-k, --key string                        select the key to use [fuji/devnet only]
-g, --ledger                            use ledger instead of key (always true on mainnet, defaults to false on fuji/devnet)
--ledger-addrs strings                  use the given ledger addresses
-l, --local                             operate on a local network
-m, --mainnet                           operate on mainnet
--node-endpoint string                  gather node id/bls from publicly available avalanchego apis on the given endpoint
--node-id string                        node-id of the validator to add
--output-tx-path string                 (for Subnets, not L1s) file path of the add validator tx
--partial-sync                          set primary network partial sync for new validators (default true)
--remaining-balance-owner string        P-Chain address that will receive any leftover AVAX from the validator when it is removed from Subnet
--rpc string                            connect to validator manager at the given rpc endpoint
--stake-amount uint                     (PoS only) amount of tokens to stake
--staking-period duration               how long this validator will be staking
--start-time string                     (for Subnets, not L1s) UTC start time when this validator starts validating, in 'YYYY-MM-DD HH:MM:SS' format
--subnet-auth-keys strings              (for Subnets, not L1s) control keys that will be used to authenticate add validator tx
-t, --testnet                           fuji                         operate on testnet (alias to fuji)
--wait-for-tx-acceptance                (for Subnets, not L1s) just issue the add validator tx, without waiting for its acceptance (default true)
--weight uint                           set the staking weight of the validator to add (default 20)
--config string                         config file (default is $HOME/.avalanche-cli/config.json)
--log-level string                      log level for the application (default "ERROR")
--skip-update-check                     skip check for new versions
```

<a id="avalanche-blockchain-changeowner"></a>
### changeOwner

The blockchain changeOwner changes the owner of the deployed Blockchain.

**Usage:**
```bash
avalanche blockchain changeOwner [subcommand] [flags]
```

**Flags:**

```bash
--auth-keys strings        control keys that will be used to authenticate transfer blockchain ownership tx
--cluster string           operate on the given cluster
--control-keys strings     addresses that may make blockchain changes
--devnet                   operate on a devnet network
--endpoint string          use the given endpoint for network operations
-e, --ewoq                 use ewoq key [fuji/devnet]
-f, --fuji                 testnet            operate on fuji (alias to testnet
-h, --help                 help for changeOwner
-k, --key string           select the key to use [fuji/devnet]
-g, --ledger               use ledger instead of key (always true on mainnet, defaults to false on fuji/devnet)
--ledger-addrs strings     use the given ledger addresses
-l, --local                operate on a local network
-m, --mainnet              operate on mainnet
--output-tx-path string    file path of the transfer blockchain ownership tx
-s, --same-control-key     use the fee-paying key as control key
-t, --testnet              fuji            operate on testnet (alias to fuji)
--threshold uint32         required number of control key signatures to make blockchain changes
--config string            config file (default is $HOME/.avalanche-cli/config.json)
--log-level string         log level for the application (default "ERROR")
--skip-update-check        skip check for new versions
```

<a id="avalanche-blockchain-changeweight"></a>
### changeWeight

The blockchain changeWeight command changes the weight of a L1 Validator.

The L1 has to be a Proof of Authority L1.

**Usage:**
```bash
avalanche blockchain changeWeight [subcommand] [flags]
```

**Flags:**

```bash
--cluster string          operate on the given cluster
--devnet                  operate on a devnet network
--endpoint string         use the given endpoint for network operations
-e, --ewoq                use ewoq key [fuji/devnet only]
-f, --fuji                testnet           operate on fuji (alias to testnet
-h, --help                help for changeWeight
-k, --key string          select the key to use [fuji/devnet only]
-g, --ledger              use ledger instead of key (always true on mainnet, defaults to false on fuji/devnet)
--ledger-addrs strings    use the given ledger addresses
-l, --local               operate on a local network
-m, --mainnet             operate on mainnet
--node-endpoint string    gather node id/bls from publicly available avalanchego apis on the given endpoint
--node-id string          node-id of the validator
-t, --testnet             fuji           operate on testnet (alias to fuji)
--weight uint             set the new staking weight of the validator
--config string           config file (default is $HOME/.avalanche-cli/config.json)
--log-level string        log level for the application (default "ERROR")
--skip-update-check       skip check for new versions
```

<a id="avalanche-blockchain-configure"></a>
### configure

AvalancheGo nodes support several different configuration files.
Each network (a Subnet or an L1) has their own config which applies to all blockchains/VMs in the network (see https://build.avax.network/docs/nodes/configure/avalanche-l1-configs)
Each blockchain within the network can have its own chain config (see https://build.avax.network/docs/nodes/chain-configs/c-chain https://github.com/ava-labs/subnet-evm/blob/master/plugin/evm/config/config.go for subnet-evm options).
A chain can also have special requirements for the AvalancheGo node configuration itself (see https://build.avax.network/docs/nodes/configure/configs-flags).
This command allows you to set all those files.

**Usage:**
```bash
avalanche blockchain configure [subcommand] [flags]
```

**Flags:**

```bash
--chain-config string             path to the chain configuration
-h, --help                        help for configure
--node-config string              path to avalanchego node configuration
--per-node-chain-config string    path to per node chain configuration for local network
--subnet-config string            path to the subnet configuration
--config string                   config file (default is $HOME/.avalanche-cli/config.json)
--log-level string                log level for the application (default "ERROR")
--skip-update-check               skip check for new versions
```

<a id="avalanche-blockchain-create"></a>
### create

The blockchain create command builds a new genesis file to configure your Blockchain.
By default, the command runs an interactive wizard. It walks you through
all the steps you need to create your first Blockchain.

The tool supports deploying Subnet-EVM, and custom VMs. You
can create a custom, user-generated genesis with a custom VM by providing
the path to your genesis and VM binaries with the --genesis and --vm flags.

By default, running the command with a blockchainName that already exists
causes the command to fail. If you'd like to overwrite an existing
configuration, pass the -f flag.

**Usage:**
```bash
avalanche blockchain create [subcommand] [flags]
```

**Flags:**

```bash
--custom                            use a custom VM template
--custom-vm-branch string           custom vm branch or commit
--custom-vm-build-script string     custom vm build-script
--custom-vm-path string             file path of custom vm to use
--custom-vm-repo-url string         custom vm repository url
--debug                             enable blockchain debugging (default true)
--evm                               use the Subnet-EVM as the base template
--evm-chain-id uint                 chain ID to use with Subnet-EVM
--evm-defaults                      deprecation notice: use '--production-defaults'
--evm-token string                  token symbol to use with Subnet-EVM
--external-gas-token                use a gas token from another blockchain
-f, --force                         overwrite the existing configuration if one exists
--from-github-repo                  generate custom VM binary from github repository
--genesis string                    file path of genesis to use
-h, --help                          help for create
--icm                               interoperate with other blockchains using ICM
--icm-registry-at-genesis           setup ICM registry smart contract on genesis [experimental]
--latest                            use latest Subnet-EVM released version, takes precedence over --vm-version
--pre-release                       use latest Subnet-EVM pre-released version, takes precedence over --vm-version
--production-defaults               use default production settings for your blockchain
--proof-of-authority                use proof of authority(PoA) for validator management
--proof-of-stake                    use proof of stake(PoS) for validator management
--proxy-contract-owner string       EVM address that controls ProxyAdmin for TransparentProxy of ValidatorManager contract
--reward-basis-points uint          (PoS only) reward basis points for PoS Reward Calculator (default 100)
--sovereign                         set to false if creating non-sovereign blockchain (default true)
--teleporter                        interoperate with other blockchains using ICM
--test-defaults                     use default test settings for your blockchain
--validator-manager-owner string    EVM address that controls Validator Manager Owner
--vm string                         file path of custom vm to use. alias to custom-vm-path
--vm-version string                 version of Subnet-EVM template to use
--warp                              generate a vm with warp support (needed for ICM) (default true)
--config string                     config file (default is $HOME/.avalanche-cli/config.json)
--log-level string                  log level for the application (default "ERROR")
--skip-update-check                 skip check for new versions
```

<a id="avalanche-blockchain-delete"></a>
### delete

The blockchain delete command deletes an existing blockchain configuration.

**Usage:**
```bash
avalanche blockchain delete [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for delete
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-blockchain-deploy"></a>
### deploy

The blockchain deploy command deploys your Blockchain configuration to Local Network, to Fuji Testnet, DevNet or to Mainnet.

At the end of the call, the command prints the RPC URL you can use to interact with the L1 / Subnet.

When deploying an L1, Avalanche-CLI lets you use your local machine as a bootstrap validator, so you don't need to run separate Avalanche nodes.
This is controlled by the --use-local-machine flag (enabled by default on Local Network).

If --use-local-machine is set to true:
- Avalanche-CLI will call CreateSubnetTx, CreateChainTx, ConvertSubnetToL1Tx, followed by syncing the local machine bootstrap validator to the L1 and initialize
  Validator Manager Contract on the L1

If using your own Avalanche Nodes as bootstrap validators:
- Avalanche-CLI will call CreateSubnetTx, CreateChainTx, ConvertSubnetToL1Tx
- You will have to sync your bootstrap validators to the L1
- Next, Initialize Validator Manager contract on the L1 using avalanche contract initValidatorManager [L1_Name]

Avalanche-CLI only supports deploying an individual Blockchain once per network. Subsequent
attempts to deploy the same Blockchain to the same network (Local Network, Fuji, Mainnet) aren't
allowed. If you'd like to redeploy a Blockchain locally for testing, you must first call
avalanche network clean to reset all deployed chain state. Subsequent local deploys
redeploy the chain with fresh state. You can deploy the same Blockchain to multiple networks,
so you can take your locally tested Blockchain and deploy it on Fuji or Mainnet.

**Usage:**
```bash
avalanche blockchain deploy [subcommand] [flags]
```

**Flags:**

```bash
 --convert-only              avoid node track, restart and poa manager setup
  -e, --ewoq                      use ewoq key [local/devnet deploy only]
  -h, --help                      help for deploy
  -k, --key string                select the key to use [fuji/devnet deploy only]
  -g, --ledger                    use ledger instead of key
      --ledger-addrs strings      use the given ledger addresses
      --mainnet-chain-id uint32   use different ChainID for mainnet deployment
      --output-tx-path string     file path of the blockchain creation tx (for multi-sig signing)
  -u, --subnet-id string          do not create a subnet, deploy the blockchain into the given subnet id
      --subnet-only               command stops after CreateSubnetTx and returns SubnetID

Network Flags (Select One):
  --cluster string   operate on the given cluster
  --devnet           operate on a devnet network
  --endpoint string  use the given endpoint for network operations
  --fuji             operate on fuji (alias to `testnet`)
  --local            operate on a local network
  --mainnet          operate on mainnet
  --testnet          operate on testnet (alias to `fuji`)

Bootstrap Validators Flags:
  --balance float64                  set the AVAX balance of each bootstrap validator that will be used for continuous fee on P-Chain (setting balance=1 equals to 1 AVAX for each bootstrap validator)
  --bootstrap-endpoints stringSlice  take validator node info from the given endpoints
  --bootstrap-filepath string        JSON file path that provides details about bootstrap validators
  --change-owner-address string      address that will receive change if node is no longer L1 validator
  --generate-node-id                 set to true to generate Node IDs for bootstrap validators when none are set up. Use these Node IDs to set up your Avalanche Nodes.
  --num-bootstrap-validators int     number of bootstrap validators to set up in sovereign L1 validator)

Local Machine Flags (Use Local Machine as Bootstrap Validator):
  --avalanchego-path string              use this avalanchego binary path
  --avalanchego-version string           use this version of avalanchego (ex: v1.17.12)
  --http-port uintSlice                  http port for node(s)
  --partial-sync                         set primary network partial sync for new validators
  --staking-cert-key-path stringSlice    path to provided staking cert key for node(s)
  --staking-port uintSlice               staking port for node(s)
  --staking-signer-key-path stringSlice  path to provided staking signer key for node(s)
  --staking-tls-key-path stringSlice     path to provided staking TLS key for node(s)
  --use-local-machine                    use local machine as a blockchain validator

Local Network Flags:
  --avalanchego-path string     use this avalanchego binary path
  --avalanchego-version string  use this version of avalanchego (ex: v1.17.12)
  --num-nodes uint32            number of nodes to be created on local network deploy

Non Subnet-Only-Validators (Non-SOV) Flags:
  --auth-keys stringSlice     control keys that will be used to authenticate chain creation
  --control-keys stringSlice  addresses that may make blockchain changes
  --same-control-key          use the fee-paying key as control key
  --threshold uint32          required number of control key signatures to make blockchain changes

ICM Flags:
  --cchain-funding-key string                          key to be used to fund relayer account on cchain
  --cchain-icm-key string                              key to be used to pay for ICM deploys on C-Chain
  --icm-key string                                     key to be used to pay for ICM deploys
  --icm-version string                                 ICM version to deploy
  --relay-cchain                                       relay C-Chain as source and destination
  --relayer-allow-private-ips                          allow relayer to connec to private ips
  --relayer-amount float64                             automatically fund relayer fee payments with the given amount
  --relayer-key string                                 key to be used by default both for rewards and to pay fees
  --relayer-log-level string                           log level to be used for relayer logs
  --relayer-path string                                relayer binary to use
  --relayer-version string                             relayer version to deploy
  --skip-icm-deploy                                    Skip automatic ICM deploy
  --skip-relayer                                       skip relayer deploy
  --teleporter-messenger-contract-address-path string  path to an ICM Messenger contract address file
  --teleporter-messenger-deployer-address-path string  path to an ICM Messenger deployer address file
  --teleporter-messenger-deployer-tx-path string       path to an ICM Messenger deployer tx file
  --teleporter-registry-bytecode-path string           path to an ICM Registry bytecode file

Proof Of Stake Flags:
  --pos-maximum-stake-amount uint64     maximum stake amount
  --pos-maximum-stake-multiplier uint8  maximum stake multiplier
  --pos-minimum-delegation-fee uint16   minimum delegation fee
  --pos-minimum-stake-amount uint64     minimum stake amount
  --pos-minimum-stake-duration uint64   minimum stake duration (in seconds)
  --pos-weight-to-value-factor uint64   weight to value factor

Signature Aggregator Flags:
  --aggregator-log-level string  log level to use with signature aggregator
  --aggregator-log-to-stdout     use stdout for signature aggregator logs
```

<a id="avalanche-blockchain-describe"></a>
### describe

The blockchain describe command prints the details of a Blockchain configuration to the console.
By default, the command prints a summary of the configuration. By providing the --genesis
flag, the command instead prints out the raw genesis file.

**Usage:**
```bash
avalanche blockchain describe [subcommand] [flags]
```

**Flags:**

```bash
-g, --genesis          Print the genesis to the console directly instead of the summary
-h, --help             help for describe
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-blockchain-export"></a>
### export

The blockchain export command write the details of an existing Blockchain deploy to a file.

The command prompts for an output path. You can also provide one with
the --output flag.

**Usage:**
```bash
avalanche blockchain export [subcommand] [flags]
```

**Flags:**

```bash
--custom-vm-branch string          custom vm branch
--custom-vm-build-script string    custom vm build-script
--custom-vm-repo-url string        custom vm repository url
-h, --help                         help for export
-o, --output string                write the export data to the provided file path
--config string                    config file (default is $HOME/.avalanche-cli/config.json)
--log-level string                 log level for the application (default "ERROR")
--skip-update-check                skip check for new versions
```

<a id="avalanche-blockchain-import"></a>
### import

Import blockchain configurations into avalanche-cli.

This command suite supports importing from a file created on another computer,
or importing from blockchains running public networks
(e.g. created manually or with the deprecated subnet-cli)

**Usage:**
```bash
avalanche blockchain import [subcommand] [flags]
```

**Subcommands:**

- [`file`](#avalanche-blockchain-import-file): The blockchain import command will import a blockchain configuration from a file or a git repository.

To import from a file, you can optionally provide the path as a command-line argument.
Alternatively, running the command without any arguments triggers an interactive wizard.
To import from a repository, go through the wizard. By default, an imported Blockchain doesn't 
overwrite an existing Blockchain with the same name. To allow overwrites, provide the --force
flag.
- [`public`](#avalanche-blockchain-import-public): The blockchain import public command imports a Blockchain configuration from a running network.

By default, an imported Blockchain
doesn't overwrite an existing Blockchain with the same name. To allow overwrites, provide the --force
flag.

**Flags:**

```bash
-h, --help             help for import
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-blockchain-import-file"></a>
#### import file

The blockchain import command will import a blockchain configuration from a file or a git repository.

To import from a file, you can optionally provide the path as a command-line argument.
Alternatively, running the command without any arguments triggers an interactive wizard.
To import from a repository, go through the wizard. By default, an imported Blockchain doesn't 
overwrite an existing Blockchain with the same name. To allow overwrites, provide the --force
flag.

**Usage:**
```bash
avalanche blockchain import file [subcommand] [flags]
```

**Flags:**

```bash
--blockchain string    the blockchain configuration to import from the provided repo
--branch string        the repo branch to use if downloading a new repo
-f, --force            overwrite the existing configuration if one exists
-h, --help             help for file
--repo string          the repo to import (ex: ava-labs/avalanche-plugins-core) or url to download the repo from
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-blockchain-import-public"></a>
#### import public

The blockchain import public command imports a Blockchain configuration from a running network.

By default, an imported Blockchain
doesn't overwrite an existing Blockchain with the same name. To allow overwrites, provide the --force
flag.

**Usage:**
```bash
avalanche blockchain import public [subcommand] [flags]
```

**Flags:**

```bash
--blockchain-id string    the blockchain ID
--cluster string          operate on the given cluster
--custom                  use a custom VM template
--devnet                  operate on a devnet network
--endpoint string         use the given endpoint for network operations
--evm                     import a subnet-evm
--force                   overwrite the existing configuration if one exists
-f, --fuji                testnet           operate on fuji (alias to testnet
-h, --help                help for public
-l, --local               operate on a local network
-m, --mainnet             operate on mainnet
--node-url string         [optional] URL of an already running validator
-t, --testnet             fuji           operate on testnet (alias to fuji)
--config string           config file (default is $HOME/.avalanche-cli/config.json)
--log-level string        log level for the application (default "ERROR")
--skip-update-check       skip check for new versions
```

<a id="avalanche-blockchain-join"></a>
### join

The blockchain join command configures your validator node to begin validating a new Blockchain.

To complete this process, you must have access to the machine running your validator. If the
CLI is running on the same machine as your validator, it can generate or update your node's
config file automatically. Alternatively, the command can print the necessary instructions
to update your node manually. To complete the validation process, the Blockchain's admins must add
the NodeID of your validator to the Blockchain's allow list by calling addValidator with your
NodeID.

After you update your validator's config, you need to restart your validator manually. If
you provide the --avalanchego-config flag, this command attempts to edit the config file
at that path.

This command currently only supports Blockchains deployed on the Fuji Testnet and Mainnet.

**Usage:**
```bash
avalanche blockchain join [subcommand] [flags]
```

**Flags:**

```bash
--avalanchego-config string    file path of the avalanchego config file
--cluster string               operate on the given cluster
--data-dir string              path of avalanchego's data dir directory
--devnet                       operate on a devnet network
--endpoint string              use the given endpoint for network operations
--force-write                  if true, skip to prompt to overwrite the config file
-f, --fuji                     testnet                operate on fuji (alias to testnet
-h, --help                     help for join
-k, --key string               select the key to use [fuji only]
-g, --ledger                   use ledger instead of key (always true on mainnet, defaults to false on fuji)
--ledger-addrs strings         use the given ledger addresses
-l, --local                    operate on a local network
-m, --mainnet                  operate on mainnet
--node-id string               set the NodeID of the validator to check
--plugin-dir string            file path of avalanchego's plugin directory
--print                        if true, print the manual config without prompting
--stake-amount uint            amount of tokens to stake on validator
--staking-period duration      how long validator validates for after start time
--start-time string            start time that validator starts validating
-t, --testnet                  fuji                operate on testnet (alias to fuji)
--config string                config file (default is $HOME/.avalanche-cli/config.json)
--log-level string             log level for the application (default "ERROR")
--skip-update-check            skip check for new versions
```

<a id="avalanche-blockchain-list"></a>
### list

The blockchain list command prints the names of all created Blockchain configurations. Without any flags,
it prints some general, static information about the Blockchain. With the --deployed flag, the command
shows additional information including the VMID, BlockchainID and SubnetID.

**Usage:**
```bash
avalanche blockchain list [subcommand] [flags]
```

**Flags:**

```bash
--deployed             show additional deploy information
-h, --help             help for list
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-blockchain-publish"></a>
### publish

The blockchain publish command publishes the Blockchain's VM to a repository.

**Usage:**
```bash
avalanche blockchain publish [subcommand] [flags]
```

**Flags:**

```bash
--alias string               We publish to a remote repo, but identify the repo locally under a user-provided alias (e.g. myrepo).
--force                      If true, ignores if the blockchain has been published in the past, and attempts a forced publish.
-h, --help                   help for publish
--no-repo-path string        Do not let the tool manage file publishing, but have it only generate the files and put them in the location given by this flag.
--repo-url string            The URL of the repo where we are publishing
--subnet-file-path string    Path to the Blockchain description file. If not given, a prompting sequence will be initiated.
--vm-file-path string        Path to the VM description file. If not given, a prompting sequence will be initiated.
--config string              config file (default is $HOME/.avalanche-cli/config.json)
--log-level string           log level for the application (default "ERROR")
--skip-update-check          skip check for new versions
```

<a id="avalanche-blockchain-removevalidator"></a>
### removeValidator

The blockchain removeValidator command stops a whitelisted blockchain network validator from
validating your deployed Blockchain.

To remove the validator from the Subnet's allow list, provide the validator's unique NodeID. You can bypass
these prompts by providing the values with flags.

**Usage:**
```bash
avalanche blockchain removeValidator [subcommand] [flags]
```

**Flags:**

```bash
--aggregator-allow-private-peers        allow the signature aggregator to connect to peers with private IP (default true)
--aggregator-extra-endpoints strings    endpoints for extra nodes that are needed in signature aggregation
--aggregator-log-level string           log level to use with signature aggregator (default "Debug")
--aggregator-log-to-stdout              use stdout for signature aggregator logs
--auth-keys strings                     (for non-SOV blockchain only) control keys that will be used to authenticate the removeValidator tx
--blockchain-genesis-key                use genesis allocated key to pay fees for completing the validator's removal (blockchain gas token)
--blockchain-key string                 CLI stored key to use to pay fees for completing the validator's removal (blockchain gas token)
--blockchain-private-key string         private key to use to pay fees for completing the validator's removal (blockchain gas token)
--cluster string                        operate on the given cluster
--devnet                                operate on a devnet network
--endpoint string                       use the given endpoint for network operations
--force                                 force validator removal even if it's not getting rewarded
-f, --fuji                              testnet                         operate on fuji (alias to testnet
-h, --help                              help for removeValidator
-k, --key string                        select the key to use [fuji deploy only]
-g, --ledger                            use ledger instead of key (always true on mainnet, defaults to false on fuji)
--ledger-addrs strings                  use the given ledger addresses
-l, --local                             operate on a local network
-m, --mainnet                           operate on mainnet
--node-endpoint string                  remove validator that responds to the given endpoint
--node-id string                        node-id of the validator
--output-tx-path string                 (for non-SOV blockchain only) file path of the removeValidator tx
--rpc string                            connect to validator manager at the given rpc endpoint
-t, --testnet                           fuji                         operate on testnet (alias to fuji)
--uptime uint                           validator's uptime in seconds. If not provided, it will be automatically calculated
--config string                         config file (default is $HOME/.avalanche-cli/config.json)
--log-level string                      log level for the application (default "ERROR")
--skip-update-check                     skip check for new versions
```

<a id="avalanche-blockchain-stats"></a>
### stats

The blockchain stats command prints validator statistics for the given Blockchain.

**Usage:**
```bash
avalanche blockchain stats [subcommand] [flags]
```

**Flags:**

```bash
--cluster string       operate on the given cluster
--devnet               operate on a devnet network
--endpoint string      use the given endpoint for network operations
-f, --fuji             testnet      operate on fuji (alias to testnet
-h, --help             help for stats
-l, --local            operate on a local network
-m, --mainnet          operate on mainnet
-t, --testnet          fuji      operate on testnet (alias to fuji)
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-blockchain-upgrade"></a>
### upgrade

The blockchain upgrade command suite provides a collection of tools for
updating your developmental and deployed Blockchains.

**Usage:**
```bash
avalanche blockchain upgrade [subcommand] [flags]
```

**Subcommands:**

- [`apply`](#avalanche-blockchain-upgrade-apply): Apply generated upgrade bytes to running Blockchain nodes to trigger a network upgrade.

For public networks (Fuji Testnet or Mainnet), to complete this process,
you must have access to the machine running your validator.
If the CLI is running on the same machine as your validator, it can manipulate your node's
configuration automatically. Alternatively, the command can print the necessary instructions
to upgrade your node manually.

After you update your validator's configuration, you need to restart your validator manually.
If you provide the --avalanchego-chain-config-dir flag, this command attempts to write the upgrade file at that path.
Refer to https://docs.avax.network/nodes/maintain/chain-config-flags#subnet-chain-configs for related documentation.
- [`export`](#avalanche-blockchain-upgrade-export): Export the upgrade bytes file to a location of choice on disk
- [`generate`](#avalanche-blockchain-upgrade-generate): The blockchain upgrade generate command builds a new upgrade.json file to customize your Blockchain. It
guides the user through the process using an interactive wizard.
- [`import`](#avalanche-blockchain-upgrade-import): Import the upgrade bytes file into the local environment
- [`print`](#avalanche-blockchain-upgrade-print): Print the upgrade.json file content
- [`vm`](#avalanche-blockchain-upgrade-vm): The blockchain upgrade vm command enables the user to upgrade their Blockchain's VM binary. The command
can upgrade both local Blockchains and publicly deployed Blockchains on Fuji and Mainnet.

The command walks the user through an interactive wizard. The user can skip the wizard by providing
command line flags.

**Flags:**

```bash
-h, --help             help for upgrade
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-blockchain-upgrade-apply"></a>
#### upgrade apply

Apply generated upgrade bytes to running Blockchain nodes to trigger a network upgrade.

For public networks (Fuji Testnet or Mainnet), to complete this process,
you must have access to the machine running your validator.
If the CLI is running on the same machine as your validator, it can manipulate your node's
configuration automatically. Alternatively, the command can print the necessary instructions
to upgrade your node manually.

After you update your validator's configuration, you need to restart your validator manually.
If you provide the --avalanchego-chain-config-dir flag, this command attempts to write the upgrade file at that path.
Refer to https://docs.avax.network/nodes/maintain/chain-config-flags#subnet-chain-configs for related documentation.

**Usage:**
```bash
avalanche blockchain upgrade apply [subcommand] [flags]
```

**Flags:**

```bash
--avalanchego-chain-config-dir string    avalanchego's chain config file directory (default "/home/runner/.avalanchego/chains")
--config                                 create upgrade config for future subnet deployments (same as generate)
--force                                  If true, don't prompt for confirmation of timestamps in the past
--fuji                                   fuji                             apply upgrade existing fuji deployment (alias for `testnet`)
-h, --help                               help for apply
--local                                  local                           apply upgrade existing local deployment
--mainnet                                mainnet                       apply upgrade existing mainnet deployment
--print                                  if true, print the manual config without prompting (for public networks only)
--testnet                                testnet                       apply upgrade existing testnet deployment (alias for `fuji`)
--log-level string                       log level for the application (default "ERROR")
--skip-update-check                      skip check for new versions
```

<a id="avalanche-blockchain-upgrade-export"></a>
#### upgrade export

Export the upgrade bytes file to a location of choice on disk

**Usage:**
```bash
avalanche blockchain upgrade export [subcommand] [flags]
```

**Flags:**

```bash
--force                      If true, overwrite a possibly existing file without prompting
-h, --help                   help for export
--upgrade-filepath string    Export upgrade bytes file to location of choice on disk
--config string              config file (default is $HOME/.avalanche-cli/config.json)
--log-level string           log level for the application (default "ERROR")
--skip-update-check          skip check for new versions
```

<a id="avalanche-blockchain-upgrade-generate"></a>
#### upgrade generate

The blockchain upgrade generate command builds a new upgrade.json file to customize your Blockchain. It
guides the user through the process using an interactive wizard.

**Usage:**
```bash
avalanche blockchain upgrade generate [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for generate
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-blockchain-upgrade-import"></a>
#### upgrade import

Import the upgrade bytes file into the local environment

**Usage:**
```bash
avalanche blockchain upgrade import [subcommand] [flags]
```

**Flags:**

```bash
-h, --help                   help for import
--upgrade-filepath string    Import upgrade bytes file into local environment
--config string              config file (default is $HOME/.avalanche-cli/config.json)
--log-level string           log level for the application (default "ERROR")
--skip-update-check          skip check for new versions
```

<a id="avalanche-blockchain-upgrade-print"></a>
#### upgrade print

Print the upgrade.json file content

**Usage:**
```bash
avalanche blockchain upgrade print [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for print
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-blockchain-upgrade-vm"></a>
#### upgrade vm

The blockchain upgrade vm command enables the user to upgrade their Blockchain's VM binary. The command
can upgrade both local Blockchains and publicly deployed Blockchains on Fuji and Mainnet.

The command walks the user through an interactive wizard. The user can skip the wizard by providing
command line flags.

**Usage:**
```bash
avalanche blockchain upgrade vm [subcommand] [flags]
```

**Flags:**

```bash
--binary string        Upgrade to custom binary
--config               upgrade config for future subnet deployments
--fuji                 fuji           upgrade existing fuji deployment (alias for `testnet`)
-h, --help             help for vm
--latest               upgrade to latest version
--local                local         upgrade existing local deployment
--mainnet              mainnet     upgrade existing mainnet deployment
--plugin-dir string    plugin directory to automatically upgrade VM
--print                print instructions for upgrading
--testnet              testnet     upgrade existing testnet deployment (alias for `fuji`)
--version string       Upgrade to custom version
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-blockchain-validators"></a>
### validators

The blockchain validators command lists the validators of a blockchain and provides
several statistics about them.

**Usage:**
```bash
avalanche blockchain validators [subcommand] [flags]
```

**Flags:**

```bash
--cluster string       operate on the given cluster
--devnet               operate on a devnet network
--endpoint string      use the given endpoint for network operations
-f, --fuji             testnet      operate on fuji (alias to testnet
-h, --help             help for validators
-l, --local            operate on a local network
-m, --mainnet          operate on mainnet
-t, --testnet          fuji      operate on testnet (alias to fuji)
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-blockchain-vmid"></a>
### vmid

The blockchain vmid command prints the virtual machine ID (VMID) for the given Blockchain.

**Usage:**
```bash
avalanche blockchain vmid [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for vmid
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-config"></a>
## avalanche config

Customize configuration for Avalanche-CLI

**Usage:**
```bash
avalanche config [subcommand] [flags]
```

**Subcommands:**

- [`authorize-cloud-access`](#avalanche-config-authorize-cloud-access): set preferences to authorize access to cloud resources
- [`metrics`](#avalanche-config-metrics): set user metrics collection preferences
- [`migrate`](#avalanche-config-migrate): migrate command migrates old ~/.avalanche-cli.json and ~/.avalanche-cli/config to /.avalanche-cli/config.json..
- [`snapshotsAutoSave`](#avalanche-config-snapshotsautosave): set user preference between auto saving local network snapshots or not
- [`update`](#avalanche-config-update): set user preference between update check or not

**Flags:**

```bash
-h, --help             help for config
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-config-authorize-cloud-access"></a>
### authorize-cloud-access

set preferences to authorize access to cloud resources

**Usage:**
```bash
avalanche config authorize-cloud-access [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for authorize-cloud-access
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-config-metrics"></a>
### metrics

set user metrics collection preferences

**Usage:**
```bash
avalanche config metrics [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for metrics
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-config-migrate"></a>
### migrate

migrate command migrates old ~/.avalanche-cli.json and ~/.avalanche-cli/config to /.avalanche-cli/config.json..

**Usage:**
```bash
avalanche config migrate [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for migrate
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-config-snapshotsautosave"></a>
### snapshotsAutoSave

set user preference between auto saving local network snapshots or not

**Usage:**
```bash
avalanche config snapshotsAutoSave [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for snapshotsAutoSave
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-config-update"></a>
### update

set user preference between update check or not

**Usage:**
```bash
avalanche config update [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for update
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-contract"></a>
## avalanche contract

The contract command suite provides a collection of tools for deploying
and interacting with smart contracts.

**Usage:**
```bash
avalanche contract [subcommand] [flags]
```

**Subcommands:**

- [`deploy`](#avalanche-contract-deploy): The contract command suite provides a collection of tools for deploying
smart contracts.
- [`initValidatorManager`](#avalanche-contract-initvalidatormanager): Initializes Proof of Authority(PoA) or Proof of Stake(PoS)Validator Manager contract on a Blockchain and sets up initial validator set on the Blockchain. For more info on Validator Manager, please head to https://github.com/ava-labs/icm-contracts/tree/main/contracts/validator-manager

**Flags:**

```bash
-h, --help             help for contract
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-contract-deploy"></a>
### deploy

The contract command suite provides a collection of tools for deploying
smart contracts.

**Usage:**
```bash
avalanche contract deploy [subcommand] [flags]
```

**Subcommands:**

- [`erc20`](#avalanche-contract-deploy-erc20): Deploy an ERC20 token into a given Network and Blockchain

**Flags:**

```bash
-h, --help             help for deploy
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-contract-deploy-erc20"></a>
#### deploy erc20

Deploy an ERC20 token into a given Network and Blockchain

**Usage:**
```bash
avalanche contract deploy erc20 [subcommand] [flags]
```

**Flags:**

```bash
--blockchain string       deploy the ERC20 contract into the given CLI blockchain
--blockchain-id string    deploy the ERC20 contract into the given blockchain ID/Alias
--c-chain                 deploy the ERC20 contract into C-Chain
--cluster string          operate on the given cluster
--devnet                  operate on a devnet network
--endpoint string         use the given endpoint for network operations
-f, --fuji                testnet           operate on fuji (alias to testnet
--funded string           set the funded address
--genesis-key             use genesis allocated key as contract deployer
-h, --help                help for erc20
--key string              CLI stored key to use as contract deployer
-l, --local               operate on a local network
-m, --mainnet             operate on mainnet
--private-key string      private key to use as contract deployer
--rpc string              deploy the contract into the given rpc endpoint
--supply uint             set the token supply
--symbol string           set the token symbol
-t, --testnet             fuji           operate on testnet (alias to fuji)
--config string           config file (default is $HOME/.avalanche-cli/config.json)
--log-level string        log level for the application (default "ERROR")
--skip-update-check       skip check for new versions
```

<a id="avalanche-contract-initvalidatormanager"></a>
### initValidatorManager

Initializes Proof of Authority(PoA) or Proof of Stake(PoS)Validator Manager contract on a Blockchain and sets up initial validator set on the Blockchain. For more info on Validator Manager, please head to https://github.com/ava-labs/icm-contracts/tree/main/contracts/validator-manager

**Usage:**
```bash
avalanche contract initValidatorManager [subcommand] [flags]
```

**Flags:**

```bash
--aggregator-allow-private-peers          allow the signature aggregator to connect to peers with private IP (default true)
--aggregator-extra-endpoints strings      endpoints for extra nodes that are needed in signature aggregation
--aggregator-log-level string             log level to use with signature aggregator (default "Debug")
--aggregator-log-to-stdout                dump signature aggregator logs to stdout
--cluster string                          operate on the given cluster
--devnet                                  operate on a devnet network
--endpoint string                         use the given endpoint for network operations
-f, --fuji                                testnet                           operate on fuji (alias to testnet
--genesis-key                             use genesis allocated key as contract deployer
-h, --help                                help for initValidatorManager
--key string                              CLI stored key to use as contract deployer
-l, --local                               operate on a local network
-m, --mainnet                             operate on mainnet
--pos-maximum-stake-amount uint           (PoS only) maximum stake amount (default 1000)
--pos-maximum-stake-multiplier            uint8     (PoS only )maximum stake multiplier (default 1)
--pos-minimum-delegation-fee uint16       (PoS only) minimum delegation fee (default 1)
--pos-minimum-stake-amount uint           (PoS only) minimum stake amount (default 1)
--pos-minimum-stake-duration uint         (PoS only) minimum stake duration (in seconds) (default 100)
--pos-reward-calculator-address string    (PoS only) initialize the ValidatorManager with reward calculator address
--pos-weight-to-value-factor uint         (PoS only) weight to value factor (default 1)
--private-key string                      private key to use as contract deployer
--rpc string                              deploy the contract into the given rpc endpoint
-t, --testnet                             fuji                           operate on testnet (alias to fuji)
--config string                           config file (default is $HOME/.avalanche-cli/config.json)
--log-level string                        log level for the application (default "ERROR")
--skip-update-check                       skip check for new versions
```

<a id="avalanche-help"></a>
## avalanche help

Help provides help for any command in the application.
Simply type avalanche help [path to command] for full details.

**Usage:**
```bash
avalanche help [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for help
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-icm"></a>
## avalanche icm

The messenger command suite provides a collection of tools for interacting
with ICM messenger contracts.

**Usage:**
```bash
avalanche icm [subcommand] [flags]
```

**Subcommands:**

- [`deploy`](#avalanche-icm-deploy): Deploys ICM Messenger and Registry into a given L1.
- [`sendMsg`](#avalanche-icm-sendmsg): Sends and wait reception for a ICM msg between two blockchains.

**Flags:**

```bash
-h, --help             help for icm
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-icm-deploy"></a>
### deploy

Deploys ICM Messenger and Registry into a given L1.

For Local Networks, it also deploys into C-Chain.

**Usage:**
```bash
avalanche icm deploy [subcommand] [flags]
```

**Flags:**

```bash
--blockchain string                         deploy ICM into the given CLI blockchain
--blockchain-id string                      deploy ICM into the given blockchain ID/Alias
--c-chain                                   deploy ICM into C-Chain
--cchain-key string                         key to be used to pay fees to deploy ICM to C-Chain
--cluster string                            operate on the given cluster
--deploy-messenger                          deploy ICM Messenger (default true)
--deploy-registry                           deploy ICM Registry (default true)
--devnet                                    operate on a devnet network
--endpoint string                           use the given endpoint for network operations
--force-registry-deploy                     deploy ICM Registry even if Messenger has already been deployed
-f, --fuji                                  testnet                             operate on fuji (alias to testnet
--genesis-key                               use genesis allocated key to fund ICM deploy
-h, --help                                  help for deploy
--include-cchain                            deploy ICM also to C-Chain
--key string                                CLI stored key to use to fund ICM deploy
-l, --local                                 operate on a local network
-m, --mainnet                               operate on mainnet
--messenger-contract-address-path string    path to a messenger contract address file
--messenger-deployer-address-path string    path to a messenger deployer address file
--messenger-deployer-tx-path string         path to a messenger deployer tx file
--private-key string                        private key to use to fund ICM deploy
--registry-bytecode-path string             path to a registry bytecode file
--rpc-url string                            use the given RPC URL to connect to the subnet
-t, --testnet                               fuji                             operate on testnet (alias to fuji)
--version string                            version to deploy (default "latest")
--config string                             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string                          log level for the application (default "ERROR")
--skip-update-check                         skip check for new versions
```

<a id="avalanche-icm-sendmsg"></a>
### sendMsg

Sends and wait reception for a ICM msg between two blockchains.

**Usage:**
```bash
avalanche icm sendMsg [subcommand] [flags]
```

**Flags:**

```bash
--cluster string                operate on the given cluster
--dest-rpc string               use the given destination blockchain rpc endpoint
--destination-address string    deliver the message to the given contract destination address
--devnet                        operate on a devnet network
--endpoint string               use the given endpoint for network operations
-f, --fuji                      testnet                 operate on fuji (alias to testnet
--genesis-key                   use genesis allocated key as message originator and to pay source blockchain fees
-h, --help                      help for sendMsg
--hex-encoded                   given message is hex encoded
--key string                    CLI stored key to use as message originator and to pay source blockchain fees
-l, --local                     operate on a local network
-m, --mainnet                   operate on mainnet
--private-key string            private key to use as message originator and to pay source blockchain fees
--source-rpc string             use the given source blockchain rpc endpoint
-t, --testnet                   fuji                 operate on testnet (alias to fuji)
--config string                 config file (default is $HOME/.avalanche-cli/config.json)
--log-level string              log level for the application (default "ERROR")
--skip-update-check             skip check for new versions
```

<a id="avalanche-ictt"></a>
## avalanche ictt

The ictt command suite provides tools to deploy and manage Interchain Token Transferrers.

**Usage:**
```bash
avalanche ictt [subcommand] [flags]
```

**Subcommands:**

- [`deploy`](#avalanche-ictt-deploy): Deploys a Token Transferrer into a given Network and Subnets

**Flags:**

```bash
-h, --help             help for ictt
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-ictt-deploy"></a>
### deploy

Deploys a Token Transferrer into a given Network and Subnets

**Usage:**
```bash
avalanche ictt deploy [subcommand] [flags]
```

**Flags:**

```bash
--c-chain-home                 set the Transferrer's Home Chain into C-Chain
--c-chain-remote               set the Transferrer's Remote Chain into C-Chain
--cluster string               operate on the given cluster
--deploy-erc20-home string     deploy a Transferrer Home for the given Chain's ERC20 Token
--deploy-native-home           deploy a Transferrer Home for the Chain's Native Token
--deploy-native-remote         deploy a Transferrer Remote for the Chain's Native Token
--devnet                       operate on a devnet network
--endpoint string              use the given endpoint for network operations
-f, --fuji                     testnet                  operate on fuji (alias to testnet
-h, --help                     help for deploy
--home-blockchain string       set the Transferrer's Home Chain into the given CLI blockchain
--home-genesis-key             use genesis allocated key to deploy Transferrer Home
--home-key string              CLI stored key to use to deploy Transferrer Home
--home-private-key string      private key to use to deploy Transferrer Home
--home-rpc string              use the given RPC URL to connect to the home blockchain
-l, --local                    operate on a local network
-m, --mainnet                  operate on mainnet
--remote-blockchain string     set the Transferrer's Remote Chain into the given CLI blockchain
--remote-genesis-key           use genesis allocated key to deploy Transferrer Remote
--remote-key string            CLI stored key to use to deploy Transferrer Remote
--remote-private-key string    private key to use to deploy Transferrer Remote
--remote-rpc string            use the given RPC URL to connect to the remote blockchain
--remote-token-decimals        uint8   use the given number of token decimals for the Transferrer Remote [defaults to token home's decimals (18 for a new wrapped native home token)]
--remove-minter-admin          remove the native minter precompile admin found on remote blockchain genesis
-t, --testnet                  fuji                  operate on testnet (alias to fuji)
--use-home string              use the given Transferrer's Home Address
--version string               tag/branch/commit of Avalanche Interchain Token Transfer (ICTT) to be used (defaults to main branch)
--config string                config file (default is $HOME/.avalanche-cli/config.json)
--log-level string             log level for the application (default "ERROR")
--skip-update-check            skip check for new versions
```

<a id="avalanche-interchain"></a>
## avalanche interchain

The interchain command suite provides a collection of tools to
set and manage interoperability between blockchains.

**Usage:**
```bash
avalanche interchain [subcommand] [flags]
```

**Subcommands:**

- [`messenger`](#avalanche-interchain-messenger): The messenger command suite provides a collection of tools for interacting
with ICM messenger contracts.
- [`relayer`](#avalanche-interchain-relayer): The relayer command suite provides a collection of tools for deploying
and configuring an ICM relayers.
- [`tokenTransferrer`](#avalanche-interchain-tokentransferrer): The tokenTransfer command suite provides tools to deploy and manage Token Transferrers.

**Flags:**

```bash
-h, --help             help for interchain
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-interchain-messenger"></a>
### messenger

The messenger command suite provides a collection of tools for interacting
with ICM messenger contracts.

**Usage:**
```bash
avalanche interchain messenger [subcommand] [flags]
```

**Subcommands:**

- [`deploy`](#avalanche-interchain-messenger-deploy): Deploys ICM Messenger and Registry into a given L1.
- [`sendMsg`](#avalanche-interchain-messenger-sendmsg): Sends and wait reception for a ICM msg between two blockchains.

**Flags:**

```bash
-h, --help             help for messenger
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-interchain-messenger-deploy"></a>
#### messenger deploy

Deploys ICM Messenger and Registry into a given L1.

For Local Networks, it also deploys into C-Chain.

**Usage:**
```bash
avalanche interchain messenger deploy [subcommand] [flags]
```

**Flags:**

```bash
--blockchain string                         deploy ICM into the given CLI blockchain
--blockchain-id string                      deploy ICM into the given blockchain ID/Alias
--c-chain                                   deploy ICM into C-Chain
--cchain-key string                         key to be used to pay fees to deploy ICM to C-Chain
--cluster string                            operate on the given cluster
--deploy-messenger                          deploy ICM Messenger (default true)
--deploy-registry                           deploy ICM Registry (default true)
--devnet                                    operate on a devnet network
--endpoint string                           use the given endpoint for network operations
--force-registry-deploy                     deploy ICM Registry even if Messenger has already been deployed
-f, --fuji                                  testnet                             operate on fuji (alias to testnet
--genesis-key                               use genesis allocated key to fund ICM deploy
-h, --help                                  help for deploy
--include-cchain                            deploy ICM also to C-Chain
--key string                                CLI stored key to use to fund ICM deploy
-l, --local                                 operate on a local network
-m, --mainnet                               operate on mainnet
--messenger-contract-address-path string    path to a messenger contract address file
--messenger-deployer-address-path string    path to a messenger deployer address file
--messenger-deployer-tx-path string         path to a messenger deployer tx file
--private-key string                        private key to use to fund ICM deploy
--registry-bytecode-path string             path to a registry bytecode file
--rpc-url string                            use the given RPC URL to connect to the subnet
-t, --testnet                               fuji                             operate on testnet (alias to fuji)
--version string                            version to deploy (default "latest")
--config string                             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string                          log level for the application (default "ERROR")
--skip-update-check                         skip check for new versions
```

<a id="avalanche-interchain-messenger-sendmsg"></a>
#### messenger sendMsg

Sends and wait reception for a ICM msg between two blockchains.

**Usage:**
```bash
avalanche interchain messenger sendMsg [subcommand] [flags]
```

**Flags:**

```bash
--cluster string                operate on the given cluster
--dest-rpc string               use the given destination blockchain rpc endpoint
--destination-address string    deliver the message to the given contract destination address
--devnet                        operate on a devnet network
--endpoint string               use the given endpoint for network operations
-f, --fuji                      testnet                 operate on fuji (alias to testnet
--genesis-key                   use genesis allocated key as message originator and to pay source blockchain fees
-h, --help                      help for sendMsg
--hex-encoded                   given message is hex encoded
--key string                    CLI stored key to use as message originator and to pay source blockchain fees
-l, --local                     operate on a local network
-m, --mainnet                   operate on mainnet
--private-key string            private key to use as message originator and to pay source blockchain fees
--source-rpc string             use the given source blockchain rpc endpoint
-t, --testnet                   fuji                 operate on testnet (alias to fuji)
--config string                 config file (default is $HOME/.avalanche-cli/config.json)
--log-level string              log level for the application (default "ERROR")
--skip-update-check             skip check for new versions
```

<a id="avalanche-interchain-relayer"></a>
### relayer

The relayer command suite provides a collection of tools for deploying
and configuring an ICM relayers.

**Usage:**
```bash
avalanche interchain relayer [subcommand] [flags]
```

**Subcommands:**

- [`deploy`](#avalanche-interchain-relayer-deploy): Deploys an ICM Relayer for the given Network.
- [`logs`](#avalanche-interchain-relayer-logs): Shows pretty formatted AWM relayer logs
- [`start`](#avalanche-interchain-relayer-start): Starts AWM relayer on the specified network (Currently only for local network).
- [`stop`](#avalanche-interchain-relayer-stop): Stops AWM relayer on the specified network (Currently only for local network, cluster).

**Flags:**

```bash
-h, --help             help for relayer
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-interchain-relayer-deploy"></a>
#### relayer deploy

Deploys an ICM Relayer for the given Network.

**Usage:**
```bash
avalanche interchain relayer deploy [subcommand] [flags]
```

**Flags:**

```bash
--allow-private-ips                allow relayer to connec to private ips (default true)
--amount float                     automatically fund l1s fee payments with the given amount
--bin-path string                  use the given relayer binary
--blockchain-funding-key string    key to be used to fund relayer account on all l1s
--blockchains strings              blockchains to relay as source and destination
--cchain                           relay C-Chain as source and destination
--cchain-amount float              automatically fund cchain fee payments with the given amount
--cchain-funding-key string        key to be used to fund relayer account on cchain
--cluster string                   operate on the given cluster
--devnet                           operate on a devnet network
--endpoint string                  use the given endpoint for network operations
-f, --fuji                         testnet                    operate on fuji (alias to testnet
-h, --help                         help for deploy
--key string                       key to be used by default both for rewards and to pay fees
-l, --local                        operate on a local network
--log-level string                 log level to use for relayer logs
-t, --testnet                      fuji                    operate on testnet (alias to fuji)
--version string                   version to deploy (default "latest-prerelease")
--config string                    config file (default is $HOME/.avalanche-cli/config.json)
--skip-update-check                skip check for new versions
```

<a id="avalanche-interchain-relayer-logs"></a>
#### relayer logs

Shows pretty formatted AWM relayer logs

**Usage:**
```bash
avalanche interchain relayer logs [subcommand] [flags]
```

**Flags:**

```bash
--endpoint string      use the given endpoint for network operations
--first uint           output first N log lines
-f, --fuji             testnet      operate on fuji (alias to testnet
-h, --help             help for logs
--last uint            output last N log lines
-l, --local            operate on a local network
--raw                  raw logs output
-t, --testnet          fuji      operate on testnet (alias to fuji)
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-interchain-relayer-start"></a>
#### relayer start

Starts AWM relayer on the specified network (Currently only for local network).

**Usage:**
```bash
avalanche interchain relayer start [subcommand] [flags]
```

**Flags:**

```bash
--bin-path string      use the given relayer binary
--cluster string       operate on the given cluster
--endpoint string      use the given endpoint for network operations
-f, --fuji             testnet      operate on fuji (alias to testnet
-h, --help             help for start
-l, --local            operate on a local network
-t, --testnet          fuji      operate on testnet (alias to fuji)
--version string       version to use (default "latest-prerelease")
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-interchain-relayer-stop"></a>
#### relayer stop

Stops AWM relayer on the specified network (Currently only for local network, cluster).

**Usage:**
```bash
avalanche interchain relayer stop [subcommand] [flags]
```

**Flags:**

```bash
--cluster string       operate on the given cluster
--endpoint string      use the given endpoint for network operations
-f, --fuji             testnet      operate on fuji (alias to testnet
-h, --help             help for stop
-l, --local            operate on a local network
-t, --testnet          fuji      operate on testnet (alias to fuji)
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-interchain-tokentransferrer"></a>
### tokenTransferrer

The tokenTransfer command suite provides tools to deploy and manage Token Transferrers.

**Usage:**
```bash
avalanche interchain tokenTransferrer [subcommand] [flags]
```

**Subcommands:**

- [`deploy`](#avalanche-interchain-tokentransferrer-deploy): Deploys a Token Transferrer into a given Network and Subnets

**Flags:**

```bash
-h, --help             help for tokenTransferrer
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-interchain-tokentransferrer-deploy"></a>
#### tokenTransferrer deploy

Deploys a Token Transferrer into a given Network and Subnets

**Usage:**
```bash
avalanche interchain tokenTransferrer deploy [subcommand] [flags]
```

**Flags:**

```bash
--c-chain-home                 set the Transferrer's Home Chain into C-Chain
--c-chain-remote               set the Transferrer's Remote Chain into C-Chain
--cluster string               operate on the given cluster
--deploy-erc20-home string     deploy a Transferrer Home for the given Chain's ERC20 Token
--deploy-native-home           deploy a Transferrer Home for the Chain's Native Token
--deploy-native-remote         deploy a Transferrer Remote for the Chain's Native Token
--devnet                       operate on a devnet network
--endpoint string              use the given endpoint for network operations
-f, --fuji                     testnet                  operate on fuji (alias to testnet
-h, --help                     help for deploy
--home-blockchain string       set the Transferrer's Home Chain into the given CLI blockchain
--home-genesis-key             use genesis allocated key to deploy Transferrer Home
--home-key string              CLI stored key to use to deploy Transferrer Home
--home-private-key string      private key to use to deploy Transferrer Home
--home-rpc string              use the given RPC URL to connect to the home blockchain
-l, --local                    operate on a local network
-m, --mainnet                  operate on mainnet
--remote-blockchain string     set the Transferrer's Remote Chain into the given CLI blockchain
--remote-genesis-key           use genesis allocated key to deploy Transferrer Remote
--remote-key string            CLI stored key to use to deploy Transferrer Remote
--remote-private-key string    private key to use to deploy Transferrer Remote
--remote-rpc string            use the given RPC URL to connect to the remote blockchain
--remote-token-decimals        uint8   use the given number of token decimals for the Transferrer Remote [defaults to token home's decimals (18 for a new wrapped native home token)]
--remove-minter-admin          remove the native minter precompile admin found on remote blockchain genesis
-t, --testnet                  fuji                  operate on testnet (alias to fuji)
--use-home string              use the given Transferrer's Home Address
--version string               tag/branch/commit of Avalanche Interchain Token Transfer (ICTT) to be used (defaults to main branch)
--config string                config file (default is $HOME/.avalanche-cli/config.json)
--log-level string             log level for the application (default "ERROR")
--skip-update-check            skip check for new versions
```

<a id="avalanche-key"></a>
## avalanche key

The key command suite provides a collection of tools for creating and managing
signing keys. You can use these keys to deploy Subnets to the Fuji Testnet,
but these keys are NOT suitable to use in production environments. DO NOT use
these keys on Mainnet.

To get started, use the key create command.

**Usage:**
```bash
avalanche key [subcommand] [flags]
```

**Subcommands:**

- [`create`](#avalanche-key-create): The key create command generates a new private key to use for creating and controlling
test Subnets. Keys generated by this command are NOT cryptographically secure enough to
use in production environments. DO NOT use these keys on Mainnet.

The command works by generating a secp256 key and storing it with the provided keyName. You
can use this key in other commands by providing this keyName.

If you'd like to import an existing key instead of generating one from scratch, provide the
--file flag.
- [`delete`](#avalanche-key-delete): The key delete command deletes an existing signing key.

To delete a key, provide the keyName. The command prompts for confirmation
before deleting the key. To skip the confirmation, provide the --force flag.
- [`export`](#avalanche-key-export): The key export command exports a created signing key. You can use an exported key in other
applications or import it into another instance of Avalanche-CLI.

By default, the tool writes the hex encoded key to stdout. If you provide the --output
flag, the command writes the key to a file of your choosing.
- [`list`](#avalanche-key-list): The key list command prints information for all stored signing
keys or for the ledger addresses associated to certain indices.
- [`transfer`](#avalanche-key-transfer): The key transfer command allows to transfer funds between stored keys or ledger addresses.

**Flags:**

```bash
-h, --help             help for key
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-key-create"></a>
### create

The key create command generates a new private key to use for creating and controlling
test Subnets. Keys generated by this command are NOT cryptographically secure enough to
use in production environments. DO NOT use these keys on Mainnet.

The command works by generating a secp256 key and storing it with the provided keyName. You
can use this key in other commands by providing this keyName.

If you'd like to import an existing key instead of generating one from scratch, provide the
--file flag.

**Usage:**
```bash
avalanche key create [subcommand] [flags]
```

**Flags:**

```bash
--file string          import the key from an existing key file
-f, --force            overwrite an existing key with the same name
-h, --help             help for create
--skip-balances        do not query public network balances for an imported key
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-key-delete"></a>
### delete

The key delete command deletes an existing signing key.

To delete a key, provide the keyName. The command prompts for confirmation
before deleting the key. To skip the confirmation, provide the --force flag.

**Usage:**
```bash
avalanche key delete [subcommand] [flags]
```

**Flags:**

```bash
-f, --force            delete the key without confirmation
-h, --help             help for delete
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-key-export"></a>
### export

The key export command exports a created signing key. You can use an exported key in other
applications or import it into another instance of Avalanche-CLI.

By default, the tool writes the hex encoded key to stdout. If you provide the --output
flag, the command writes the key to a file of your choosing.

**Usage:**
```bash
avalanche key export [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for export
-o, --output string    write the key to the provided file path
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-key-list"></a>
### list

The key list command prints information for all stored signing
keys or for the ledger addresses associated to certain indices.

**Usage:**
```bash
avalanche key list [subcommand] [flags]
```

**Flags:**

```bash
-a, --all-networks       list all network addresses
--blockchains strings    blockchains to show information about (p=p-chain, x=x-chain, c=c-chain, and blockchain names) (default p,x,c)
-c, --cchain             list C-Chain addresses (default true)
--cluster string         operate on the given cluster
--devnet                 operate on a devnet network
--endpoint string        use the given endpoint for network operations
-f, --fuji               testnet          operate on fuji (alias to testnet
-h, --help               help for list
--keys strings           list addresses for the given keys
-g, --ledger             uints          list ledger addresses for the given indices (default [])
-l, --local              operate on a local network
-m, --mainnet            operate on mainnet
--pchain                 list P-Chain addresses (default true)
--subnets strings        subnets to show information about (p=p-chain, x=x-chain, c=c-chain, and blockchain names) (default p,x,c)
-t, --testnet            fuji          operate on testnet (alias to fuji)
--tokens strings         provide balance information for the given token contract addresses (Evm only) (default [Native])
--use-gwei               use gwei for EVM balances
-n, --use-nano-avax      use nano Avax for balances
--xchain                 list X-Chain addresses (default true)
--config string          config file (default is $HOME/.avalanche-cli/config.json)
--log-level string       log level for the application (default "ERROR")
--skip-update-check      skip check for new versions
```

<a id="avalanche-key-transfer"></a>
### transfer

The key transfer command allows to transfer funds between stored keys or ledger addresses.

**Usage:**
```bash
avalanche key transfer [subcommand] [flags]
```

**Flags:**

```bash
-o, --amount float                          amount to send or receive (AVAX or TOKEN units)
--c-chain-receiver                          receive at C-Chain
--c-chain-sender                            send from C-Chain
--cluster string                            operate on the given cluster
-a, --destination-addr string               destination address
--destination-key string                    key associated to a destination address
--destination-subnet string                 subnet where the funds will be sent (token transferrer experimental)
--destination-transferrer-address string    token transferrer address at the destination subnet (token transferrer experimental)
--devnet                                    operate on a devnet network
--endpoint string                           use the given endpoint for network operations
-f, --fuji                                  testnet                             operate on fuji (alias to testnet
-h, --help                                  help for transfer
-k, --key string                            key associated to the sender or receiver address
-i, --ledger uint32                         ledger index associated to the sender or receiver address (default 32768)
-l, --local                                 operate on a local network
-m, --mainnet                               operate on mainnet
--origin-subnet string                      subnet where the funds belong (token transferrer experimental)
--origin-transferrer-address string         token transferrer address at the origin subnet (token transferrer experimental)
--p-chain-receiver                          receive at P-Chain
--p-chain-sender                            send from P-Chain
--receiver-blockchain string                receive at the given CLI blockchain
--receiver-blockchain-id string             receive at the given blockchain ID/Alias
--sender-blockchain string                  send from the given CLI blockchain
--sender-blockchain-id string               send from the given blockchain ID/Alias
-t, --testnet                               fuji                             operate on testnet (alias to fuji)
--x-chain-receiver                          receive at X-Chain
--x-chain-sender                            send from X-Chain
--config string                             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string                          log level for the application (default "ERROR")
--skip-update-check                         skip check for new versions
```

<a id="avalanche-network"></a>
## avalanche network

The network command suite provides a collection of tools for managing local Blockchain
deployments.

When you deploy a Blockchain locally, it runs on a local, multi-node Avalanche network. The
blockchain deploy command starts this network in the background. This command suite allows you
to shutdown, restart, and clear that network.

This network currently supports multiple, concurrently deployed Blockchains.

**Usage:**
```bash
avalanche network [subcommand] [flags]
```

**Subcommands:**

- [`clean`](#avalanche-network-clean): The network clean command shuts down your local, multi-node network. All deployed Subnets
shutdown and delete their state. You can restart the network by deploying a new Subnet
configuration.
- [`start`](#avalanche-network-start): The network start command starts a local, multi-node Avalanche network on your machine.

By default, the command loads the default snapshot. If you provide the --snapshot-name
flag, the network loads that snapshot instead. The command fails if the local network is
already running.
- [`status`](#avalanche-network-status): The network status command prints whether or not a local Avalanche
network is running and some basic stats about the network.
- [`stop`](#avalanche-network-stop): The network stop command shuts down your local, multi-node network.

All deployed Subnets shutdown gracefully and save their state. If you provide the
--snapshot-name flag, the network saves its state under this named snapshot. You can
reload this snapshot with network start --snapshot-name `snapshotName`. Otherwise, the
network saves to the default snapshot, overwriting any existing state. You can reload the
default snapshot with network start.

**Flags:**

```bash
-h, --help             help for network
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-network-clean"></a>
### clean

The network clean command shuts down your local, multi-node network. All deployed Subnets
shutdown and delete their state. You can restart the network by deploying a new Subnet
configuration.

**Usage:**
```bash
avalanche network clean [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for clean
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-network-start"></a>
### start

The network start command starts a local, multi-node Avalanche network on your machine.

By default, the command loads the default snapshot. If you provide the --snapshot-name
flag, the network loads that snapshot instead. The command fails if the local network is
already running.

**Usage:**
```bash
avalanche network start [subcommand] [flags]
```

**Flags:**

```bash
--avalanchego-path string       use this avalanchego binary path
--avalanchego-version string    use this version of avalanchego (ex: v1.17.12) (default "latest-prerelease")
-h, --help                      help for start
--num-nodes uint32              number of nodes to be created on local network (default 2)
--relayer-path string           use this relayer binary path
--relayer-version string        use this relayer version (default "latest-prerelease")
--snapshot-name string          name of snapshot to use to start the network from (default "default")
--config string                 config file (default is $HOME/.avalanche-cli/config.json)
--log-level string              log level for the application (default "ERROR")
--skip-update-check             skip check for new versions
```

<a id="avalanche-network-status"></a>
### status

The network status command prints whether or not a local Avalanche
network is running and some basic stats about the network.

**Usage:**
```bash
avalanche network status [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for status
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-network-stop"></a>
### stop

The network stop command shuts down your local, multi-node network.

All deployed Subnets shutdown gracefully and save their state. If you provide the
--snapshot-name flag, the network saves its state under this named snapshot. You can
reload this snapshot with network start --snapshot-name `snapshotName`. Otherwise, the
network saves to the default snapshot, overwriting any existing state. You can reload the
default snapshot with network start.

**Usage:**
```bash
avalanche network stop [subcommand] [flags]
```

**Flags:**

```bash
--dont-save               do not save snapshot, just stop the network
-h, --help                help for stop
--snapshot-name string    name of snapshot to use to save network state into (default "default")
--config string           config file (default is $HOME/.avalanche-cli/config.json)
--log-level string        log level for the application (default "ERROR")
--skip-update-check       skip check for new versions
```

<a id="avalanche-node"></a>
## avalanche node

The node command suite provides a collection of tools for creating and maintaining 
validators on Avalanche Network.

To get started, use the node create command wizard to walk through the
configuration to make your node a primary validator on Avalanche public network. You can use the 
rest of the commands to maintain your node and make your node a Subnet Validator.

**Usage:**
```bash
avalanche node [subcommand] [flags]
```

**Subcommands:**

- [`addDashboard`](#avalanche-node-adddashboard): (ALPHA Warning) This command is currently in experimental mode. 

The node addDashboard command adds custom dashboard to the Grafana monitoring dashboard for the 
cluster.
- [`create`](#avalanche-node-create): (ALPHA Warning) This command is currently in experimental mode. 

The node create command sets up a validator on a cloud server of your choice. 
The validator will be validating the Avalanche Primary Network and Subnet 
of your choice. By default, the command runs an interactive wizard. It 
walks you through all the steps you need to set up a validator.
Once this command is completed, you will have to wait for the validator
to finish bootstrapping on the primary network before running further
commands on it, e.g. validating a Subnet. You can check the bootstrapping
status by running avalanche node status 

The created node will be part of group of validators called `clusterName` 
and users can call node commands with `clusterName` so that the command
will apply to all nodes in the cluster
- [`destroy`](#avalanche-node-destroy): (ALPHA Warning) This command is currently in experimental mode.

The node destroy command terminates all running nodes in cloud server and deletes all storage disks.

If there is a static IP address attached, it will be released.
- [`devnet`](#avalanche-node-devnet): (ALPHA Warning) This command is currently in experimental mode.

The node devnet command suite provides a collection of commands related to devnets.
You can check the updated status by calling avalanche node status `clusterName`
- [`export`](#avalanche-node-export): (ALPHA Warning) This command is currently in experimental mode.

The node export command exports cluster configuration and its nodes config to a text file.

If no file is specified, the configuration is printed to the stdout.

Use --include-secrets to include keys in the export. In this case please keep the file secure as it contains sensitive information.

Exported cluster configuration without secrets can be imported by another user using node import command.
- [`import`](#avalanche-node-import): (ALPHA Warning) This command is currently in experimental mode.

The node import command imports cluster configuration and its nodes configuration from a text file
created from the node export command.

Prior to calling this command, call node whitelist command to have your SSH public key and IP whitelisted by
the cluster owner. This will enable you to use avalanche-cli commands to manage the imported cluster.

Please note, that this imported cluster will be considered as EXTERNAL by avalanche-cli, so some commands
affecting cloud nodes like node create or node destroy will be not applicable to it.
- [`list`](#avalanche-node-list): (ALPHA Warning) This command is currently in experimental mode.

The node list command lists all clusters together with their nodes.
- [`loadtest`](#avalanche-node-loadtest): (ALPHA Warning) This command is currently in experimental mode. 

The node loadtest command suite starts and stops a load test for an existing devnet cluster.
- [`local`](#avalanche-node-local): The node local command suite provides a collection of commands related to local nodes
- [`refresh-ips`](#avalanche-node-refresh-ips): (ALPHA Warning) This command is currently in experimental mode.

The node refresh-ips command obtains the current IP for all nodes with dynamic IPs in the cluster,
and updates the local node information used by CLI commands.
- [`resize`](#avalanche-node-resize): (ALPHA Warning) This command is currently in experimental mode.

The node resize command can change the amount of CPU, memory and disk space available for the cluster nodes.
- [`scp`](#avalanche-node-scp): (ALPHA Warning) This command is currently in experimental mode.

The node scp command securely copies files to and from nodes. Remote source or destionation can be specified using the following format:
[clusterName|nodeID|instanceID|IP]:/path/to/file. Regular expressions are supported for the source files like /tmp/*.txt.
File transfer to the nodes are parallelized. IF source or destination is cluster, the other should be a local file path. 
If both destinations are remote, they must be nodes for the same cluster and not clusters themselves.
For example:
$ avalanche node scp [cluster1|node1]:/tmp/file.txt /tmp/file.txt
$ avalanche node scp /tmp/file.txt [cluster1|NodeID-XXXX]:/tmp/file.txt
$ avalanche node scp node1:/tmp/file.txt NodeID-XXXX:/tmp/file.txt
- [`ssh`](#avalanche-node-ssh): (ALPHA Warning) This command is currently in experimental mode.

The node ssh command execute a given command [cmd] using ssh on all nodes in the cluster if ClusterName is given.
If no command is given, just prints the ssh command to be used to connect to each node in the cluster.
For provided NodeID or InstanceID or IP, the command [cmd] will be executed on that node.
If no [cmd] is provided for the node, it will open ssh shell there.
- [`status`](#avalanche-node-status): (ALPHA Warning) This command is currently in experimental mode.

The node status command gets the bootstrap status of all nodes in a cluster with the Primary Network. 
If no cluster is given, defaults to node list behaviour.

To get the bootstrap status of a node with a Blockchain, use --blockchain flag
- [`sync`](#avalanche-node-sync): (ALPHA Warning) This command is currently in experimental mode.

The node sync command enables all nodes in a cluster to be bootstrapped to a Blockchain.
You can check the blockchain bootstrap status by calling avalanche node status `clusterName` --blockchain `blockchainName`
- [`update`](#avalanche-node-update): (ALPHA Warning) This command is currently in experimental mode.

The node update command suite provides a collection of commands for nodes to update
their avalanchego or VM config.

You can check the status after update by calling avalanche node status
- [`upgrade`](#avalanche-node-upgrade): (ALPHA Warning) This command is currently in experimental mode.

The node update command suite provides a collection of commands for nodes to update
their avalanchego or VM version.

You can check the status after upgrade by calling avalanche node status
- [`validate`](#avalanche-node-validate): (ALPHA Warning) This command is currently in experimental mode.

The node validate command suite provides a collection of commands for nodes to join
the Primary Network and Subnets as validators.
If any of the commands is run before the nodes are bootstrapped on the Primary Network, the command 
will fail. You can check the bootstrap status by calling avalanche node status `clusterName`
- [`whitelist`](#avalanche-node-whitelist): (ALPHA Warning) The whitelist command suite provides a collection of tools for granting access to the cluster.

	Command adds IP if --ip params provided to cloud security access rules allowing it to access all nodes in the cluster via ssh or http.
	It also command adds SSH public key to all nodes in the cluster if --ssh params is there.
	If no params provided it detects current user IP automaticaly and whitelists it

**Flags:**

```bash
-h, --help             help for node
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-node-adddashboard"></a>
### addDashboard

(ALPHA Warning) This command is currently in experimental mode. 

The node addDashboard command adds custom dashboard to the Grafana monitoring dashboard for the 
cluster.

**Usage:**
```bash
avalanche node addDashboard [subcommand] [flags]
```

**Flags:**

```bash
--add-grafana-dashboard string    path to additional grafana dashboard json file
-h, --help                        help for addDashboard
--subnet string                   subnet that the dasbhoard is intended for (if any)
--config string                   config file (default is $HOME/.avalanche-cli/config.json)
--log-level string                log level for the application (default "ERROR")
--skip-update-check               skip check for new versions
```

<a id="avalanche-node-create"></a>
### create

(ALPHA Warning) This command is currently in experimental mode. 

The node create command sets up a validator on a cloud server of your choice. 
The validator will be validating the Avalanche Primary Network and Subnet 
of your choice. By default, the command runs an interactive wizard. It 
walks you through all the steps you need to set up a validator.
Once this command is completed, you will have to wait for the validator
to finish bootstrapping on the primary network before running further
commands on it, e.g. validating a Subnet. You can check the bootstrapping
status by running avalanche node status 

The created node will be part of group of validators called `clusterName` 
and users can call node commands with `clusterName` so that the command
will apply to all nodes in the cluster

**Usage:**
```bash
avalanche node create [subcommand] [flags]
```

**Flags:**

```bash
--add-grafana-dashboard string              path to additional grafana dashboard json file
--alternative-key-pair-name string          key pair name to use if default one generates conflicts
--authorize-access                          authorize CLI to create cloud resources
--auto-replace-keypair                      automatically replaces key pair to access node if previous key pair is not found
--avalanchego-version-from-subnet string    install latest avalanchego version, that is compatible with the given subnet, on node/s
--aws                                       create node/s in AWS cloud
--aws-profile string                        aws profile to use (default "default")
--aws-volume-iops int                       AWS iops (for gp3, io1, and io2 volume types only) (default 3000)
--aws-volume-size int                       AWS volume size in GB (default 1000)
--aws-volume-throughput int                 AWS throughput in MiB/s (for gp3 volume type only) (default 125)
--aws-volume-type string                    AWS volume type (default "gp3")
--bootstrap-ids                             stringArray                nodeIDs of bootstrap nodes
--bootstrap-ips                             stringArray                IP:port pairs of bootstrap nodes
--cluster string                            operate on the given cluster
--custom-avalanchego-version string         install given avalanchego version on node/s
--devnet                                    operate on a devnet network
--enable-monitoring                         set up Prometheus monitoring for created nodes. This option creates a separate monitoring cloud instance and incures additional cost
--endpoint string                           use the given endpoint for network operations
-f, --fuji                                  testnet                             operate on fuji (alias to testnet
--gcp                                       create node/s in GCP cloud
--gcp-credentials string                    use given GCP credentials
--gcp-project string                        use given GCP project
--genesis string                            path to genesis file
--grafana-pkg string                        use grafana pkg instead of apt repo(by default), for example https://dl.grafana.com/oss/release/grafana_10.4.1_amd64.deb
-h, --help                                  help for create
--latest-avalanchego-pre-release-version    install latest avalanchego pre-release version on node/s
--latest-avalanchego-version                install latest avalanchego release version on node/s
-m, --mainnet                               operate on mainnet
--node-type string                          cloud instance type. Use 'default' to use recommended default instance type
--num-apis                                  ints                            number of API nodes(nodes without stake) to create in the new Devnet
--num-validators                            ints                      number of nodes to create per region(s). Use comma to separate multiple numbers for each region in the same order as --region flag
--partial-sync                              primary network partial sync (default true)
--public-http-port                          allow public access to avalanchego HTTP port
--region strings                            create node(s) in given region(s). Use comma to separate multiple regions
--ssh-agent-identity string                 use given ssh identity(only for ssh agent). If not set, default will be used
-t, --testnet                               fuji                             operate on testnet (alias to fuji)
--upgrade string                            path to upgrade file
--use-ssh-agent                             use ssh agent(ex: Yubikey) for ssh auth
--use-static-ip                             attach static Public IP on cloud servers (default true)
--config string                             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string                          log level for the application (default "ERROR")
--skip-update-check                         skip check for new versions
```

<a id="avalanche-node-destroy"></a>
### destroy

(ALPHA Warning) This command is currently in experimental mode.

The node destroy command terminates all running nodes in cloud server and deletes all storage disks.

If there is a static IP address attached, it will be released.

**Usage:**
```bash
avalanche node destroy [subcommand] [flags]
```

**Flags:**

```bash
--all                   destroy all existing clusters created by Avalanche CLI
--authorize-access      authorize CLI to release cloud resources
-y, --authorize-all     authorize all CLI requests
--authorize-remove      authorize CLI to remove all local files related to cloud nodes
--aws-profile string    aws profile to use (default "default")
-h, --help              help for destroy
--config string         config file (default is $HOME/.avalanche-cli/config.json)
--log-level string      log level for the application (default "ERROR")
--skip-update-check     skip check for new versions
```

<a id="avalanche-node-devnet"></a>
### devnet

(ALPHA Warning) This command is currently in experimental mode.

The node devnet command suite provides a collection of commands related to devnets.
You can check the updated status by calling avalanche node status `clusterName`

**Usage:**
```bash
avalanche node devnet [subcommand] [flags]
```

**Subcommands:**

- [`deploy`](#avalanche-node-devnet-deploy): (ALPHA Warning) This command is currently in experimental mode.

The node devnet deploy command deploys a subnet into a devnet cluster, creating subnet and blockchain txs for it.
It saves the deploy info both locally and remotely.
- [`wiz`](#avalanche-node-devnet-wiz): (ALPHA Warning) This command is currently in experimental mode.

The node wiz command creates a devnet and deploys, sync and validate a subnet into it. It creates the subnet if so needed.

**Flags:**

```bash
-h, --help             help for devnet
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-node-devnet-deploy"></a>
#### devnet deploy

(ALPHA Warning) This command is currently in experimental mode.

The node devnet deploy command deploys a subnet into a devnet cluster, creating subnet and blockchain txs for it.
It saves the deploy info both locally and remotely.

**Usage:**
```bash
avalanche node devnet deploy [subcommand] [flags]
```

**Flags:**

```bash
-h, --help                  help for deploy
--no-checks                 do not check for healthy status or rpc compatibility of nodes against subnet
--subnet-aliases strings    additional subnet aliases to be used for RPC calls in addition to subnet blockchain name
--subnet-only               only create a subnet
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check         skip check for new versions
```

<a id="avalanche-node-devnet-wiz"></a>
#### devnet wiz

(ALPHA Warning) This command is currently in experimental mode.

The node wiz command creates a devnet and deploys, sync and validate a subnet into it. It creates the subnet if so needed.

**Usage:**
```bash
avalanche node devnet wiz [subcommand] [flags]
```

**Flags:**

```bash
--add-grafana-dashboard string                         path to additional grafana dashboard json file
--alternative-key-pair-name string                     key pair name to use if default one generates conflicts
--authorize-access                                     authorize CLI to create cloud resources
--auto-replace-keypair                                 automatically replaces key pair to access node if previous key pair is not found
--aws                                                  create node/s in AWS cloud
--aws-profile string                                   aws profile to use (default "default")
--aws-volume-iops int                                  AWS iops (for gp3, io1, and io2 volume types only) (default 3000)
--aws-volume-size int                                  AWS volume size in GB (default 1000)
--aws-volume-throughput int                            AWS throughput in MiB/s (for gp3 volume type only) (default 125)
--aws-volume-type string                               AWS volume type (default "gp3")
--chain-config string                                  path to the chain configuration for subnet
--custom-avalanchego-version string                    install given avalanchego version on node/s
--custom-subnet                                        use a custom VM as the subnet virtual machine
--custom-vm-branch string                              custom vm branch or commit
--custom-vm-build-script string                        custom vm build-script
--custom-vm-repo-url string                            custom vm repository url
--default-validator-params                             use default weight/start/duration params for subnet validator
--deploy-icm-messenger                                 deploy Interchain Messenger (default true)
--deploy-icm-registry                                  deploy Interchain Registry (default true)
--deploy-teleporter-messenger                          deploy Interchain Messenger (default true)
--deploy-teleporter-registry                           deploy Interchain Registry (default true)
--enable-monitoring                                    set up Prometheus monitoring for created nodes. Please note that this option creates a separate monitoring instance and incures additional cost
--evm-chain-id uint                                    chain ID to use with Subnet-EVM
--evm-defaults                                         use default production settings with Subnet-EVM
--evm-production-defaults                              use default production settings for your blockchain
--evm-subnet                                           use Subnet-EVM as the subnet virtual machine
--evm-test-defaults                                    use default test settings for your blockchain
--evm-token string                                     token name to use with Subnet-EVM
--evm-version string                                   version of Subnet-EVM to use
--force-subnet-create                                  overwrite the existing subnet configuration if one exists
--gcp                                                  create node/s in GCP cloud
--gcp-credentials string                               use given GCP credentials
--gcp-project string                                   use given GCP project
--grafana-pkg string                                   use grafana pkg instead of apt repo(by default), for example https://dl.grafana.com/oss/release/grafana_10.4.1_amd64.deb
-h, --help                                             help for wiz
--icm                                                  generate an icm-ready vm
--icm-messenger-contract-address-path string           path to an icm messenger contract address file
--icm-messenger-deployer-address-path string           path to an icm messenger deployer address file
--icm-messenger-deployer-tx-path string                path to an icm messenger deployer tx file
--icm-registry-bytecode-path string                    path to an icm registry bytecode file
--icm-version string                                   icm version to deploy (default "latest")
--latest-avalanchego-pre-release-version               install latest avalanchego pre-release version on node/s
--latest-avalanchego-version                           install latest avalanchego release version on node/s
--latest-evm-version                                   use latest Subnet-EVM released version
--latest-pre-released-evm-version                      use latest Subnet-EVM pre-released version
--node-config string                                   path to avalanchego node configuration for subnet
--node-type string                                     cloud instance type. Use 'default' to use recommended default instance type
--num-apis                                             ints                                       number of API nodes(nodes without stake) to create in the new Devnet
--num-validators                                       ints                                 number of nodes to create per region(s). Use comma to separate multiple numbers for each region in the same order as --region flag
--public-http-port                                     allow public access to avalanchego HTTP port
--region strings                                       create node/s in given region(s). Use comma to separate multiple regions
--relayer                                              run AWM relayer when deploying the vm
--ssh-agent-identity string                            use given ssh identity(only for ssh agent). If not set, default will be used.
--subnet-aliases strings                               additional subnet aliases to be used for RPC calls in addition to subnet blockchain name
--subnet-config string                                 path to the subnet configuration for subnet
--subnet-genesis string                                file path of the subnet genesis
--teleporter                                           generate an icm-ready vm
--teleporter-messenger-contract-address-path string    path to an icm messenger contract address file
--teleporter-messenger-deployer-address-path string    path to an icm messenger deployer address file
--teleporter-messenger-deployer-tx-path string         path to an icm messenger deployer tx file
--teleporter-registry-bytecode-path string             path to an icm registry bytecode file
--teleporter-version string                            icm version to deploy (default "latest")
--use-ssh-agent                                        use ssh agent for ssh
--use-static-ip                                        attach static Public IP on cloud servers (default true)
--validators strings                                   deploy subnet into given comma separated list of validators. defaults to all cluster nodes
--config string                                        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string                                     log level for the application (default "ERROR")
--skip-update-check                                    skip check for new versions
```

<a id="avalanche-node-export"></a>
### export

(ALPHA Warning) This command is currently in experimental mode.

The node export command exports cluster configuration and its nodes config to a text file.

If no file is specified, the configuration is printed to the stdout.

Use --include-secrets to include keys in the export. In this case please keep the file secure as it contains sensitive information.

Exported cluster configuration without secrets can be imported by another user using node import command.

**Usage:**
```bash
avalanche node export [subcommand] [flags]
```

**Flags:**

```bash
--file string          specify the file to export the cluster configuration to
--force                overwrite the file if it exists
-h, --help             help for export
--include-secrets      include keys in the export
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-node-import"></a>
### import

(ALPHA Warning) This command is currently in experimental mode.

The node import command imports cluster configuration and its nodes configuration from a text file
created from the node export command.

Prior to calling this command, call node whitelist command to have your SSH public key and IP whitelisted by
the cluster owner. This will enable you to use avalanche-cli commands to manage the imported cluster.

Please note, that this imported cluster will be considered as EXTERNAL by avalanche-cli, so some commands
affecting cloud nodes like node create or node destroy will be not applicable to it.

**Usage:**
```bash
avalanche node import [subcommand] [flags]
```

**Flags:**

```bash
--file string          specify the file to export the cluster configuration to
-h, --help             help for import
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-node-list"></a>
### list

(ALPHA Warning) This command is currently in experimental mode.

The node list command lists all clusters together with their nodes.

**Usage:**
```bash
avalanche node list [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for list
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-node-loadtest"></a>
### loadtest

(ALPHA Warning) This command is currently in experimental mode. 

The node loadtest command suite starts and stops a load test for an existing devnet cluster.

**Usage:**
```bash
avalanche node loadtest [subcommand] [flags]
```

**Subcommands:**

- [`start`](#avalanche-node-loadtest-start): (ALPHA Warning) This command is currently in experimental mode. 

The node loadtest command starts load testing for an existing devnet cluster. If the cluster does 
not have an existing load test host, the command creates a separate cloud server and builds the load 
test binary based on the provided load test Git Repo URL and load test binary build command. 

The command will then run the load test binary based on the provided load test run command.
- [`stop`](#avalanche-node-loadtest-stop): (ALPHA Warning) This command is currently in experimental mode. 

The node loadtest stop command stops load testing for an existing devnet cluster and terminates the 
separate cloud server created to host the load test.

**Flags:**

```bash
-h, --help             help for loadtest
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-node-loadtest-start"></a>
#### loadtest start

(ALPHA Warning) This command is currently in experimental mode. 

The node loadtest command starts load testing for an existing devnet cluster. If the cluster does 
not have an existing load test host, the command creates a separate cloud server and builds the load 
test binary based on the provided load test Git Repo URL and load test binary build command. 

The command will then run the load test binary based on the provided load test run command.

**Usage:**
```bash
avalanche node loadtest start [subcommand] [flags]
```

**Flags:**

```bash
--authorize-access              authorize CLI to create cloud resources
--aws                           create loadtest node in AWS cloud
--aws-profile string            aws profile to use (default "default")
--gcp                           create loadtest in GCP cloud
-h, --help                      help for start
--load-test-branch string       load test branch or commit
--load-test-build-cmd string    command to build load test binary
--load-test-cmd string          command to run load test
--load-test-repo string         load test repo url to use
--node-type string              cloud instance type for loadtest script
--region string                 create load test node in a given region
--ssh-agent-identity string     use given ssh identity(only for ssh agent). If not set, default will be used
--use-ssh-agent                 use ssh agent(ex: Yubikey) for ssh auth
--config string                 config file (default is $HOME/.avalanche-cli/config.json)
--log-level string              log level for the application (default "ERROR")
--skip-update-check             skip check for new versions
```

<a id="avalanche-node-loadtest-stop"></a>
#### loadtest stop

(ALPHA Warning) This command is currently in experimental mode. 

The node loadtest stop command stops load testing for an existing devnet cluster and terminates the 
separate cloud server created to host the load test.

**Usage:**
```bash
avalanche node loadtest stop [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for stop
--load-test strings    stop specified load test node(s). Use comma to separate multiple load test instance names
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-node-local"></a>
### local

The node local command suite provides a collection of commands related to local nodes

**Usage:**
```bash
avalanche node local [subcommand] [flags]
```

**Subcommands:**

- [`destroy`](#avalanche-node-local-destroy): Cleanup local node.
- [`start`](#avalanche-node-local-start): The node local start command creates Avalanche nodes on the local machine.
Once this command is completed, you will have to wait for the Avalanche node
to finish bootstrapping on the primary network before running further
commands on it, e.g. validating a Subnet. 

You can check the bootstrapping status by running avalanche node status local.
- [`status`](#avalanche-node-local-status): Get status of local node.
- [`stop`](#avalanche-node-local-stop): Stop local node.
- [`track`](#avalanche-node-local-track): Track specified blockchain with local node
- [`validate`](#avalanche-node-local-validate): Use Avalanche Node set up on local machine to set up specified L1 by providing the
RPC URL of the L1. 

This command can only be used to validate Proof of Stake L1.

**Flags:**

```bash
-h, --help             help for local
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-node-local-destroy"></a>
#### local destroy

Cleanup local node.

**Usage:**
```bash
avalanche node local destroy [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for destroy
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-node-local-start"></a>
#### local start

The node local start command creates Avalanche nodes on the local machine.
Once this command is completed, you will have to wait for the Avalanche node
to finish bootstrapping on the primary network before running further
commands on it, e.g. validating a Subnet. 

You can check the bootstrapping status by running avalanche node status local.

**Usage:**
```bash
avalanche node local start [subcommand] [flags]
```

**Flags:**

```bash
--avalanchego-path string                   use this avalanchego binary path
--bootstrap-id                              stringArray                 nodeIDs of bootstrap nodes
--bootstrap-ip                              stringArray                 IP:port pairs of bootstrap nodes
--cluster string                            operate on the given cluster
--custom-avalanchego-version string         install given avalanchego version on node/s
--devnet                                    operate on a devnet network
--endpoint string                           use the given endpoint for network operations
-f, --fuji                                  testnet                             operate on fuji (alias to testnet
--genesis string                            path to genesis file
-h, --help                                  help for start
--latest-avalanchego-pre-release-version    install latest avalanchego pre-release version on node/s (default true)
--latest-avalanchego-version                install latest avalanchego release version on node/s
-l, --local                                 operate on a local network
-m, --mainnet                               operate on mainnet
--node-config string                        path to common avalanchego config settings for all nodes
--num-nodes uint32                          number of Avalanche nodes to create on local machine (default 1)
--partial-sync                              primary network partial sync (default true)
--staking-cert-key-path string              path to provided staking cert key for node
--staking-signer-key-path string            path to provided staking signer key for node
--staking-tls-key-path string               path to provided staking tls key for node
-t, --testnet                               fuji                             operate on testnet (alias to fuji)
--upgrade string                            path to upgrade file
--config string                             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string                          log level for the application (default "ERROR")
--skip-update-check                         skip check for new versions
```

<a id="avalanche-node-local-status"></a>
#### local status

Get status of local node.

**Usage:**
```bash
avalanche node local status [subcommand] [flags]
```

**Flags:**

```bash
--blockchain string    specify the blockchain the node is syncing with
-h, --help             help for status
--l1 string            specify the blockchain the node is syncing with
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-node-local-stop"></a>
#### local stop

Stop local node.

**Usage:**
```bash
avalanche node local stop [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for stop
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-node-local-track"></a>
#### local track

Track specified blockchain with local node

**Usage:**
```bash
avalanche node local track [subcommand] [flags]
```

**Flags:**

```bash
--avalanchego-path string                   use this avalanchego binary path
--custom-avalanchego-version string         install given avalanchego version on node/s
-h, --help                                  help for track
--latest-avalanchego-pre-release-version    install latest avalanchego pre-release version on node/s (default true)
--latest-avalanchego-version                install latest avalanchego release version on node/s
--config string                             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string                          log level for the application (default "ERROR")
--skip-update-check                         skip check for new versions
```

<a id="avalanche-node-local-validate"></a>
#### local validate

Use Avalanche Node set up on local machine to set up specified L1 by providing the
RPC URL of the L1. 

This command can only be used to validate Proof of Stake L1.

**Usage:**
```bash
avalanche node local validate [subcommand] [flags]
```

**Flags:**

```bash
--aggregator-log-level string       log level to use with signature aggregator (default "Debug")
--aggregator-log-to-stdout          use stdout for signature aggregator logs
--balance float                     amount of AVAX to increase validator's balance by
--blockchain string                 specify the blockchain the node is syncing with
--delegation-fee uint16             delegation fee (in bips) (default 100)
--disable-owner string              P-Chain address that will able to disable the validator with a P-Chain transaction
-h, --help                          help for validate
--l1 string                         specify the blockchain the node is syncing with
--minimum-stake-duration uint       minimum stake duration (in seconds) (default 100)
--remaining-balance-owner string    P-Chain address that will receive any leftover AVAX from the validator when it is removed from Subnet
--rpc string                        connect to validator manager at the given rpc endpoint
--stake-amount uint                 amount of tokens to stake
--config string                     config file (default is $HOME/.avalanche-cli/config.json)
--log-level string                  log level for the application (default "ERROR")
--skip-update-check                 skip check for new versions
```

<a id="avalanche-node-refresh-ips"></a>
### refresh-ips

(ALPHA Warning) This command is currently in experimental mode.

The node refresh-ips command obtains the current IP for all nodes with dynamic IPs in the cluster,
and updates the local node information used by CLI commands.

**Usage:**
```bash
avalanche node refresh-ips [subcommand] [flags]
```

**Flags:**

```bash
--aws-profile string    aws profile to use (default "default")
-h, --help              help for refresh-ips
--config string         config file (default is $HOME/.avalanche-cli/config.json)
--log-level string      log level for the application (default "ERROR")
--skip-update-check     skip check for new versions
```

<a id="avalanche-node-resize"></a>
### resize

(ALPHA Warning) This command is currently in experimental mode.

The node resize command can change the amount of CPU, memory and disk space available for the cluster nodes.

**Usage:**
```bash
avalanche node resize [subcommand] [flags]
```

**Flags:**

```bash
--aws-profile string    aws profile to use (default "default")
--disk-size string      Disk size to resize in Gb (e.g. 1000Gb)
-h, --help              help for resize
--node-type string      Node type to resize (e.g. t3.2xlarge)
--config string         config file (default is $HOME/.avalanche-cli/config.json)
--log-level string      log level for the application (default "ERROR")
--skip-update-check     skip check for new versions
```

<a id="avalanche-node-scp"></a>
### scp

(ALPHA Warning) This command is currently in experimental mode.

The node scp command securely copies files to and from nodes. Remote source or destionation can be specified using the following format:
[clusterName|nodeID|instanceID|IP]:/path/to/file. Regular expressions are supported for the source files like /tmp/*.txt.
File transfer to the nodes are parallelized. IF source or destination is cluster, the other should be a local file path. 
If both destinations are remote, they must be nodes for the same cluster and not clusters themselves.
For example:
$ avalanche node scp [cluster1|node1]:/tmp/file.txt /tmp/file.txt
$ avalanche node scp /tmp/file.txt [cluster1|NodeID-XXXX]:/tmp/file.txt
$ avalanche node scp node1:/tmp/file.txt NodeID-XXXX:/tmp/file.txt

**Usage:**
```bash
avalanche node scp [subcommand] [flags]
```

**Flags:**

```bash
--compress             use compression for ssh
-h, --help             help for scp
--recursive            copy directories recursively
--with-loadtest        include loadtest node for scp cluster operations
--with-monitor         include monitoring node for scp cluster operations
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-node-ssh"></a>
### ssh

(ALPHA Warning) This command is currently in experimental mode.

The node ssh command execute a given command [cmd] using ssh on all nodes in the cluster if ClusterName is given.
If no command is given, just prints the ssh command to be used to connect to each node in the cluster.
For provided NodeID or InstanceID or IP, the command [cmd] will be executed on that node.
If no [cmd] is provided for the node, it will open ssh shell there.

**Usage:**
```bash
avalanche node ssh [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for ssh
--parallel             run ssh command on all nodes in parallel
--with-loadtest        include loadtest node for ssh cluster operations
--with-monitor         include monitoring node for ssh cluster operations
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-node-status"></a>
### status

(ALPHA Warning) This command is currently in experimental mode.

The node status command gets the bootstrap status of all nodes in a cluster with the Primary Network. 
If no cluster is given, defaults to node list behaviour.

To get the bootstrap status of a node with a Blockchain, use --blockchain flag

**Usage:**
```bash
avalanche node status [subcommand] [flags]
```

**Flags:**

```bash
--blockchain string    specify the blockchain the node is syncing with
-h, --help             help for status
--subnet string        specify the blockchain the node is syncing with
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-node-sync"></a>
### sync

(ALPHA Warning) This command is currently in experimental mode.

The node sync command enables all nodes in a cluster to be bootstrapped to a Blockchain.
You can check the blockchain bootstrap status by calling avalanche node status `clusterName` --blockchain `blockchainName`

**Usage:**
```bash
avalanche node sync [subcommand] [flags]
```

**Flags:**

```bash
-h, --help                  help for sync
--no-checks                 do not check for bootstrapped/healthy status or rpc compatibility of nodes against subnet
--subnet-aliases strings    subnet alias to be used for RPC calls. defaults to subnet blockchain ID
--validators strings        sync subnet into given comma separated list of validators. defaults to all cluster nodes
--config string             config file (default is $HOME/.avalanche-cli/config.json)
--log-level string          log level for the application (default "ERROR")
--skip-update-check         skip check for new versions
```

<a id="avalanche-node-update"></a>
### update

(ALPHA Warning) This command is currently in experimental mode.

The node update command suite provides a collection of commands for nodes to update
their avalanchego or VM config.

You can check the status after update by calling avalanche node status

**Usage:**
```bash
avalanche node update [subcommand] [flags]
```

**Subcommands:**

- [`subnet`](#avalanche-node-update-subnet): (ALPHA Warning) This command is currently in experimental mode.

The node update subnet command updates all nodes in a cluster with latest Subnet configuration and VM for custom VM.
You can check the updated subnet bootstrap status by calling avalanche node status `clusterName` --subnet `subnetName`

**Flags:**

```bash
-h, --help             help for update
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-node-update-subnet"></a>
#### update subnet

(ALPHA Warning) This command is currently in experimental mode.

The node update subnet command updates all nodes in a cluster with latest Subnet configuration and VM for custom VM.
You can check the updated subnet bootstrap status by calling avalanche node status `clusterName` --subnet `subnetName`

**Usage:**
```bash
avalanche node update subnet [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for subnet
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-node-upgrade"></a>
### upgrade

(ALPHA Warning) This command is currently in experimental mode.

The node update command suite provides a collection of commands for nodes to update
their avalanchego or VM version.

You can check the status after upgrade by calling avalanche node status

**Usage:**
```bash
avalanche node upgrade [subcommand] [flags]
```

**Flags:**

```bash
-h, --help             help for upgrade
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-node-validate"></a>
### validate

(ALPHA Warning) This command is currently in experimental mode.

The node validate command suite provides a collection of commands for nodes to join
the Primary Network and Subnets as validators.
If any of the commands is run before the nodes are bootstrapped on the Primary Network, the command 
will fail. You can check the bootstrap status by calling avalanche node status `clusterName`

**Usage:**
```bash
avalanche node validate [subcommand] [flags]
```

**Subcommands:**

- [`primary`](#avalanche-node-validate-primary): (ALPHA Warning) This command is currently in experimental mode.

The node validate primary command enables all nodes in a cluster to be validators of Primary
Network.
- [`subnet`](#avalanche-node-validate-subnet): (ALPHA Warning) This command is currently in experimental mode.

The node validate subnet command enables all nodes in a cluster to be validators of a Subnet.
If the command is run before the nodes are Primary Network validators, the command will first
make the nodes Primary Network validators before making them Subnet validators. 
If The command is run before the nodes are bootstrapped on the Primary Network, the command will fail. 
You can check the bootstrap status by calling avalanche node status `clusterName`
If The command is run before the nodes are synced to the subnet, the command will fail.
You can check the subnet sync status by calling avalanche node status `clusterName` --subnet `subnetName`

**Flags:**

```bash
-h, --help             help for validate
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-node-validate-primary"></a>
#### validate primary

(ALPHA Warning) This command is currently in experimental mode.

The node validate primary command enables all nodes in a cluster to be validators of Primary
Network.

**Usage:**
```bash
avalanche node validate primary [subcommand] [flags]
```

**Flags:**

```bash
-e, --ewoq                   use ewoq key [fuji/devnet only]
-h, --help                   help for primary
-k, --key string             select the key to use [fuji only]
-g, --ledger                 use ledger instead of key (always true on mainnet, defaults to false on fuji/devnet)
--ledger-addrs strings       use the given ledger addresses
--stake-amount uint          how many AVAX to stake in the validator
--staking-period duration    how long validator validates for after start time
--start-time string          UTC start time when this validator starts validating, in 'YYYY-MM-DD HH:MM:SS' format
--config string              config file (default is $HOME/.avalanche-cli/config.json)
--log-level string           log level for the application (default "ERROR")
--skip-update-check          skip check for new versions
```

<a id="avalanche-node-validate-subnet"></a>
#### validate subnet

(ALPHA Warning) This command is currently in experimental mode.

The node validate subnet command enables all nodes in a cluster to be validators of a Subnet.
If the command is run before the nodes are Primary Network validators, the command will first
make the nodes Primary Network validators before making them Subnet validators. 
If The command is run before the nodes are bootstrapped on the Primary Network, the command will fail. 
You can check the bootstrap status by calling avalanche node status `clusterName`
If The command is run before the nodes are synced to the subnet, the command will fail.
You can check the subnet sync status by calling avalanche node status `clusterName` --subnet `subnetName`

**Usage:**
```bash
avalanche node validate subnet [subcommand] [flags]
```

**Flags:**

```bash
--default-validator-params    use default weight/start/duration params for subnet validator
-e, --ewoq                    use ewoq key [fuji/devnet only]
-h, --help                    help for subnet
-k, --key string              select the key to use [fuji/devnet only]
-g, --ledger                  use ledger instead of key (always true on mainnet, defaults to false on fuji/devnet)
--ledger-addrs strings        use the given ledger addresses
--no-checks                   do not check for bootstrapped status or healthy status
--no-validation-checks        do not check if subnet is already synced or validated (default true)
--stake-amount uint           how many AVAX to stake in the validator
--staking-period duration     how long validator validates for after start time
--start-time string           UTC start time when this validator starts validating, in 'YYYY-MM-DD HH:MM:SS' format
--validators strings          validate subnet for the given comma separated list of validators. defaults to all cluster nodes
--config string               config file (default is $HOME/.avalanche-cli/config.json)
--log-level string            log level for the application (default "ERROR")
--skip-update-check           skip check for new versions
```

<a id="avalanche-node-whitelist"></a>
### whitelist

(ALPHA Warning) The whitelist command suite provides a collection of tools for granting access to the cluster.

	Command adds IP if --ip params provided to cloud security access rules allowing it to access all nodes in the cluster via ssh or http.
	It also command adds SSH public key to all nodes in the cluster if --ssh params is there.
	If no params provided it detects current user IP automaticaly and whitelists it

**Usage:**
```bash
avalanche node whitelist [subcommand] [flags]
```

**Flags:**

```bash
-y, --current-ip       whitelist current host ip
-h, --help             help for whitelist
--ip string            ip address to whitelist
--ssh string           ssh public key to whitelist
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-primary"></a>
## avalanche primary

The primary command suite provides a collection of tools for interacting with the
Primary Network

**Usage:**
```bash
avalanche primary [subcommand] [flags]
```

**Subcommands:**

- [`addValidator`](#avalanche-primary-addvalidator): The primary addValidator command adds a node as a validator 
in the Primary Network
- [`describe`](#avalanche-primary-describe): The subnet describe command prints details of the primary network configuration to the console.

**Flags:**

```bash
-h, --help             help for primary
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-primary-addvalidator"></a>
### addValidator

The primary addValidator command adds a node as a validator 
in the Primary Network

**Usage:**
```bash
avalanche primary addValidator [subcommand] [flags]
```

**Flags:**

```bash
--cluster string                operate on the given cluster
--delegation-fee uint32         set the delegation fee (20 000 is equivalent to 2%)
--devnet                        operate on a devnet network
--endpoint string               use the given endpoint for network operations
-f, --fuji                      testnet                 operate on fuji (alias to testnet
-h, --help                      help for addValidator
-k, --key string                select the key to use [fuji only]
-g, --ledger                    use ledger instead of key (always true on mainnet, defaults to false on fuji)
--ledger-addrs strings          use the given ledger addresses
-m, --mainnet                   operate on mainnet
--nodeID string                 set the NodeID of the validator to add
--proof-of-possession string    set the BLS proof of possession of the validator to add
--public-key string             set the BLS public key of the validator to add
--staking-period duration       how long this validator will be staking
--start-time string             UTC start time when this validator starts validating, in 'YYYY-MM-DD HH:MM:SS' format
-t, --testnet                   fuji                 operate on testnet (alias to fuji)
--weight uint                   set the staking weight of the validator to add
--config string                 config file (default is $HOME/.avalanche-cli/config.json)
--log-level string              log level for the application (default "ERROR")
--skip-update-check             skip check for new versions
```

<a id="avalanche-primary-describe"></a>
### describe

The subnet describe command prints details of the primary network configuration to the console.

**Usage:**
```bash
avalanche primary describe [subcommand] [flags]
```

**Flags:**

```bash
--cluster string       operate on the given cluster
-h, --help             help for describe
-l, --local            operate on a local network
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-transaction"></a>
## avalanche transaction

The transaction command suite provides all of the utilities required to sign multisig transactions.

**Usage:**
```bash
avalanche transaction [subcommand] [flags]
```

**Subcommands:**

- [`commit`](#avalanche-transaction-commit): The transaction commit command commits a transaction by submitting it to the P-Chain.
- [`sign`](#avalanche-transaction-sign): The transaction sign command signs a multisig transaction.

**Flags:**

```bash
-h, --help             help for transaction
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-transaction-commit"></a>
### commit

The transaction commit command commits a transaction by submitting it to the P-Chain.

**Usage:**
```bash
avalanche transaction commit [subcommand] [flags]
```

**Flags:**

```bash
-h, --help                    help for commit
--input-tx-filepath string    Path to the transaction signed by all signatories
--config string               config file (default is $HOME/.avalanche-cli/config.json)
--log-level string            log level for the application (default "ERROR")
--skip-update-check           skip check for new versions
```

<a id="avalanche-transaction-sign"></a>
### sign

The transaction sign command signs a multisig transaction.

**Usage:**
```bash
avalanche transaction sign [subcommand] [flags]
```

**Flags:**

```bash
-h, --help                    help for sign
--input-tx-filepath string    Path to the transaction file for signing
-k, --key string              select the key to use [fuji only]
-g, --ledger                  use ledger instead of key (always true on mainnet, defaults to false on fuji)
--ledger-addrs strings        use the given ledger addresses
--config string               config file (default is $HOME/.avalanche-cli/config.json)
--log-level string            log level for the application (default "ERROR")
--skip-update-check           skip check for new versions
```

<a id="avalanche-update"></a>
## avalanche update

Check if an update is available, and prompt the user to install it

**Usage:**
```bash
avalanche update [subcommand] [flags]
```

**Flags:**

```bash
-c, --confirm          Assume yes for installation
-h, --help             help for update
-v, --version          version for update
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-validator"></a>
## avalanche validator

The validator command suite provides a collection of tools for managing validator
balance on P-Chain.

Validator's balance is used to pay for continuous fee to the P-Chain. When this Balance reaches 0, 
the validator will be considered inactive and will no longer participate in validating the L1

**Usage:**
```bash
avalanche validator [subcommand] [flags]
```

**Subcommands:**

- [`getBalance`](#avalanche-validator-getbalance): This command gets the remaining validator P-Chain balance that is available to pay
P-Chain continuous fee
- [`increaseBalance`](#avalanche-validator-increasebalance): This command increases the validator P-Chain balance
- [`list`](#avalanche-validator-list): This command gets a list of the validators of the L1

**Flags:**

```bash
-h, --help             help for validator
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

<a id="avalanche-validator-getbalance"></a>
### getBalance

This command gets the remaining validator P-Chain balance that is available to pay
P-Chain continuous fee

**Usage:**
```bash
avalanche validator getBalance [subcommand] [flags]
```

**Flags:**

```bash
--cluster string          operate on the given cluster
--devnet                  operate on a devnet network
--endpoint string         use the given endpoint for network operations
-f, --fuji                testnet           operate on fuji (alias to testnet
-h, --help                help for getBalance
--l1 string               name of L1
-l, --local               operate on a local network
-m, --mainnet             operate on mainnet
--node-id string          node ID of the validator
-t, --testnet             fuji           operate on testnet (alias to fuji)
--validation-id string    validation ID of the validator
--config string           config file (default is $HOME/.avalanche-cli/config.json)
--log-level string        log level for the application (default "ERROR")
--skip-update-check       skip check for new versions
```

<a id="avalanche-validator-increasebalance"></a>
### increaseBalance

This command increases the validator P-Chain balance

**Usage:**
```bash
avalanche validator increaseBalance [subcommand] [flags]
```

**Flags:**

```bash
--balance float           amount of AVAX to increase validator's balance by
--cluster string          operate on the given cluster
--devnet                  operate on a devnet network
--endpoint string         use the given endpoint for network operations
-f, --fuji                testnet           operate on fuji (alias to testnet
-h, --help                help for increaseBalance
-k, --key string          select the key to use [fuji/devnet deploy only]
--l1 string               name of L1 (to increase balance of bootstrap validators only)
-l, --local               operate on a local network
-m, --mainnet             operate on mainnet
--node-id string          node ID of the validator
-t, --testnet             fuji           operate on testnet (alias to fuji)
--validation-id string    validationIDStr of the validator
--config string           config file (default is $HOME/.avalanche-cli/config.json)
--log-level string        log level for the application (default "ERROR")
--skip-update-check       skip check for new versions
```

<a id="avalanche-validator-list"></a>
### list

This command gets a list of the validators of the L1

**Usage:**
```bash
avalanche validator list [subcommand] [flags]
```

**Flags:**

```bash
--cluster string       operate on the given cluster
--devnet               operate on a devnet network
--endpoint string      use the given endpoint for network operations
-f, --fuji             testnet      operate on fuji (alias to testnet
-h, --help             help for list
-l, --local            operate on a local network
-m, --mainnet          operate on mainnet
-t, --testnet          fuji      operate on testnet (alias to fuji)
--config string        config file (default is $HOME/.avalanche-cli/config.json)
--log-level string     log level for the application (default "ERROR")
--skip-update-check    skip check for new versions
```

# Create Avalanche L1 (/docs/tooling/avalanche-cli/create-avalanche-l1)

---
title: Create Avalanche L1
description: This page demonstrates how to create an Avalanche L1 using Avalanche-CLI.
---

This tutorial walks you through the process of using Avalanche-CLI to create an Avalanche L1, deploy it to a local network, and connect to it with Core wallet.

The first step of learning Avalanche L1 development is learning to use [Avalanche-CLI](https://github.com/ava-labs/avalanche-cli).

Installation[​](#installation "Direct link to heading")
-------------------------------------------------------

The fastest way to install the latest Avalanche-CLI binary is by running the install script:

```bash
curl -sSfL https://raw.githubusercontent.com/ava-labs/avalanche-cli/main/scripts/install.sh | sh -s
```

The binary installs inside the `~/bin` directory. If the directory doesn't exist, it will be created.

You can run all of the commands in this tutorial by calling `~/bin/avalanche`.

You can also add the command to your system path by running:

```bash
export PATH=~/bin:$PATH
```

To make this change permanent, add this line to your shell’s initialization file (e.g., `~/.bashrc` or `~/.zshrc`). For example:

```bash
echo 'export PATH=~/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
```

Once you add it to your path, you should be able to call the program anywhere with just: `avalanche`

For more detailed installation instructions, see [Avalanche-CLI Installation](/docs/tooling/get-avalanche-cli).

Create Your Avalanche L1 Configuration[​](#create-your-avalanche-l1-configuration "Direct link to heading")
-----------------------------------------------------------------------------------------------

This tutorial teaches you how to create an Ethereum Virtual Machine (EVM) based Avalanche L1. To do so, you use Subnet-EVM, Avalanche's L1 fork of the EVM. It supports airdrops, custom fee tokens, configurable gas parameters, and multiple stateful precompiles. To learn more, take a look at [Subnet-EVM](https://github.com/ava-labs/subnet-evm). The goal of your first command is to create a Subnet-EVM configuration.

The `avalanche-cli` command suite provides a collection of tools for developing and deploying Avalanche L1s.

The Creation Wizard walks you through the process of creating your Avalanche L1. To get started, first pick a name for your Avalanche L1. This tutorial uses `myblockchain`, but feel free to substitute that with any name you like. Once you've picked your name, run:

```bash
avalanche blockchain create myblockchain
```

The following sections walk through each question in the wizard.

### Choose Your VM

```bash
? Which Virtual Machine would you like to use?: 
  ▸ Subnet-EVM
    Custom VM
    Explain the difference
```
Select `Subnet-EVM`.

### Choose Validator Manager

```text
? Which validator management type would you like to use in your blockchain?: 
  ▸ Proof Of Authority
    Proof Of Stake
    Explain the difference
```
Select `Proof Of Authority`.

```text
? Which address do you want to enable as controller of ValidatorManager contract?: 
  ▸ Get address from an existing stored key (created from avalanche key create or avalanche key import)
    Custom
```
Select `Get address from an existing stored key`.

```text
? Which stored key should be used enable as controller of ValidatorManager contract?: 
  ▸ ewoq
    cli-awm-relayer
    cli-teleporter-deployer
```
Select `ewoq`.

This key is used to manage (add/remove) the validator set.

<Callout>
Do not use EWOQ key in a testnet or production setup. The EWOQ private key is publicly exposed.
</Callout>

To learn more about different validator management types, see [PoA vs PoS](/docs/avalanche-l1s/validator-manager/poa-vs-pos).

### Choose Blockchain Configuration

```text
? Do you want to use default values for the Blockchain configuration?: 
  ▸ I want to use defaults for a test environment
    I want to use defaults for a production environment
    I don't want to use default values
    Explain the difference
```

Select `I want to use defaults for a test environment`.
This will automatically setup the configuration for a test environment, including an airdrop to the EWOQ key and Avalanche ICM.

### Enter Your Avalanche L1's ChainID

```text
✗ Chain ID: 
```

Choose a positive integer for your EVM-style ChainID.

In production environments, this ChainID needs to be unique and not shared with any other chain. You can visit [chainlist](https://chainlist.org/) to verify that your selection is unique. Because this is a development Avalanche L1, feel free to pick any number. Stay away from well-known ChainIDs such as 1 (Ethereum) or 43114 (Avalanche C-Chain) as those may cause issues with other tools.

### Token Symbol

```text
✗ Token Symbol: 
```

Enter a string to name your Avalanche L1's native token. The token symbol doesn't necessarily need to be unique. Example token symbols are AVAX, JOE, and BTC.

### Wrapping Up

If all worked successfully, the command prints:
```bash
✓ Successfully created blockchain configuration
```

To view the Genesis configuration, use the following command:
```bash
avalanche blockchain describe myblockchain --genesis
```

You've successfully created your first Avalanche L1 configuration. Now it's time to deploy it.


# Installation (/docs/tooling/avalanche-cli/get-avalanche-cli)

---
title: Installation
description: Instructions for installing and setting up the Avalanche-CLI.
---

## Compatibility

Avalanche-CLI runs on Linux and Mac. Windows is currently not supported.

## Instructions

To download a binary for the latest release, run:

```bash
curl -sSfL https://raw.githubusercontent.com/ava-labs/avalanche-cli/main/scripts/install.sh | sh -s
```

The script installs the binary inside the `~/bin` directory. If the directory doesn't exist, it will be created.

## Adding Avalanche-CLI to Your PATH

To call the `avalanche` binary from anywhere, you'll need to add it to your system path. If you installed the binary into the default location, you can run the following snippet to add it to your path.

To add it to your path permanently, add an export command to your shell initialization script. If you run `bash`, use `.bashrc`. If you run `zsh`, use `.zshrc`.

For example:

```bash
export PATH=~/bin:$PATH >> .bashrc
```

## Checking Your Installation

You can test your installation by running `avalanche --version`. The tool should print the running version.

## Updating

To update your installation, you need to delete your current binary and download the latest version using the preceding steps.

## Building from Source

The source code is available in this [GitHub repository](https://github.com/ava-labs/avalanche-cli).

After you've cloned the repository, checkout the tag you'd like to run. You can compile the code by running `./scripts/build.sh` from the top level directory.

The build script names the binary `./bin/avalanche`.

# Avalanche-CLI Overview (/docs/tooling/avalanche-cli)

---
title: Avalanche-CLI Overview
description: Build, deploy, and manage Avalanche L1s with the Avalanche-CLI
---

The Avalanche-CLI is a powerful command-line tool that streamlines the process of building, deploying, and managing Avalanche L1 blockchains (formerly known as Subnets).

## Key Features

- **Create & Deploy L1s**: Quickly create and deploy new Avalanche L1 blockchains to local, testnet, or mainnet environments
- **VM Management**: Deploy L1s with Subnet-EVM or custom Virtual Machines
- **Node Operations**: Run and manage validator nodes across different cloud providers
- **Cross-Chain Messaging**: Set up Teleporter for cross-chain communication
- **Transaction Management**: Handle native token transfers and P-Chain operations

## Getting Started

To get started with Avalanche-CLI:

1. [Install Avalanche-CLI](/docs/tooling/avalanche-cli/get-avalanche-cli) on your system
2. Review the [CLI Commands Reference](/docs/tooling/avalanche-cli/cli-commands) for available commands
3. Follow the guide to [Create an Avalanche L1](/docs/tooling/avalanche-cli/create-avalanche-l1)

## Quick Links

<Cards>
  <Card title="Installation" href="/docs/tooling/avalanche-cli/get-avalanche-cli">
    Get Avalanche-CLI installed on your system
  </Card>
  <Card title="Create L1s" href="/docs/tooling/avalanche-cli/create-avalanche-l1">
    Learn how to create your first Avalanche L1
  </Card>
  <Card title="Deploy L1s" href="/docs/tooling/avalanche-cli/create-deploy-avalanche-l1s">
    Deploy L1s to various environments
  </Card>
  <Card title="CLI Reference" href="/docs/tooling/avalanche-cli/cli-commands">
    Complete reference for all CLI commands
  </Card>
</Cards>

## Common Use Cases

### Local Development
Deploy and test your L1 locally before moving to testnet or mainnet.

### Production Deployment
Deploy L1s to Fuji testnet for testing, then to mainnet for production use.

### Validator Management
Add and remove validators, manage staking, and monitor node health.

### Cross-Chain Integration
Enable cross-chain messaging between your L1 and other chains using Teleporter.

## Support

- [GitHub Repository](https://github.com/ava-labs/avalanche-cli)
- [Discord Community](https://chat.avalabs.org/)
- [Documentation](https://docs.avax.network/)


# Data Visualization (/docs/tooling/avalanche-postman/data-visualization)

---
title: Data Visualization
description: Data visualization for Avalanche APIs using Postman
---

Data visualization is available for a number of API calls whose responses are transformed and presented in tabular format for easy reference.

Please check out [Installing Postman Collection](/docs/tooling/avalanche-postman/index) and [Making API Calls](/docs/tooling/avalanche-postman/making-api-calls) beforehand, as this guide assumes that the user has already gone through these steps.

Data visualizations are available for following API calls:

### C-Chain[​](#c-chain "Direct link to heading")

- [`eth_baseFee`](/docs/api-reference/c-chain/api#eth_basefee)
- [`eth_blockNumber`](https://www.quicknode.com/docs/ethereum/eth_blockNumber)
- [`eth_chainId`](https://www.quicknode.com/docs/ethereum/eth_chainId)
- [`eth_getBalance`](https://www.quicknode.com/docs/ethereum/eth_getBalance)
- [`eth_getBlockByHash`](https://www.quicknode.com/docs/ethereum/eth_getBlockByHash)
- [`eth_getBlockByNumber`](https://www.quicknode.com/docs/ethereum/eth_getBlockByNumber)
- [`eth_getTransactionByHash`](https://www.quicknode.com/docs/ethereum/eth_getTransactionByHash)
- [`eth_getTransactionReceipt`](https://www.quicknode.com/docs/ethereum/eth_getTransactionReceipt)
- [`avax.getAtomicTx`](/docs/api-reference/c-chain/api#avaxgetatomictx)

### P-Chain[​](#p-chain "Direct link to heading")

- [`platform.getCurrentValidators`](/docs/api-reference/p-chain/api#platformgetcurrentvalidators)

### X-Chain[​](#x-chain "Direct link to heading")

- [`avm.getAssetDescription`](/docs/api-reference/x-chain/api#avmgetassetdescription)
- [`avm.getBlock`](/docs/api-reference/x-chain/api#avmgetblock)
- [`avm.getBlockByHeight`](/docs/api-reference/x-chain/api#avmgetblockbyheight)
- [`avm.getTx`](/docs/api-reference/x-chain/api#avmgettx)

<YouTube id="2jS5EFWLoGs" fullSize={false}/>

Data Visualization Features[​](#data-visualization-features "Direct link to heading")
-------------------------------------------------------------------------------------

- The response output is displayed in tabular format, each data category having a different color.

![Data Visualization Feature](/images/visualize1.png)

- Unix timestamps are converted to date and time.

![Data Visualization Feature](/images/visualize2.png)

- Hexadecimal to decimal conversions.

![Data Visualization Feature](/images/visualize3.png)

- Native token amounts shown as AVAX and/or gwei and wei.

![Data Visualization Feature](/images/visualize4.png)

- The name of the transaction type added besides the transaction type ID.

![Data Visualization Feature](/images/visualize5.png)

- Percentages added for the amount of gas used. This percent represents what percentage of gas was used our of the `gasLimit`.

![Data Visualization Feature](/images/visualize6.png)

- Convert the output for atomic transactions from hexadecimal to user readable.

<Callout title="Note">
Please note that this only works for C-Chain Mainnet, not Fuji.
</Callout>

![Data Visualization Feature](/images/visualize7.png)

How to Visualize Responses[​](#how-to-visualize-responses "Direct link to heading")
-----------------------------------------------------------------------------------

1. After [installing Postman](/docs/tooling/avalanche-postman/add-postman-collection#postman-installation) and importing the [Avalanche collection](/docs/tooling/avalanche-postman/add-postman-collection#collection-import), choose an API to make the call. 
2. Make the call.
3. Click on the **Visualize** tab.
4. Now all data from the output is displayed in tabular format.

![Data Visualization Feature](/images/visualize8.png) ![Data Visualization Feature](/images/visualize9.png)

Examples[​](#examples "Direct link to heading")
-----------------------------------------------

### `eth_getTransactionByHash`[​](#eth_gettransactionbyhash "Direct link to heading")

<YouTube id="M83WhbXq5R0" fullSize={false}/>

### `avm.getBlock`[​](#avmgetblock "Direct link to heading")

<YouTube id="d5E2pHXFInE" fullSize={false}/>

### `platform.getCurrentValidators`[​](#platformgetcurrentvalidators "Direct link to heading")

<YouTube id="Pkf84edkw_0" fullSize={false}/>

### `avax.getAtomicTx`[​](#avaxgetatomictx "Direct link to heading")

<YouTube id="AYIgdQomHqc" fullSize={false}/>

### `eth_getBalance`[​](#eth_getbalance "Direct link to heading")

<YouTube id="M3n7cm1DYLE" fullSize={false}/>

# Installing Postman Collection (/docs/tooling/avalanche-postman)

---
title: Installing Postman Collection
description: Installing Postman collection for Avalanche APIs
---

We have made a Postman collection for Avalanche, that includes all the public API calls that are available on an [AvalancheGo instance](https://github.com/ava-labs/avalanchego/releases/), including environment variables, allowing developers to quickly issue commands to a node and see the response, without having to copy and paste long and complicated `curl` commands.

[Link to GitHub](https://github.com/ava-labs/avalanche-postman-collection/)

What Is Postman?[​](#what-is-postman "Direct link to heading")
--------------------------------------------------------------

Postman is a free tool used by developers to quickly and easily send REST, SOAP, and GraphQL requests and test APIs. It is available as both an online tool and an application for Linux, MacOS and Windows. Postman allows you to quickly issue API calls and see the responses in a nicely formatted, searchable form.

Along with the API collection, there is also the example Avalanche environment for Postman, that defines common variables such as IP address of the node, Avalanche addresses and similar common elements of the queries, so you don't have to enter them multiple times.

Combined, they will allow you to easily keep tabs on an Avalanche node, check on its state and do quick queries to find out details about its operation.

Setup[​](#setup "Direct link to heading")
-----------------------------------------

### Postman Installation[​](#postman-installation "Direct link to heading")

Postman can be installed locally or used as a web app. We recommend installing the application, as it simplifies operation. You can download Postman from its [website](https://www.postman.com/downloads/). It is recommended that you sign up using your email address as then your workspace can be easily backed up and shared between the web app and the app installed on your computer.

![Download Postman](/images/postman1.png)

When you run Postman for the first time, it will prompt you to create an account or log in. Again, it is not necessary, but recommended.

### Collection Import[​](#collection-import "Direct link to heading")

Select `Create workspace` from Workspaces tab and follow the prompts to create a new workspace. This will be where the rest of the work will be done.

![Create workspace](/images/postman2.png)

We're ready to import the collection. On the top-left corner of the Workspaces tab select `Import` and switch to `Link` tab.

![Import collection](/images/postman3.png)

There, in the URL input field paste the link below to the collection:

```bash
https://raw.githubusercontent.com/ava-labs/avalanche-postman-collection/master/Avalanche.postman_collection.json
```

Postman will recognize the format of the file content and offer to import the file as a collection. Complete the import. Now you will have Avalanche collection in your Workspace.

![Collection content](/images/postman4.png)

### Environment Import[​](#environment-import "Direct link to heading")

Next, we have to import the environment variables. Again, on the top-left corner of the Workspaces tab select `Import` and switch to `Link` tab. This time, paste the link below to the environment JSON:

```bash
https://raw.githubusercontent.com/ava-labs/avalanche-postman-collection/master/Example-Avalanche-Environment.postman_environment.json
```

Postman will recognize the format of the file:

![Environment import](/images/postman5.png)

Import it to your workspace. Now, we will need to edit that environment to suit the actual parameters of your particular installation. These are the parameters that differ from the defaults in the imported file.

Select the Environments tab, choose the Avalanche environment which was just added. You can directly edit any values here:

![Environment content](/images/postman6.png)

As a minimum, you will need to change the IP address of your node, which is the value of the `host` variable. Change it to the IP of your node (change both the `initial` and `current` values). Also, if your node is not running on the same machine where you installed Postman, make sure your node is accepting the connections on the API port from the outside by checking the appropriate [command line option](/docs/nodes/configure/configs-flags#http-server).

Now we sorted everything out, and we're ready to query the node.

Conclusion[​](#conclusion "Direct link to heading")
---------------------------------------------------

If you have completed the tutorial, you are now able to quickly [issue API calls](/docs/tooling/avalanche-postman/making-api-calls) to your node without messing with the curl commands in the terminal. This allows you to quickly see the state of your node, track changes or double-check the health or liveness of your node.

Contributing[​](#contributing "Direct link to heading")
-------------------------------------------------------

We're hoping to continuously keep this collection up-to-date with the [Avalanche APIs](/docs/api-reference/p-chain/api). If you're able to help improve the Avalanche Postman Collection in any way, first create a feature branch by branching off of `master`, next make the improvements on your feature branch and lastly create a [pull request](https://github.com/ava-labs/builders-hub/pulls) to merge your work back in to `master`.

If you have any other questions or suggestions, come [talk to us](https://chat.avalabs.org/).

# Making API Calls (/docs/tooling/avalanche-postman/making-api-calls)

---
title: Making API Calls
description: Making API calls using Postman
---

After [installing Postman Collection](/docs/tooling/avalanche-postman/index) and importing the [Avalanche collection](/docs/tooling/avalanche-postman/index#collection-import), you can choose an API to make the call.

You should also make sure the URL is the correct one for the call. This URL consists of the base URL and the endpoint:

- The base URL is set by an environment variable called `baseURL`, and it is by default Avalanche's [public API](/docs/tooling/rpc-providers#mainnet-rpc---public-api-server). If you need to make a local API call, simply change the URL to localhost. This can be done by changing the value of the `baseURL` variable or changing the URL directly on the call tab. Check out the [RPC providers](/docs/tooling/rpc-providers) to see all public URLs.  
- The API endpoint depends on which API is used. Please check out [our APIs](/docs/api-reference/c-chain/api) to find the proper endpoint.
    
The last step is to add the needed parameters for the call. For example, if a user wants to fetch data about a certain transaction, the transaction hash is needed. For fetching data about a block, depending on the call used, the block hash or number will be required.

After clicking the **Send** button, if the call is successfully, the output will be displayed in the **Body** tab.

<Callout title="Note">
Data visualization is available for a number of methods. Learn how to use it with the help of [this](/docs/tooling/avalanche-postman/data-visualization) guide.
</Callout>

![Make Call](/images/api-call1.png)

Examples[​](#examples "Direct link to heading")
-----------------------------------------------

### C-Chain Public API Call[​](#c-chain-public-api-call "Direct link to heading")

Fetching data about a C-Chain transaction using `eth_getTransactionByHash`.

<YouTube id="M83WhbXq5R0" fullSize={false}/>

### X-Chain Public API Call[​](#x-chain-public-api-call "Direct link to heading")

Fetching data about an X-Chain block using `avm.getBlock`.

<YouTube id="4Yu2G3Zvrdo" fullSize={false} params="start=2"/>

### P-Chain Public API Call[​](#p-chain-public-api-call "Direct link to heading")

Getting the current P-Chain height using `platform.getHeight`.

<YouTube id="9d5VPNcODDw" fullSize={false}/>

### API Call Using Variables[​](#api-call-using-variables "Direct link to heading")

Let's say we want fetch data about this `0x20cb0c03dbbe39e934c7bb04979e3073cc2c93defa30feec41198fde8fabc9b8` C-Chain transaction using both:

- `eth_getTransactionReceipt` 
- `eth_getTransactionByHash`
    
We can set up an environment variable with the transaction hash as value and use it on both calls.

<Callout title="Note">
Find out more about variables [here](/docs/tooling/avalanche-postman/variables).
</Callout>

<YouTube id="26xCiawBRjM" fullSize={false}x/>


# Variable Types (/docs/tooling/avalanche-postman/variables)

---
title: Variable Types
description: Variable types for Avalanche APIs using Postman
---

Variables at different scopes are supported by Postman, as it follows:

- **Global variables**: A global variable can be used with every collection. Basically, it allows user to access data between collections. 
- **Collection variables**: They are available for a certain collection and are independent of an environment.
- **Environment variables**: An environment allows you to use a set of variables, which are called environment variables. Every collection can use an environment at a time, but the same environment can be used with multiple collections. This type of variables make the most sense to use with the Avalanche Postman collection, therefore an environment file with preset variables is provided
- **Data variables**: Provided by external CSV and JSON files.  
- **Local variables**: Temporary variables that can be used in a script. For example, the returned block number from querying a transaction can be a local variable. It exists only for that request, and it will change when fetching data for another transaction hash.

![](/images/variables1.png)

There are two types of variables:

- **Default type**: Every variable is automatically assigned this type when created.
- **Secret type**: Masks variable's value. It is used to store sensitive data.

<Callout title="Note">
Only default variables are used in the Avalanche Environment file. To learn more about using the secret type of variables, please checkout the [Postman documentation](https://learning.postman.com/docs/sending-requests/variables/#variable-types).
</Callout>

The [environment variables](/docs/tooling/avalanche-postman/index#environment-import) can be used to ease the process of making an API call. A variable contains the preset value of an API parameter, therefore it can be used in multiple places without having to add the value manually.

How to Use Variables[​](#how-to-use-variables "Direct link to heading")
-----------------------------------------------------------------------

Let's say we want to use both `eth_getTransactionByHash` and `eth_getTransctionReceipt` for a transaction with the following hash: `0x631dc45342a47d360915ea0d193fc317777f8061fe57b4a3e790e49d26960202`. We can set a variable which contains the transaction hash, and then use it on both API calls. Then, when wanting to fetch data about another transaction, the variable can be updated and the new transaction hash will be used again on both calls.

Below are examples on how to set the transaction hash as variable of each scope.

### Set a Global Variable[​](#set-a-global-variable "Direct link to heading")

Go to Environments

![](/images/variables2.png)

Select Globals

![](/images/variables3.png)

Click on the Add a new variable area

![](/images/variables4.png)

Add the variable name and value. Make sure to use quotes.

![](/images/variables5.png)

Click Save

![](/images/variables6.png)

Now it can be used on any call from any collection

### Set a Collection Variable[​](#set-a-collection-variable "Direct link to heading")

Click on the three dots next to the Avalanche collection and select Edit

![](/images/variables7.png)

Go to the Variables tab

![](/images/variables8.png)

Click on the Add a new variable area

![](/images/variables9.png)

Add the variable name and value. Make sure to use quotes.

![](/images/variables10.png)

Click Save

![](/images/variables11.png)

Now it can be used on any call from this collection

### Set an Environment Variable[​](#set-an-environment-variable "Direct link to heading")

Go to Environments

![](/images/variables12.png)

Select an environment. In this case, it is Example-Avalanche-Environment.

![](/images/variables13.png)

Scroll down until you find the Add a new variable area and click on it.

![](/images/variables14.png)

Add the variable name and value. Make sure to use quotes.

![](/images/variables15.png)

Click Save.

![](/images/variables16.png)

The variable is available now for any call collection that uses this environment.

### Set a Data Variable[​](#set-a-data-variable "Direct link to heading")

Please check out [this guide](https://www.softwaretestinghelp.com/postman-variables/#5_Data) and [this video](https://www.youtube.com/watch?v=9wl_UQtRLw4) on how to use data variables.

### Set a Local Variable[​](#set-a-local-variable "Direct link to heading")

Please check out [this guide](https://www.softwaretestinghelp.com/postman-variables/#4_Local) and [this video](https://www.youtube.com/watch?v=gOF7Oc0sXmE) on how to use local variables.

# Overview (/docs/tooling/avalanche-sdk)

---
title: Overview
description: Build applications and interact with Avalanche networks programmatically
icon: Rocket
---

The **Avalanche SDK for TypeScript** is a modular suite of tools designed for building powerful applications on the Avalanche ecosystem. Whether you're building DeFi applications, NFT platforms, or cross-chain bridges, our SDKs provide everything you need.

<img src="https://mintcdn.com/avalabs-47ea3976/Wi87V1LwXev8P44s/images/avalanche_sdk.jpg?fit=max&auto=format&n=Wi87V1LwXev8P44s&q=85&s=1e10ff983be444a989bf30e2dedf1cb8" data-og-width="1984" width="1984" data-og-height="604" height="604" data-path="images/avalanche_sdk.jpg" data-optimize="true" data-opv="3" srcSet="https://mintcdn.com/avalabs-47ea3976/Wi87V1LwXev8P44s/images/avalanche_sdk.jpg?w=280&fit=max&auto=format&n=Wi87V1LwXev8P44s&q=85&s=ddf429244d37623020bd754cd793dc92 280w, https://mintcdn.com/avalabs-47ea3976/Wi87V1LwXev8P44s/images/avalanche_sdk.jpg?w=560&fit=max&auto=format&n=Wi87V1LwXev8P44s&q=85&s=57ad5a44d41025b567fc1564894e80ca 560w, https://mintcdn.com/avalabs-47ea3976/Wi87V1LwXev8P44s/images/avalanche_sdk.jpg?w=840&fit=max&auto=format&n=Wi87V1LwXev8P44s&q=85&s=5b51ef1d5cf23ccce207b632610d12df 840w, https://mintcdn.com/avalabs-47ea3976/Wi87V1LwXev8P44s/images/avalanche_sdk.jpg?w=1100&fit=max&auto=format&n=Wi87V1LwXev8P44s&q=85&s=c986a3608d6e29b7ad0c4f1f29df7845 1100w, https://mintcdn.com/avalabs-47ea3976/Wi87V1LwXev8P44s/images/avalanche_sdk.jpg?w=1650&fit=max&auto=format&n=Wi87V1LwXev8P44s&q=85&s=55b096c77f3dc0505293b8308974a2b9 1650w, https://mintcdn.com/avalabs-47ea3976/Wi87V1LwXev8P44s/images/avalanche_sdk.jpg?w=2500&fit=max&auto=format&n=Wi87V1LwXev8P44s&q=85&s=f15b10a3cc43b734a0777b239511af74 2500w" />

### Core Capabilities

* **Direct Chain Access** - RPC calls, wallet integration, and transaction management.
* **Indexed Data & Metrics** - Access Glacier Data API & Metrics API with type safety.
* **Interchain Messaging** - Build cross-L1 applications with ICM/Teleporter.

<Callout type="warning">
  **Developer Preview**: This suite of SDKs is currently in beta and is subject to change. Use in production at your own risk.
</Callout>

<Callout>
  We'd love to hear about your experience! **<a href="https://forms.gle/kpunVSkA9nuCa1wM9" target="_blank" rel="noopener noreferrer">Please share your feedback here</a>.**
</Callout>

<Cards>
  <Card title="Open Source on GitHub" icon="github" href="https://github.com/ava-labs/avalanche-sdk-typescript">
    Check out the code, contribute, or report issues. The Avalanche SDK TypeScript is fully open source.
  </Card>
</Cards>

## Which SDK Should I Use?

Choose the right SDK based on your specific needs:

| SDK Package                                                                  | Description                                                      |
| :--------------------------------------------------------------------------- | :--------------------------------------------------------------- |
| [`@avalanche-sdk/client`](/avalanche-sdk/client-sdk/getting-started)         | Direct blockchain interaction - transactions, wallets, RPC calls |
| [`@avalanche-sdk/chainkit`](/avalanche-sdk/chainkit-sdk/getting-started)     | Complete suite: Data, Metrics and Webhooks API                   |
| [`@avalanche-sdk/interchain`](/avalanche-sdk/interchain-sdk/getting-started) | Send messages between Avalanche L1s using ICM/Teleporter         |

## Quick Start

<Tabs items={['npm', 'yarn', 'pnpm']}>
  <Tab value="npm">
    ```bash  theme={null}
    npm install @avalanche-sdk/client
    ```
  </Tab>

  <Tab value="yarn">
    ```bash  theme={null}
    yarn add @avalanche-sdk/client
    ```
  </Tab>

  <Tab value="pnpm">
    ```bash  theme={null}
    pnpm add @avalanche-sdk/client
    ```
  </Tab>
</Tabs>

### Basic Example

```typescript  theme={null}
import { createClient } from '@avalanche-sdk/client';

// Initialize the client
const client = createClient({
  network: 'mainnet'
});

// Get balance
const balance = await client.getBalance({
  address: '0x...',
  chainId: 43114
});

console.log('Balance:', balance);
```

## Available SDKs

### Client SDK

The main Avalanche client SDK for interacting with Avalanche nodes and building blockchain applications.

**Key Features:**

* **Complete API coverage** for P-Chain, X-Chain, and C-Chain.
* **Full viem compatibility** - anything you can do with viem works here.
* **TypeScript-first design** with full type safety.
* **Smart contract interactions** with first-class APIs.
* **Wallet integration** and transaction management.
* **Cross-chain transfers** between X, P and C chains.

**Common Use Cases:**

* Retrieve balances and UTXOs for addresses
* Build, sign, and issue transactions to any chain
* Add validators and delegators
* Create subnets and blockchains.
* Convert subnets to L1s.

<Card title="Get Started with Client SDK" icon="arrow-right" href="/avalanche-sdk/client-sdk/getting-started">
  Learn how to integrate blockchain functionality into your application
</Card>

### ChainKit SDK

Combined SDK with full typed coverage of Avalanche Data (Glacier) and Metrics APIs.

**Key Features:**

* **Full endpoint coverage** for Glacier Data API and Metrics API
* **Strongly-typed models** with automatic TypeScript inference
* **Built-in pagination** helpers and automatic retries/backoff
* **High-level helpers** for transactions, blocks, addresses, tokens, NFTs
* **Metrics insights** including network health, validator stats, throughput
* **Webhook support** with payload shapes and signature verification

**API Endpoints:**

* Glacier API: <a href="https://glacier-api.avax.network/api" target="_blank" rel="noopener noreferrer">[https://glacier-api.avax.network/api](https://glacier-api.avax.network/api)</a>
* Metrics API: <a href="https://metrics.avax.network/api" target="_blank" rel="noopener noreferrer">[https://metrics.avax.network/api](https://metrics.avax.network/api)</a>

<Card title="Get Started with ChainKit SDK" icon="arrow-right" href="/avalanche-sdk/chainkit-sdk/getting-started">
  Access comprehensive blockchain data and analytics
</Card>

### Interchain SDK

SDK for building cross-L1 applications and bridges.

**Key Features:**

* **Type-safe ICM client** for sending cross-chain messages
* **Seamless wallet integration** with existing wallet clients
* **Built-in support** for Avalanche C-Chain and custom subnets
* **Message tracking** and delivery confirmation
* **Gas estimation** for cross-chain operations

**Use Cases:**

* Cross-chain token bridges
* Multi-L1 governance systems
* Interchain data oracles
* Cross-subnet liquidity pools

<Card title="Get Started with Interchain SDK" icon="arrow-right" href="/avalanche-sdk/interchain-sdk/getting-started">
  Build powerful cross-chain applications
</Card>

## Support

### Community & Help

* <a href="https://discord.gg/avax" target="_blank" rel="noopener noreferrer">Discord</a> - Get real-time help in the #avalanche-sdk channel
* <a href="https://t.me/+KDajA4iToKY2ZjBk" target="_blank" rel="noopener noreferrer">Telegram</a> - Join discussions
* <a href="https://x.com/AvaxDevelopers" target="_blank" rel="noopener noreferrer">Twitter</a> - Stay updated

### Feedback Sessions

* <a href="https://calendar.google.com/calendar/appointments/schedules/AcZssZ1RkNFpny9hBimkOmBXghLkGJ8RXV0GgHZb2tfrIRoZ9Su3s1wYZOP2R_OjXpwG2aQw_zlHf2JQ?gv=true" target="_blank" rel="noopener noreferrer">Book a Google Meet Feedback Session</a> - Schedule a 1-on-1 session to share your feedback and suggestions

### Issue Tracking

* <a href="https://github.com/ava-labs/avalanche-sdk-typescript/issues/new?template=bug_report.md" target="_blank" rel="noopener noreferrer">Report a Bug</a>
* <a href="https://github.com/ava-labs/avalanche-sdk-typescript/issues/new?template=feature_request.md" target="_blank" rel="noopener noreferrer">Request a Feature</a>
* <a href="https://github.com/ava-labs/avalanche-sdk-typescript/issues" target="_blank" rel="noopener noreferrer">View All Issues</a>

### Direct Support

* Technical Issues: <a href="https://github.com/ava-labs/avalanche-sdk-typescript/issues" target="_blank" rel="noopener noreferrer">GitHub Issues</a>
* Security Issues: <a href="mailto:security@avalabs.org">[security@avalabs.org](mailto:security@avalabs.org)</a>
* General Inquiries: <a href="mailto:data-platform@avalabs.org">[data-platform@avalabs.org](mailto:data-platform@avalabs.org)</a>

# C-Chain API (/docs/rpcs/c-chain/api)

---
title: "C-Chain API"
description: "This page is an overview of the C-Chain API associated with AvalancheGo."
edit_url: https://github.com/ava-labs/coreth/edit/master/plugin/evm/api.md
---

<Callout title="Note">
Ethereum has its own notion of `networkID` and `chainID`. These have no relationship to Avalanche's view of networkID and chainID and are purely internal to the [C-Chain](https://github.com/docs/quick-start/primary-network#c-chain). On Mainnet, the C-Chain uses `1` and `43114` for these values. On the Fuji Testnet, it uses `1` and `43113` for these values. `networkID` and `chainID` can also be obtained using the `net_version` and `eth_chainId` methods.
</Callout>

## Ethereum APIs

### Endpoints

#### JSON-RPC Endpoints

To interact with C-Chain via the JSON-RPC endpoint:

```sh
/ext/bc/C/rpc
```

To interact with other instances of the EVM via the JSON-RPC endpoint:

```sh
/ext/bc/blockchainID/rpc
```

where `blockchainID` is the ID of the blockchain running the EVM.

#### WebSocket Endpoints

<Callout title="info">
On the [public API node](https://github.com/docs/tooling/rpc-providers), it only supports C-Chain
websocket API calls for API methods that don't exist on the C-Chain's HTTP API
</Callout>

To interact with C-Chain via the websocket endpoint:

```sh
/ext/bc/C/ws
```

For example, to interact with the C-Chain's Ethereum APIs via websocket on localhost, you can use:

```sh
ws://127.0.0.1:9650/ext/bc/C/ws
```

<Callout title="Tip" icon = {<BadgeCheck className="size-5 text-card" fill="green" />} >
On localhost, use `ws://`. When using the [Public API](https://github.com/docs/tooling/rpc-providers) or another
host that supports encryption, use `wss://`.
</Callout>

To interact with other instances of the EVM via the websocket endpoint:

```sh
/ext/bc/blockchainID/ws
```

where `blockchainID` is the ID of the blockchain running the EVM.

### Standard Ethereum APIs

Avalanche offers an API interface identical to Geth's API except that it only supports the following
services:

- `web3_`
- `net_`
- `eth_`
- `personal_`
- `txpool_`
- `debug_` (note: this is turned off on the public API node.)

You can interact with these services the same exact way you'd interact with Geth (see exceptions below). See the
[Ethereum Wiki's JSON-RPC Documentation](https://ethereum.org/en/developers/docs/apis/json-rpc/)
and [Geth's JSON-RPC Documentation](https://geth.ethereum.org/docs/rpc/server)
for a full description of this API.

<Callout title="info">
For batched requests on the [public API node](https://github.com/docs/tooling/rpc-providers) , the maximum
number of items is 40.
</Callout>

#### Exceptions

Starting with release [`v0.12.2`](https://github.com/ava-labs/avalanchego/releases/tag/v1.12.2), `eth_getProof` has a different behavior compared to geth:

- On archival nodes (nodes with`pruning-enabled` set to `false`), queries for state proofs older than 24 hours preceding the last accepted block will be rejected by default. This can be adjusted with `historical-proof-query-window`, which defines the number of blocks before the last accepted block that can be queried for state proofs. Set this option to `0` to accept a state query for any block number.
- On pruning nodes (nodes with `pruning-enabled` set to `true`), queries for state proofs outside the 32 block window after the last accepted block are always rejected.

### Avalanche - Ethereum APIs

In addition to the standard Ethereum APIs, Avalanche offers `eth_baseFee`,
`eth_maxPriorityFeePerGas`, and `eth_getChainConfig`.

They use the same endpoint as standard Ethereum APIs:

```sh
/ext/bc/C/rpc
```

#### `eth_baseFee`

Get the base fee for the next block.

**Signature:**

```sh
eth_baseFee() -> {}
```

`result` is the hex value of the base fee for the next block.

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"eth_baseFee",
    "params" :[]
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/C/rpc
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x34630b8a00"
}
```

#### `eth_maxPriorityFeePerGas`

Get the priority fee needed to be included in a block.

**Signature:**

```sh
eth_maxPriorityFeePerGas() -> {}
```

`result` is hex value of the priority fee needed to be included in a block.

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"eth_maxPriorityFeePerGas",
    "params" :[]
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/C/rpc
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x2540be400"
}
```

For more information on dynamic fees see the [C-Chain section of the transaction fee
documentation](https://github.com/docs/api-reference/guides/txn-fees#c-chain-fees).

## Admin APIs

The Admin API provides administrative functionality for the EVM.

### Endpoint

```sh
/ext/bc/C/admin
```

### Methods

#### `admin_startCPUProfiler`

Starts a CPU profile that writes to the specified file.

**Signature:**

```sh
admin_startCPUProfiler() -> {}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin_startCPUProfiler",
    "params" :[]
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/C/admin
```

#### `admin_stopCPUProfiler`

Stops the CPU profile.

**Signature:**

```sh
admin_stopCPUProfiler() -> {}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin_stopCPUProfiler",
    "params" :[]
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/C/admin
```

#### `admin_memoryProfile`

Runs a memory profile writing to the specified file.

**Signature:**

```sh
admin_memoryProfile() -> {}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin_memoryProfile",
    "params" :[]
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/C/admin
```

#### `admin_lockProfile`

Runs a mutex profile writing to the specified file.

**Signature:**

```sh
admin_lockProfile() -> {}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin_lockProfile",
    "params" :[]
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/C/admin
```

#### `admin_setLogLevel`

Sets the log level for the EVM.

**Signature:**

```sh
admin_setLogLevel({
    level: string
}) -> {}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin_setLogLevel",
    "params" :[{
        "level": "debug"
    }]
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/C/admin
```

#### `admin_getVMConfig`

Returns the current VM configuration.

**Signature:**

```sh
admin_getVMConfig() -> {
    config: {
        // VM configuration fields
    }
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin_getVMConfig",
    "params" :[]
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/C/admin
```

## Avalanche-Specific APIs

### Endpoint

```sh
/ext/bc/C/avax
```

### Methods

#### `avax.getUTXOs`

Gets all UTXOs for the specified addresses.

**Signature:**

```sh
avax.getUTXOs({
    addresses: [string],
    sourceChain: string,
    startIndex: {
        address: string,
        utxo: string
    },
    limit: number,
    encoding: string
}) -> {
    utxos: [string],
    endIndex: {
        address: string,
        utxo: string
    },
    numFetched: number,
    encoding: string
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"avax.getUTXOs",
    "params" :[{
        "addresses": ["X-avax1..."],
        "sourceChain": "X",
        "limit": 100,
        "encoding": "hex"
    }]
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/C/avax
```

#### `avax.issueTx`

Issues a transaction to the network.

**Signature:**

```sh
avax.issueTx({
    tx: string,
    encoding: string
}) -> {
    txID: string
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"avax.issueTx",
    "params" :[{
        "tx": "0x...",
        "encoding": "hex"
    }]
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/C/avax
```

#### `avax.getAtomicTxStatus`

Returns the status of the specified atomic transaction.

**Signature:**

```sh
avax.getAtomicTxStatus({
    txID: string
}) -> {
    status: string,
    blockHeight: number (optional)
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"avax.getAtomicTxStatus",
    "params" :[{
        "txID": "2QouvNW..."
    }]
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/C/avax
```

#### `avax.getAtomicTx`

Returns the specified atomic transaction.

**Signature:**

```sh
avax.getAtomicTx({
    txID: string,
    encoding: string
}) -> {
    tx: string,
    encoding: string,
    blockHeight: number (optional)
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"avax.getAtomicTx",
    "params" :[{
        "txID": "2QouvNW...",
        "encoding": "hex"
    }]
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/C/avax
```

#### `avax.version`

Returns the version of the VM.

**Signature:**

```sh
avax.version() -> {
    version: string
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"avax.version",
    "params" :[]
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/C/avax
```

# AvalancheGo C-Chain RPC (/docs/rpcs/c-chain)

---
title: "AvalancheGo C-Chain RPC"
description: "This page is an overview of the C-Chain RPC associated with AvalancheGo."
edit_url: https://github.com/ava-labs/coreth/edit/master/plugin/evm/api.md
---

<Callout title="Note">
Ethereum has its own notion of `networkID` and `chainID`. These have no relationship to Avalanche's view of networkID and chainID and are purely internal to the [C-Chain](https://github.com/docs/quick-start/primary-network#c-chain). On Mainnet, the C-Chain uses `1` and `43114` for these values. On the Fuji Testnet, it uses `1` and `43113` for these values. `networkID` and `chainID` can also be obtained using the `net_version` and `eth_chainId` methods.
</Callout>

## Ethereum APIs

### Endpoints

#### JSON-RPC Endpoints

To interact with C-Chain via the JSON-RPC endpoint:

```sh
/ext/bc/C/rpc
```

To interact with other instances of the EVM via the JSON-RPC endpoint:

```sh
/ext/bc/blockchainID/rpc
```

where `blockchainID` is the ID of the blockchain running the EVM.

#### WebSocket Endpoints

<Callout title="info">
On the [public API node](https://github.com/docs/tooling/rpc-providers), it only supports C-Chain
websocket API calls for API methods that don't exist on the C-Chain's HTTP API
</Callout>

To interact with C-Chain via the websocket endpoint:

```sh
/ext/bc/C/ws
```

For example, to interact with the C-Chain's Ethereum APIs via websocket on localhost, you can use:

```sh
ws://127.0.0.1:9650/ext/bc/C/ws
```

<Callout title="Tip" icon = {<BadgeCheck className="size-5 text-card" fill="green" />} >
On localhost, use `ws://`. When using the [Public API](https://github.com/docs/tooling/rpc-providers) or another
host that supports encryption, use `wss://`.
</Callout>

To interact with other instances of the EVM via the websocket endpoint:

```sh
/ext/bc/blockchainID/ws
```

where `blockchainID` is the ID of the blockchain running the EVM.

### Standard Ethereum APIs

Avalanche offers an API interface identical to Geth's API except that it only supports the following
services:

- `web3_`
- `net_`
- `eth_`
- `personal_`
- `txpool_`
- `debug_` (note: this is turned off on the public API node.)

You can interact with these services the same exact way you'd interact with Geth (see exceptions below). See the
[Ethereum Wiki's JSON-RPC Documentation](https://ethereum.org/en/developers/docs/apis/json-rpc/)
and [Geth's JSON-RPC Documentation](https://geth.ethereum.org/docs/rpc/server)
for a full description of this API.

<Callout title="info">
For batched requests on the [public API node](https://github.com/docs/tooling/rpc-providers) , the maximum
number of items is 40.
</Callout>

#### Exceptions

Starting with release [`v0.12.2`](https://github.com/ava-labs/avalanchego/releases/tag/v1.12.2), `eth_getProof` has a different behavior compared to geth:

- On archival nodes (nodes with`pruning-enabled` set to `false`), queries for state proofs older than 24 hours preceding the last accepted block will be rejected by default. This can be adjusted with `historical-proof-query-window`, which defines the number of blocks before the last accepted block that can be queried for state proofs. Set this option to `0` to accept a state query for any block number.
- On pruning nodes (nodes with `pruning-enabled` set to `true`), queries for state proofs outside the 32 block window after the last accepted block are always rejected.

### Avalanche - Ethereum APIs

In addition to the standard Ethereum APIs, Avalanche offers `eth_baseFee`,
`eth_maxPriorityFeePerGas`, and `eth_getChainConfig`.

They use the same endpoint as standard Ethereum APIs:

```sh
/ext/bc/C/rpc
```

#### `eth_baseFee`

Get the base fee for the next block.

**Signature:**

```sh
eth_baseFee() -> {}
```

`result` is the hex value of the base fee for the next block.

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"eth_baseFee",
    "params" :[]
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/C/rpc
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x34630b8a00"
}
```

#### `eth_maxPriorityFeePerGas`

Get the priority fee needed to be included in a block.

**Signature:**

```sh
eth_maxPriorityFeePerGas() -> {}
```

`result` is hex value of the estimated priority fee needed to be included in a block.

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"eth_maxPriorityFeePerGas",
    "params" :[]
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/C/rpc
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0x2540be400"
}
```

For more information on dynamic fees see the [C-Chain section of the transaction fee
documentation](https://github.com/docs/api-reference/guides/txn-fees#c-chain-fees).

## Admin APIs

The Admin API provides administrative functionality for the EVM.

### Endpoint

```sh
/ext/bc/C/admin
```

### Methods

#### `admin_startCPUProfiler`

Starts a CPU profile that writes to the specified file.

**Signature:**

```sh
admin_startCPUProfiler() -> {}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin_startCPUProfiler",
    "params" :[]
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/C/admin
```

#### `admin_stopCPUProfiler`

Stops the CPU profile.

**Signature:**

```sh
admin_stopCPUProfiler() -> {}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin_stopCPUProfiler",
    "params" :[]
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/C/admin
```

#### `admin_memoryProfile`

Runs a memory profile writing to the specified file.

**Signature:**

```sh
admin_memoryProfile() -> {}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin_memoryProfile",
    "params" :[]
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/C/admin
```

#### `admin_lockProfile`

Runs a mutex profile writing to the specified file.

**Signature:**

```sh
admin_lockProfile() -> {}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin_lockProfile",
    "params" :[]
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/C/admin
```

#### `admin_setLogLevel`

Sets the log level for the EVM.

**Signature:**

```sh
admin_setLogLevel({
    level: string
}) -> {}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin_setLogLevel",
    "params" :[{
        "level": "debug"
    }]
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/C/admin
```

#### `admin_getVMConfig`

Returns the current VM configuration.

**Signature:**

```sh
admin_getVMConfig() -> {
    config: {
        // VM configuration fields
    }
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin_getVMConfig",
    "params" :[]
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/C/admin
```

## Avalanche-Specific APIs

### Endpoint

```sh
/ext/bc/C/avax
```

### Methods

#### `avax.getUTXOs`

Gets all UTXOs for the specified addresses.

**Signature:**

```sh
avax.getUTXOs({
    addresses: [string],
    sourceChain: string,
    startIndex: {
        address: string,
        utxo: string
    },
    limit: number,
    encoding: string
}) -> {
    utxos: [string],
    endIndex: {
        address: string,
        utxo: string
    },
    numFetched: number,
    encoding: string
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"avax.getUTXOs",
    "params" :[{
        "addresses": ["X-avax1..."],
        "sourceChain": "X",
        "limit": 100,
        "encoding": "hex"
    }]
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/C/avax
```

#### `avax.issueTx`

Issues a transaction to the network.

**Signature:**

```sh
avax.issueTx({
    tx: string,
    encoding: string
}) -> {
    txID: string
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"avax.issueTx",
    "params" :[{
        "tx": "0x...",
        "encoding": "hex"
    }]
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/C/avax
```

#### `avax.getAtomicTxStatus`

Returns the status of the specified atomic transaction.

**Signature:**

```sh
avax.getAtomicTxStatus({
    txID: string
}) -> {
    status: string,
    blockHeight: number (optional)
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"avax.getAtomicTxStatus",
    "params" :[{
        "txID": "2QouvNW..."
    }]
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/C/avax
```

#### `avax.getAtomicTx`

Returns the specified atomic transaction.

**Signature:**

```sh
avax.getAtomicTx({
    txID: string,
    encoding: string
}) -> {
    tx: string,
    encoding: string,
    blockHeight: number (optional)
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"avax.getAtomicTx",
    "params" :[{
        "txID": "2QouvNW...",
        "encoding": "hex"
    }]
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/C/avax
```

#### `avax.version`

Returns the version of the VM.

**Signature:**

```sh
avax.version() -> {
    version: string
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"avax.version",
    "params" :[]
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/C/avax
```

# Transaction Format (/docs/rpcs/c-chain/txn-format)

---
title: Transaction Format
---

This page is meant to be the single source of truth for how we serialize atomic
transactions in `Coreth`. This document uses the [primitive serialization](/docs/api-reference/standards/serialization-primitives) format for packing and
[secp256k1](/docs/api-reference/standards/cryptographic-primitives#cryptography-in-the-avalanche-virtual-machine)
for cryptographic user identification.

## Codec ID

Some data is prepended with a codec ID (unt16) that denotes how the data should
be deserialized. Right now, the only valid codec ID is 0 (`0x00 0x00`).

## Inputs

Inputs to Coreth Atomic Transactions are either an `EVMInput` from this chain or
a `TransferableInput` (which contains a `SECP256K1TransferInput`) from another
chain. The `EVMInput` will be used in `ExportTx` to spend funds from this chain,
while the `TransferableInput` will be used to import atomic UTXOs from another
chain.

## EVM Input

Input type that specifies an EVM account to deduct the funds from as part of an `ExportTx`.

### What EVM Input Contains

An EVM Input contains an `address`, `amount`, `assetID`, and `nonce`.

- **`Address`** is the EVM address from which to transfer funds.
- **`Amount`** is the amount of the asset to be transferred (specified in nAVAX
  for AVAX and the smallest denomination for all other assets).
- **`AssetID`** is the ID of the asset to transfer.
- **`Nonce`** is the nonce of the EVM account exporting funds.

### Gantt EVM Input Specification

```text
+----------+----------+-------------------------+
| address  : [20]byte |                20 bytes |
+----------+----------+-------------------------+
| amount   : uint64   |                08 bytes |
+----------+----------+-------------------------+
| asset_id : [32]byte |                32 bytes |
+----------+----------+-------------------------+
| nonce    : uint64   |                08 bytes |
+----------+----------+-------------------------+
                      |                68 bytes |
                      +-------------------------+
```

### Proto EVM Input Specification

```text
message  {
    bytes address = 1; // 20 bytes
    uint64 amount = 2; // 08 bytes
    bytes assetID = 3; // 32 bytes
    uint64 nonce = 4;  // 08 bytes
}
```

### EVM Input Example

Let's make an EVM Input:

- `Address: 0x8db97c7cece249c2b98bdc0226cc4c2a57bf52fc`
- `Amount: 2000000`
- `AssetID: 0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f`
- `Nonce: 0`

```text
[
    Address   <- 0x8db97c7cece249c2b98bdc0226cc4c2a57bf52fc,
    Amount    <- 0x00000000001e8480
    AssetID   <- 0xdbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db
    Nonce     <- 0x0000000000000000
]
=
[
    // address:
    0x8d, 0xb9, 0x7c, 0x7c, 0xec, 0xe2, 0x49, 0xc2,
    0xb9, 0x8b, 0xdc, 0x02, 0x26, 0xcc, 0x4c, 0x2a,
    0x57, 0xbf, 0x52, 0xfc,
    // amount:
    0x00, 0x00, 0x00, 0x00, 0x00, 0x1e, 0x84, 0x80,
    // assetID:
    0xdb, 0xcf, 0x89, 0x0f, 0x77, 0xf4, 0x9b, 0x96,
    0x85, 0x76, 0x48, 0xb7, 0x2b, 0x77, 0xf9, 0xf8,
    0x29, 0x37, 0xf2, 0x8a, 0x68, 0x70, 0x4a, 0xf0,
    0x5d, 0xa0, 0xdc, 0x12, 0xba, 0x53, 0xf2, 0xdb,
    // nonce:
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
]
```

## Transferable Input

Transferable Input wraps a `SECP256K1TransferInput`. Transferable inputs
describe a specific UTXO with a provided transfer input.

### What Transferable Input Contains

A transferable input contains a `TxID`, `UTXOIndex` `AssetID` and an `Input`.

- **`TxID`** is a 32-byte array that defines which transaction this input is consuming an output from.
- **`UTXOIndex`** is an int that defines which utxo this input is consuming in the specified transaction.
- **`AssetID`** is a 32-byte array that defines which asset this input references.
- **`Input`** is a `SECP256K1TransferInput`, as defined below.

### Gantt Transferable Input Specification

```text
+------------+----------+------------------------+
| tx_id      : [32]byte |               32 bytes |
+------------+----------+------------------------+
| utxo_index : int      |               04 bytes |
+------------+----------+------------------------+
| asset_id   : [32]byte |               32 bytes |
+------------+----------+------------------------+
| input      : Input    |      size(input) bytes |
+------------+----------+------------------------+
                        | 68 + size(input) bytes |
                        +------------------------+
```

### Proto Transferable Input Specification

```text
message TransferableInput {
    bytes tx_id = 1;       // 32 bytes
    uint32 utxo_index = 2; // 04 bytes
    bytes asset_id = 3;    // 32 bytes
    Input input = 4;       // size(input)
}
```

### Transferable Input Example

Let's make a transferable input:

- `TxID: 0x6613a40dcdd8d22ea4aa99a4c84349056317cf550b6685e045e459954f258e59`
- `UTXOIndex: 1`
- `AssetID: 0xdbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db`
- `Input: "Example SECP256K1 Transfer Input from below"`

```text
[
    TxID      <- 0x6613a40dcdd8d22ea4aa99a4c84349056317cf550b6685e045e459954f258e59
    UTXOIndex <- 0x00000001
    AssetID   <- 0xdbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db
    Input     <- 0x0000000500000000075bcd15000000020000000700000003
]
=
[
    // txID:
    0x66, 0x13, 0xa4, 0x0d, 0xcd, 0xd8, 0xd2, 0x2e,
    0xa4, 0xaa, 0x99, 0xa4, 0xc8, 0x43, 0x49, 0x05,
    0x63, 0x17, 0xcf, 0x55, 0x0b, 0x66, 0x85, 0xe0,
    0x45, 0xe4, 0x59, 0x95, 0x4f, 0x25, 0x8e, 0x59,
    // utxoIndex:
    0x00, 0x00, 0x00, 0x01,
    // assetID:
    0xdb, 0xcf, 0x89, 0x0f, 0x77, 0xf4, 0x9b, 0x96,
    0x85, 0x76, 0x48, 0xb7, 0x2b, 0x77, 0xf9, 0xf8,
    0x29, 0x37, 0xf2, 0x8a, 0x68, 0x70, 0x4a, 0xf0,
    0x5d, 0xa0, 0xdc, 0x12, 0xba, 0x53, 0xf2, 0xdb,
    // input:
    0x00, 0x00, 0x00, 0x05, 0x00, 0x00, 0x00, 0x74,
    0x6a, 0x52, 0x88, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x00,
]
```

## SECP256K1 Transfer Input

A
[secp256k1](/docs/api-reference/standards/cryptographic-primitives#cryptography-in-the-avalanche-virtual-machine)
transfer input allows for spending an unspent secp256k1 transfer output.

### What SECP256K1 Transfer Input Contains

A secp256k1 transfer input contains an `Amount` and `AddressIndices`.

- **`TypeID`** is the ID for this input type. It is `0x00000005`.
- **`Amount`** is a long that specifies the quantity that this input should be
  consuming from the UTXO. Must be positive. Must be equal to the amount
  specified in the UTXO.
- **`AddressIndices`** is a list of unique ints that define the private keys
  that are being used to spend the UTXO. Each UTXO has an array of addresses
  that can spend the UTXO. Each int represents the index in this address array
  that will sign this transaction. The array must be sorted low to high.

### Gantt SECP256K1 Transfer Input Specification

```text
+-------------------------+-------------------------------------+
| type_id         : int   |                             4 bytes |
+-----------------+-------+-------------------------------------+
| amount          : long  |                             8 bytes |
+-----------------+-------+-------------------------------------+
| address_indices : []int |  4 + 4 * len(address_indices) bytes |
+-----------------+-------+-------------------------------------+
                          | 16 + 4 * len(address_indices) bytes |
                          +-------------------------------------+
```

### Proto SECP256K1 Transfer Input Specification

```text
message SECP256K1TransferInput {
    uint32 typeID = 1;                   // 04 bytes
    uint64 amount = 2;                   // 08 bytes
    repeated uint32 address_indices = 3; // 04 bytes + 04 bytes * len(address_indices)
}
```

### SECP256K1 Transfer Input Example

Let's make a payment input with:

- **`TypeId`**: 5
- **`Amount`**: 500000000000
- **`AddressIndices`**: \[0\]

```text
[
    TypeID         <- 0x00000005
    Amount         <- 500000000000 = 0x000000746a528800,
    AddressIndices <- [0x00000000]
]
=
[
    // type id:
    0x00, 0x00, 0x00, 0x05,
    // amount:
    0x00, 0x00, 0x00, 0x74, 0x6a, 0x52, 0x88, 0x00,
    // length:
    0x00, 0x00, 0x00, 0x01,
    // sig[0]
    0x00, 0x00, 0x00, 0x00,
]
```

## Outputs

Outputs to Coreth Atomic Transactions are either an `EVMOutput` to be added to
the balance of an address on this chain or a `TransferableOutput` (which
contains a `SECP256K1TransferOutput`) to be moved to another chain.

The EVM Output will be used in `ImportTx` to add funds to this chain, while the
`TransferableOutput` will be used to export atomic UTXOs to another chain.

## EVM Output

Output type specifying a state change to be applied to an EVM account as part of an `ImportTx`.

### What EVM Output Contains

An EVM Output contains an `address`, `amount`, and `assetID`.

- **`Address`** is the EVM address that will receive the funds.
- **`Amount`** is the amount of the asset to be transferred (specified in nAVAX
  for AVAX and the smallest denomination for all other assets).
- **`AssetID`** is the ID of the asset to transfer.

### Gantt EVM Output Specification

```text
+----------+----------+-------------------------+
| address  : [20]byte |                20 bytes |
+----------+----------+-------------------------+
| amount   : uin64    |                08 bytes |
+----------+----------+-------------------------+
| asset_id : [32]byte |                32 bytes |
+----------+----------+-------------------------+
                      |                60 bytes |
                      +-------------------------+
```

### Proto EVM Output Specification

```text
message  {
    bytes address = 1; // 20 bytes
    uint64 amount = 2; // 08 bytes
    bytes assetID = 3; // 32 bytes
}
```

### EVM Output Example

Let's make an EVM Output:

- `Address: 0x0eb5ccb85c29009b6060decb353a38ea3b52cd20`
- `Amount: 500000000000`
- `AssetID: 0xdbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db`

```text
[
    Address   <- 0x0eb5ccb85c29009b6060decb353a38ea3b52cd20,
    Amount    <- 0x000000746a528800
    AssetID   <- 0xdbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db
]
=
[
    // address:
    0xc3, 0x34, 0x41, 0x28, 0xe0, 0x60, 0x12, 0x8e,
    0xde, 0x35, 0x23, 0xa2, 0x4a, 0x46, 0x1c, 0x89,
    0x43, 0xab, 0x08, 0x59,
    // amount:
    0x00, 0x00, 0x00, 0x74, 0x6a, 0x52, 0x88, 0x00,
    // assetID:
    0xdb, 0xcf, 0x89, 0x0f, 0x77, 0xf4, 0x9b, 0x96,
    0x85, 0x76, 0x48, 0xb7, 0x2b, 0x77, 0xf9, 0xf8,
    0x29, 0x37, 0xf2, 0x8a, 0x68, 0x70, 0x4a, 0xf0,
    0x5d, 0xa0, 0xdc, 0x12, 0xba, 0x53, 0xf2, 0xdb,
]
```

## Transferable Output

Transferable outputs wrap a `SECP256K1TransferOutput` with an asset ID.

### What Transferable Output Contains

A transferable output contains an `AssetID` and an `Output` which is a `SECP256K1TransferOutput`.

- **`AssetID`** is a 32-byte array that defines which asset this output references.
- **`Output`** is a `SECP256K1TransferOutput` as defined below.

### Gantt Transferable Output Specification

```text
+----------+----------+-------------------------+
| asset_id : [32]byte |                32 bytes |
+----------+----------+-------------------------+
| output   : Output   |      size(output) bytes |
+----------+----------+-------------------------+
                      | 32 + size(output) bytes |
                      +-------------------------+
```

### Proto Transferable Output Specification

```text
message TransferableOutput {
    bytes asset_id = 1; // 32 bytes
    Output output = 2;  // size(output)
}
```

### Transferable Output Example

Let's make a transferable output:

- `AssetID: 0xdbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db`
- `Output: "Example SECP256K1 Transfer Output from below"`

```text
[
    AssetID <- 0xdbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db
    Output  <- 0x000000070000000000003039000000000000d431000000010000000251025c61fbcfc078f69334f834be6dd26d55a955c3344128e060128ede3523a24a461c8943ab0859,
]
=
[
    // assetID:
    0xdb, 0xcf, 0x89, 0x0f, 0x77, 0xf4, 0x9b, 0x96,
    0x85, 0x76, 0x48, 0xb7, 0x2b, 0x77, 0xf9, 0xf8,
    0x29, 0x37, 0xf2, 0x8a, 0x68, 0x70, 0x4a, 0xf0,
    0x5d, 0xa0, 0xdc, 0x12, 0xba, 0x53, 0xf2, 0xdb,
    // output:
    0xdb, 0xcf, 0x89, 0x0f, 0x77, 0xf4, 0x9b, 0x96,
    0x85, 0x76, 0x48, 0xb7, 0x2b, 0x77, 0xf9, 0xf8,
    0x29, 0x37, 0xf2, 0x8a, 0x68, 0x70, 0x4a, 0xf0,
    0x5d, 0xa0, 0xdc, 0x12, 0xba, 0x53, 0xf2, 0xdb,
    0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x0f, 0x42, 0x40, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x01, 0x66, 0xf9, 0x0d, 0xb6,
    0x13, 0x7a, 0x78, 0xf7, 0x6b, 0x36, 0x93, 0xf7,
    0xf2, 0xbc, 0x50, 0x79, 0x56, 0xda, 0xe5, 0x63,
]
```

## SECP256K1 Transfer Output

A
[secp256k1](/docs/api-reference/standards/cryptographic-primitives#cryptography-in-the-avalanche-virtual-machine)
transfer output allows for sending a quantity of an asset to a collection of
addresses after a specified Unix time.

### What SECP256K1 Transfer Output Contains

A secp256k1 transfer output contains a `TypeID`, `Amount`, `Locktime`, `Threshold`, and `Addresses`.

- **`TypeID`** is the ID for this output type. It is `0x00000007`.
- **`Amount`** is a long that specifies the quantity of the asset that this output owns. Must be positive.
- **`Locktime`** is a long that contains the Unix timestamp that this output can
  be spent after. The Unix timestamp is specific to the second.
- **`Threshold`** is an int that names the number of unique signatures required
  to spend the output. Must be less than or equal to the length of
  **`Addresses`**. If **`Addresses`** is empty, must be 0.
- **`Addresses`** is a list of unique addresses that correspond to the private
  keys that can be used to spend this output. Addresses must be sorted
  lexicographically.

### Gantt SECP256K1 Transfer Output Specification

```text
+-----------+------------+--------------------------------+
| type_id   : int        |                        4 bytes |
+-----------+------------+--------------------------------+
| amount    : long       |                        8 bytes |
+-----------+------------+--------------------------------+
| locktime  : long       |                        8 bytes |
+-----------+------------+--------------------------------+
| threshold : int        |                        4 bytes |
+-----------+------------+--------------------------------+
| addresses : [][20]byte |  4 + 20 * len(addresses) bytes |
+-----------+------------+--------------------------------+
                         | 28 + 20 * len(addresses) bytes |
                         +--------------------------------+
```

### Proto SECP256K1 Transfer Output Specification

```text
message SECP256K1TransferOutput {
    uint32 typeID = 1;            // 04 bytes
    uint64 amount = 2;            // 08 bytes
    uint64 locktime = 3;          // 08 bytes
    uint32 threshold = 4;         // 04 bytes
    repeated bytes addresses = 5; // 04 bytes + 20 bytes * len(addresses)
}
```

### SECP256K1 Transfer Output Example

Let's make a secp256k1 transfer output with:

- **`TypeID`**: 7
- **`Amount`**: 1000000
- **`Locktime`**: 0
- **`Threshold`**: 1
- **`Addresses`**:
  - 0x66f90db6137a78f76b3693f7f2bc507956dae563

```text
[
    TypeID    <- 0x00000007
    Amount    <- 0x00000000000f4240
    Locktime  <- 0x0000000000000000
    Threshold <- 0x00000001
    Addresses <- [
        0x66f90db6137a78f76b3693f7f2bc507956dae563
    ]
]
=
[
    // typeID:
    0x00, 0x00, 0x00, 0x07,
    // amount:
    0x00, 0x00, 0x00, 0x00, 0x00, 0x0f, 0x42, 0x40,
    // locktime:
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    // threshold:
    0x00, 0x00, 0x00, 0x01,
    // number of addresses:
    0x00, 0x00, 0x00, 0x01,
    // addrs[0]:
    0x66, 0xf9, 0x0d, 0xb6, 0x13, 0x7a, 0x78, 0xf7,
    0x6b, 0x36, 0x93, 0xf7, 0xf2, 0xbc, 0x50, 0x79,
    0x56, 0xda, 0xe5, 0x63,
]
```

## Atomic Transactions

Atomic Transactions are used to move funds between chains. There are two types `ImportTx` and `ExportTx`.

## ExportTx

ExportTx is a transaction to export funds from Coreth to a different chain.

### What ExportTx Contains

An ExportTx contains an `typeID`, `networkID`, `blockchainID`, `destinationChain`, `inputs`, and `exportedOutputs`.

- **`typeID`** is an int that the type for an ExportTx. The typeID for an exportTx is 1.
- **`networkID`** is an int that defines which Avalanche network this
  transaction is meant to be issued to. This could refer to Mainnet, Fuji, etc.
  and is different than the EVM's network ID.
- **`blockchainID`** is a 32-byte array that defines which blockchain this transaction was issued to.
- **`destinationChain`** is a 32-byte array that defines which blockchain this
  transaction exports funds to.
- **`inputs`** is an array of EVM Inputs to fund the ExportTx.
- **`exportedOutputs`** is an array of TransferableOutputs to be transferred to `destinationChain`.

### Gantt ExportTx Specification

```text
+---------------------+----------------------+-------------------------------------------------+
| typeID              : int                  |                                        04 bytes |
+---------------------+----------------------+-------------------------------------------------+
| networkID           : int                  |                                        04 bytes |
+---------------------+----------------------+-------------------------------------------------+
| blockchainID        : [32]byte             |                                        32 bytes |
+---------------------+----------------------+-------------------------------------------------+
| destinationChain    : [32]byte             |                                        32 bytes |
+---------------------+----------------------+-------------------------------------------------+
| inputs              : []EvmInput           |                          4 + size(inputs) bytes |
+---------------------+----------------------+-------------------------------------------------+
| exportedOutputs     : []TransferableOutput |                 4 + size(exportedOutputs) bytes |
+----------+----------+----------------------+-------------------------------------------------+
                                             | 80 + size(inputs) + size(exportedOutputs) bytes |
                                             +-------------------------------------------------+
```

### ExportTx Example

Let's make an EVM Output:

- **`TypeID`**: `1`
- **`NetworkID`**: `12345`
- **`BlockchainID`**: `0x91060eabfb5a571720109b5896e5ff00010a1cfe6b103d585e6ebf27b97a1735`
- **`DestinationChain`**: `0xd891ad56056d9c01f18f43f58b5c784ad07a4a49cf3d1f11623804b5cba2c6bf`
- **`Inputs`**:
  - `"Example EVMInput as defined above"`
- **`Exportedoutputs`**:
  - `"Example TransferableOutput as defined above"`

```text
[
    TypeID           <- 0x00000001
    NetworkID        <- 0x00003039
    BlockchainID     <- 0x91060eabfb5a571720109b5896e5ff00010a1cfe6b103d585e6ebf27b97a1735
    DestinationChain <- 0xd891ad56056d9c01f18f43f58b5c784ad07a4a49cf3d1f11623804b5cba2c6bf
    Inputs           <- [
        0xc3344128e060128ede3523a24a461c8943ab08590000000000003039000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f0000000000000001
    ]
    ExportedOutputs  <- [
        0xdbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2dbdbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db0000000700000000000f42400000000000000000000000010000000166f90db6137a78f76b3693f7f2bc507956dae563
    ]
]
=
[
    // typeID:
    0x00, 0x00, 0x00, 0x01,
    // networkID:
    0x00, 0x00, 0x00, 0x04,
    // blockchainID:
    0x91, 0x06, 0x0e, 0xab, 0xfb, 0x5a, 0x57, 0x17,
    0x20, 0x10, 0x9b, 0x58, 0x96, 0xe5, 0xff, 0x00,
    0x01, 0x0a, 0x1c, 0xfe, 0x6b, 0x10, 0x3d, 0x58,
    0x5e, 0x6e, 0xbf, 0x27, 0xb9, 0x7a, 0x17, 0x35,
    // destination_chain:
    0xd8, 0x91, 0xad, 0x56, 0x05, 0x6d, 0x9c, 0x01,
    0xf1, 0x8f, 0x43, 0xf5, 0x8b, 0x5c, 0x78, 0x4a,
    0xd0, 0x7a, 0x4a, 0x49, 0xcf, 0x3d, 0x1f, 0x11,
    0x62, 0x38, 0x04, 0xb5, 0xcb, 0xa2, 0xc6, 0xbf,
    // inputs[] count:
    0x00, 0x00, 0x00, 0x01,
    // inputs[0]
    0x8d, 0xb9, 0x7c, 0x7c, 0xec, 0xe2, 0x49, 0xc2,
    0xb9, 0x8b, 0xdc, 0x02, 0x26, 0xcc, 0x4c, 0x2a,
    0x57, 0xbf, 0x52, 0xfc, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x1e, 0x84, 0x80, 0xdb, 0xcf, 0x89, 0x0f,
    0x77, 0xf4, 0x9b, 0x96, 0x85, 0x76, 0x48, 0xb7,
    0x2b, 0x77, 0xf9, 0xf8, 0x29, 0x37, 0xf2, 0x8a,
    0x68, 0x70, 0x4a, 0xf0, 0x5d, 0xa0, 0xdc, 0x12,
    0xba, 0x53, 0xf2, 0xdb, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00,
    // exportedOutputs[] count
    0x00, 0x00, 0x00, 0x01,
    // exportedOutputs[0]
    0xdb, 0xcf, 0x89, 0x0f, 0x77, 0xf4, 0x9b, 0x96,
    0x85, 0x76, 0x48, 0xb7, 0x2b, 0x77, 0xf9, 0xf8,
    0x29, 0x37, 0xf2, 0x8a, 0x68, 0x70, 0x4a, 0xf0,
    0x5d, 0xa0, 0xdc, 0x12, 0xba, 0x53, 0xf2, 0xdb,
    0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x0f, 0x42, 0x40, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x01, 0x66, 0xf9, 0x0d, 0xb6,
    0x13, 0x7a, 0x78, 0xf7, 0x6b, 0x36, 0x93, 0xf7,
    0xf2, 0xbc, 0x50, 0x79, 0x56, 0xda, 0xe5, 0x63,
]
```

## ImportTx

ImportTx is a transaction to import funds to Coreth from another chain.

### What ImportTx Contains

An ImportTx contains an `typeID`, `networkID`, `blockchainID`,
`destinationChain`, `importedInputs`, and `Outs`.

- **`typeID`** is an int that the type for an ImportTx. The typeID for an `ImportTx` is 0.
- **`networkID`** is an int that defines which Avalanche network this
  transaction is meant to be issued to. This could refer to Mainnet, Fuji, etc.
  and is different than the EVM's network ID.
- **`blockchainID`** is a 32-byte array that defines which blockchain this transaction was issued to.
- **`sourceChain`** is a 32-byte array that defines which blockchain from which to import funds.
- **`importedInputs`** is an array of TransferableInputs to fund the ImportTx.
- **`Outs`** is an array of EVM Outputs to be imported to this chain.

### Gantt ImportTx Specification

```text
+---------------------+----------------------+-------------------------------------------------+
| typeID              : int                  |                                        04 bytes |
+---------------------+----------------------+-------------------------------------------------+
| networkID           : int                  |                                        04 bytes |
+---------------------+----------------------+-------------------------------------------------+
| blockchainID        : [32]byte             |                                        32 bytes |
+---------------------+----------------------+-------------------------------------------------+
| sourceChain         : [32]byte             |                                        32 bytes |
+---------------------+----------------------+-------------------------------------------------+
| importedInputs      : []TransferableInput  |                  4 + size(importedInputs) bytes |
+---------------------+----------------------+-------------------------------------------------+
| outs                : []EVMOutput          |                            4 + size(outs) bytes |
+----------+----------+----------------------+-------------------------------------------------+
                                             |    80 + size(importedInputs) + size(outs) bytes |
                                             +-------------------------------------------------+
```

### ImportTx Example

Let's make an ImportTx:

- **`TypeID`**: `0`
- **`NetworkID`**: `12345`
- **`BlockchainID`**: `0x91060eabfb5a571720109b5896e5ff00010a1cfe6b103d585e6ebf27b97a1735`
- **`SourceChain`**: `0xd891ad56056d9c01f18f43f58b5c784ad07a4a49cf3d1f11623804b5cba2c6bf`
- **`ImportedInputs`**:
  - `"Example TransferableInput as defined above"`
- **`Outs`**:
  - `"Example EVMOutput as defined above"`

```text
[
    TypeID           <- 0x00000000
    NetworkID        <- 0x00003039
    BlockchainID     <- 0x91060eabfb5a571720109b5896e5ff00010a1cfe6b103d585e6ebf27b97a1735
    SourceChain      <- 0xd891ad56056d9c01f18f43f58b5c784ad07a4a49cf3d1f11623804b5cba2c6bf
    ImportedInputs   <- [
        0x6613a40dcdd8d22ea4aa99a4c84349056317cf550b6685e045e459954f258e5900000001dbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db00000005000000746a5288000000000100000000
    ]
    Outs             <- [
        0x0eb5ccb85c29009b6060decb353a38ea3b52cd20000000746a528800dbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db
    ]
]
=
[
    // typeID:
    0x00, 0x00, 0x00, 0x00,
    // networkID:
    0x00, 0x00, 0x00, 0x04,
    // blockchainID:
    0x91, 0x06, 0x0e, 0xab, 0xfb, 0x5a, 0x57, 0x17,
    0x20, 0x10, 0x9b, 0x58, 0x96, 0xe5, 0xff, 0x00,
    0x01, 0x0a, 0x1c, 0xfe, 0x6b, 0x10, 0x3d, 0x58,
    0x5e, 0x6e, 0xbf, 0x27, 0xb9, 0x7a, 0x17, 0x35,
    // sourceChain:
    0xd8, 0x91, 0xad, 0x56, 0x05, 0x6d, 0x9c, 0x01,
    0xf1, 0x8f, 0x43, 0xf5, 0x8b, 0x5c, 0x78, 0x4a,
    0xd0, 0x7a, 0x4a, 0x49, 0xcf, 0x3d, 0x1f, 0x11,
    0x62, 0x38, 0x04, 0xb5, 0xcb, 0xa2, 0xc6, 0xbf,
    // importedInputs[] count:
    0x00, 0x00, 0x00, 0x01,
    // importedInputs[0]
    0x66, 0x13, 0xa4, 0x0d, 0xcd, 0xd8, 0xd2, 0x2e,
    0xa4, 0xaa, 0x99, 0xa4, 0xc8, 0x43, 0x49, 0x05,
    0x63, 0x17, 0xcf, 0x55, 0x0b, 0x66, 0x85, 0xe0,
    0x45, 0xe4, 0x59, 0x95, 0x4f, 0x25, 0x8e, 0x59,
    0x00, 0x00, 0x00, 0x01, 0xdb, 0xcf, 0x89, 0x0f,
    0x77, 0xf4, 0x9b, 0x96, 0x85, 0x76, 0x48, 0xb7,
    0x2b, 0x77, 0xf9, 0xf8, 0x29, 0x37, 0xf2, 0x8a,
    0x68, 0x70, 0x4a, 0xf0, 0x5d, 0xa0, 0xdc, 0x12,
    0xba, 0x53, 0xf2, 0xdb, 0x00, 0x00, 0x00, 0x05,
    0x00, 0x00, 0x00, 0x74, 0x6a, 0x52, 0x88, 0x00,
    0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x00,
    // outs[] count
    0x00, 0x00, 0x00, 0x01,
    // outs[0]
    0x0e, 0xb5, 0xcc, 0xb8, 0x5c, 0x29, 0x00, 0x9b,
    0x60, 0x60, 0xde, 0xcb, 0x35, 0x3a, 0x38, 0xea,
    0x3b, 0x52, 0xcd, 0x20, 0x00, 0x00, 0x00, 0x74,
    0x6a, 0x52, 0x88, 0x00, 0xdb, 0xcf, 0x89, 0x0f,
    0x77, 0xf4, 0x9b, 0x96, 0x85, 0x76, 0x48, 0xb7,
    0x2b, 0x77, 0xf9, 0xf8, 0x29, 0x37, 0xf2, 0x8a,
    0x68, 0x70, 0x4a, 0xf0, 0x5d, 0xa0, 0xdc, 0x12,
    0xba, 0x53, 0xf2, 0xdb,
]
```

## Credentials

Credentials have one possible type: `SECP256K1Credential`. Each credential is
paired with an Input. The order of the credentials match the order of the
inputs.

## SECP256K1 Credential

A
[secp256k1](/docs/api-reference/standards/cryptographic-primitives#cryptography-in-the-avalanche-virtual-machine)
credential contains a list of 65-byte recoverable signatures.

### What SECP256K1 Credential Contains

- **`TypeID`** is the ID for this type. It is `0x00000009`.
- **`Signatures`** is an array of 65-byte recoverable signatures. The order of
  the signatures must match the input's signature indices.

### Gantt SECP256K1 Credential Specification

```text
+------------------------------+---------------------------------+
| type_id         : int        |                         4 bytes |
+-----------------+------------+---------------------------------+
| signatures      : [][65]byte |  4 + 65 * len(signatures) bytes |
+-----------------+------------+---------------------------------+
                               |  8 + 65 * len(signatures) bytes |
                               +---------------------------------+
```

### Proto SECP256K1 Credential Specification

```text
message SECP256K1Credential {
    uint32 typeID = 1;             // 4 bytes
    repeated bytes signatures = 2; // 4 bytes + 65 bytes * len(signatures)
}
```

### SECP256K1 Credential Example

Let's make a payment input with:

- **`TypeID`**: 9
- **`signatures`**:
  - `0x0acccf47a820549a84428440e2421975138790e41be262f7197f3d93faa26cc8741060d743ffaf025782c8c86b862d2b9febebe7d352f0b4591afbd1a737f8a30010199dbf`

```text
[
    TypeID         <- 0x00000009
    Signatures     <- [
        0x0acccf47a820549a84428440e2421975138790e41be262f7197f3d93faa26cc8741060d743ffaf025782c8c86b862d2b9febebe7d352f0b4591afbd1a737f8a30010199dbf,
    ]
]
=
[
    // Type ID
    0x00, 0x00, 0x00, 0x09,
    // length:
    0x00, 0x00, 0x00, 0x01,
    // sig[0]
    0x0a, 0xcc, 0xcf, 0x47, 0xa8, 0x20, 0x54, 0x9a,
    0x84, 0x42, 0x84, 0x40, 0xe2, 0x42, 0x19, 0x75,
    0x13, 0x87, 0x90, 0xe4, 0x1b, 0xe2, 0x62, 0xf7,
    0x19, 0x7f, 0x3d, 0x93, 0xfa, 0xa2, 0x6c, 0xc8,
    0x74, 0x10, 0x60, 0xd7, 0x43, 0xff, 0xaf, 0x02,
    0x57, 0x82, 0xc8, 0xc8, 0x6b, 0x86, 0x2d, 0x2b,
    0x9f, 0xeb, 0xeb, 0xe7, 0xd3, 0x52, 0xf0, 0xb4,
    0x59, 0x1a, 0xfb, 0xd1, 0xa7, 0x37, 0xf8, 0xa3,
    0x00, 0x10, 0x19, 0x9d, 0xbf,
]
```

## Signed Transaction

A signed transaction contains an unsigned `AtomicTx` and credentials.

### What Signed Transaction Contains

A signed transaction contains a `CodecID`, `AtomicTx`, and `Credentials`.

- **`CodecID`** The only current valid codec id is `00 00`.
- **`AtomicTx`** is an atomic transaction, as described above.
- **`Credentials`** is an array of credentials. Each credential corresponds to
  the input at the same index in the AtomicTx

### Gantt Signed Transaction Specification

```text
+---------------------+--------------+------------------------------------------------+
| codec_id            : uint16       |                                        2 bytes |
+---------------------+--------------+------------------------------------------------+
| atomic_tx           : AtomicTx     |                          size(atomic_tx) bytes |
+---------------------+--------------+------------------------------------------------+
| credentials         : []Credential |                    4 + size(credentials) bytes |
+---------------------+--------------+------------------------------------------------+
                                     |   6 + size(atomic_tx) + len(credentials) bytes |
                                     +------------------------------------------------+
```

### Proto Signed Transaction Specification

```text
message Tx {
    uint16 codec_id = 1;                 // 2 bytes
    AtomicTx atomic_tx = 2;              // size(atomic_tx)
    repeated Credential credentials = 3; // 4 bytes + size(credentials)
}
```

### Signed Transaction Example

Let's make a signed transaction that uses the unsigned transaction and credential from the previous examples.

- **`CodecID`**: `0`
- **`UnsignedTx`**: `0x000000000000303991060eabfb5a571720109b5896e5ff00010a1cfe6b103d585e6ebf27b97a1735d891ad56056d9c01f18f43f58b5c784ad07a4a49cf3d1f11623804b5cba2c6bf000000016613a40dcdd8d22ea4aa99a4c84349056317cf550b6685e045e459954f258e5900000001dbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db00000005000000746a5288000000000100000000000000010eb5ccb85c29009b6060decb353a38ea3b52cd20000000746a528800dbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db`
- **`Credentials`**

  `0x00000009000000010acccf47a820549a84428440e2421975138790e41be262f7197f3d93faa26cc8741060d743ffaf025782c8c86b862d2b9febebe7d352f0b4591afbd1a737f8a300`

```text
[
    CodecID            <- 0x0000
    UnsignedAtomic Tx  <- 0x0000000100000004ffffffffeeeeeeeeddddddddccccccccbbbbbbbbaaaaaaaa999999998888888800000001000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f000000070000000000003039000000000000d431000000010000000251025c61fbcfc078f69334f834be6dd26d55a955c3344128e060128ede3523a24a461c8943ab085900000001f1e1d1c1b1a191817161514131211101f0e0d0c0b0a09080706050403020100000000005000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f0000000500000000075bcd150000000200000007000000030000000400010203
    Credentials        <- [
        0x00000009000000010acccf47a820549a84428440e2421975138790e41be262f7197f3d93faa26cc8741060d743ffaf025782c8c86b862d2b9febebe7d352f0b4591afbd1a737f8a300,
    ]
]
=
[
    // Codec ID
    0x00, 0x00,
    // unsigned atomic transaction:
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x30, 0x39,
    0x91, 0x06, 0x0e, 0xab, 0xfb, 0x5a, 0x57, 0x17,
    0x20, 0x10, 0x9b, 0x58, 0x96, 0xe5, 0xff, 0x00,
    0x01, 0x0a, 0x1c, 0xfe, 0x6b, 0x10, 0x3d, 0x58,
    0x5e, 0x6e, 0xbf, 0x27, 0xb9, 0x7a, 0x17, 0x35,
    0xd8, 0x91, 0xad, 0x56, 0x05, 0x6d, 0x9c, 0x01,
    0xf1, 0x8f, 0x43, 0xf5, 0x8b, 0x5c, 0x78, 0x4a,
    0xd0, 0x7a, 0x4a, 0x49, 0xcf, 0x3d, 0x1f, 0x11,
    0x62, 0x38, 0x04, 0xb5, 0xcb, 0xa2, 0xc6, 0xbf,
    0x00, 0x00, 0x00, 0x01, 0x66, 0x13, 0xa4, 0x0d,
    0xcd, 0xd8, 0xd2, 0x2e, 0xa4, 0xaa, 0x99, 0xa4,
    0xc8, 0x43, 0x49, 0x05, 0x63, 0x17, 0xcf, 0x55,
    0x0b, 0x66, 0x85, 0xe0, 0x45, 0xe4, 0x59, 0x95,
    0x4f, 0x25, 0x8e, 0x59, 0x00, 0x00, 0x00, 0x01,
    0xdb, 0xcf, 0x89, 0x0f, 0x77, 0xf4, 0x9b, 0x96,
    0x85, 0x76, 0x48, 0xb7, 0x2b, 0x77, 0xf9, 0xf8,
    0x29, 0x37, 0xf2, 0x8a, 0x68, 0x70, 0x4a, 0xf0,
    0x5d, 0xa0, 0xdc, 0x12, 0xba, 0x53, 0xf2, 0xdb,
    0x00, 0x00, 0x00, 0x05, 0x00, 0x00, 0x00, 0x74,
    0x6a, 0x52, 0x88, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x0e, 0xb5, 0xcc, 0xb8, 0x5c, 0x29, 0x00, 0x9b,
    0x60, 0x60, 0xde, 0xcb, 0x35, 0x3a, 0x38, 0xea,
    0x3b, 0x52, 0xcd, 0x20, 0x00, 0x00, 0x00, 0x74,
    0x6a, 0x52, 0x88, 0x00, 0xdb, 0xcf, 0x89, 0x0f,
    0x77, 0xf4, 0x9b, 0x96, 0x85, 0x76, 0x48, 0xb7,
    0x2b, 0x77, 0xf9, 0xf8, 0x29, 0x37, 0xf2, 0x8a,
    0x68, 0x70, 0x4a, 0xf0, 0x5d, 0xa0, 0xdc, 0x12,
    0xba, 0x53, 0xf2, 0xdb,
    // number of credentials:
    0x00, 0x00, 0x00, 0x01,
    // credential[0]:
    0x00, 0x00, 0x00, 0x09, 0x00, 0x00, 0x00, 0x01,
    0x0a, 0xcc, 0xcf, 0x47, 0xa8, 0x20, 0x54, 0x9a,
    0x84, 0x42, 0x84, 0x40, 0xe2, 0x42, 0x19, 0x75,
    0x13, 0x87, 0x90, 0xe4, 0x1b, 0xe2, 0x62, 0xf7,
    0x19, 0x7f, 0x3d, 0x93, 0xfa, 0xa2, 0x6c, 0xc8,
    0x74, 0x10, 0x60, 0xd7, 0x43, 0xff, 0xaf, 0x02,
    0x57, 0x82, 0xc8, 0xc8, 0x6b, 0x86, 0x2d, 0x2b,
    0x9f, 0xeb, 0xeb, 0xe7, 0xd3, 0x52, 0xf0, 0xb4,
    0x59, 0x1a, 0xfb, 0xd1, 0xa7, 0x37, 0xf8, 0xa3,
    0x00,
```

## UTXO

A UTXO is a standalone representation of a transaction output.

### What UTXO Contains

A UTXO contains a `CodecID`, `TxID`, `UTXOIndex`, `AssetID`, and `Output`.

- **`CodecID`** The only valid `CodecID` is `00 00`
- **`TxID`** is a 32-byte transaction ID. Transaction IDs are calculated by
  taking sha256 of the bytes of the signed transaction.
- **`UTXOIndex`** is an int that specifies which output in the transaction
  specified by **`TxID`** that this utxo was created by.
- **`AssetID`** is a 32-byte array that defines which asset this utxo references.
- **`Output`** is the output object that created this utxo. The serialization of
  Outputs was defined above.

### Gantt UTXO Specification

```text
+--------------+----------+-------------------------+
| codec_id     : uint16   |                 2 bytes |
+--------------+----------+-------------------------+
| tx_id        : [32]byte |                32 bytes |
+--------------+----------+-------------------------+
| output_index : int      |                 4 bytes |
+--------------+----------+-------------------------+
| asset_id     : [32]byte |                32 bytes |
+--------------+----------+-------------------------+
| output       : Output   |      size(output) bytes |
+--------------+----------+-------------------------+
                          | 70 + size(output) bytes |
                          +-------------------------+
```

### Proto UTXO Specification

```text
message Utxo {
    uint16 codec_id = 1;     // 02 bytes
    bytes tx_id = 2;         // 32 bytes
    uint32 output_index = 3; // 04 bytes
    bytes asset_id = 4;      // 32 bytes
    Output output = 5;       // size(output)
}
```

### UTXO Example

Let's make a UTXO from the signed transaction created above:

- **`CodecID`**: `0`
- **`TxID`**: `0xf966750f438867c3c9828ddcdbe660e21ccdbb36a9276958f011ba472f75d4e7`
- **`UTXOIndex`**: 0 = 0x00000000
- **`AssetID`**: `0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f`
- **`Output`**: `"Example EVMOutput as defined above"`

```text
[
    CodecID   <- 0x0000
    TxID      <- 0xf966750f438867c3c9828ddcdbe660e21ccdbb36a9276958f011ba472f75d4e7
    UTXOIndex <- 0x00000000
    AssetID   <- 0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f
    Output    <-     0x000000070000000000003039000000000000d431000000010000000251025c61fbcfc078f69334f834be6dd26d55a955c3344128e060128ede3523a24a461c8943ab0859
]
=
[
    // Codec ID:
    0x00, 0x00,
    // txID:
    0xf9, 0x66, 0x75, 0x0f, 0x43, 0x88, 0x67, 0xc3,
    0xc9, 0x82, 0x8d, 0xdc, 0xdb, 0xe6, 0x60, 0xe2,
    0x1c, 0xcd, 0xbb, 0x36, 0xa9, 0x27, 0x69, 0x58,
    0xf0, 0x11, 0xba, 0x47, 0x2f, 0x75, 0xd4, 0xe7,
    // utxo index:
    0x00, 0x00, 0x00, 0x00,
    // assetID:
    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
    0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
    0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
    0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
    // output:
    0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x30, 0x39, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0xd4, 0x31, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x02, 0x00, 0x01, 0x02, 0x03,
    0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b,
    0x0c, 0x0d, 0x0e, 0x0f, 0x10, 0x11, 0x12, 0x13,
    0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1a, 0x1b,
    0x1c, 0x1d, 0x1e, 0x1f, 0x20, 0x21, 0x22, 0x23,
    0x24, 0x25, 0x26, 0x27,
]
```



# Health RPC (/docs/rpcs/other/health-rpc)

---
title: "Health RPC"
description: "This page is an overview of the Health RPC associated with AvalancheGo."
edit_url: https://github.com/ava-labs/avalanchego/edit/master/api/health/service.md
---

The Health API can be used for measuring node health.

<Callout title="Note">
This API set is for a specific node; it is unavailable on the [public server](https://build.avax.network/docs/tooling/rpc-providers).
</Callout>

## Health Checks

The node periodically runs all health checks, including health checks for each chain.

The frequency at which health checks are run can be specified with the [\--health-check-frequency](https://build.avax.network/docs/nodes/configure/configs-flags) flag.

## Filterable Health Checks

The health checks that are run by the node are filterable. You can specify which health checks you want to see by using `tags` filters. Returned results will only include health checks that match the specified tags and global health checks like `network`, `database` etc. When filtered, the returned results will not show the full node health, but only a subset of filtered health checks. This means the node can still be unhealthy in unfiltered checks, even if the returned results show that the node is healthy. AvalancheGo supports using subnetIDs as tags.

## GET Request

To get an HTTP status code response that indicates the node's health, make a `GET` request. If the node is healthy, it will return a `200` status code. If the node is unhealthy, it will return a `503` status code. In-depth information about the node's health is included in the response body.

### Filtering

To filter GET health checks, add a `tag` query parameter to the request. The `tag` parameter is a string. For example, to filter health results by subnetID `29uVeLPJB1eQJkzRemU8g8wZDw5uJRqpab5U2mX9euieVwiEbL`, use the following query:

```sh
curl 'http://localhost:9650/ext/health?tag=29uVeLPJB1eQJkzRemU8g8wZDw5uJRqpab5U2mX9euieVwiEbL'
```

In this example returned results will contain global health checks and health checks that are related to subnetID `29uVeLPJB1eQJkzRemU8g8wZDw5uJRqpab5U2mX9euieVwiEbL`.

**Note**: This filtering can show healthy results even if the node is unhealthy in other Chains/Avalanche L1s.

In order to filter results by multiple tags, use multiple `tag` query parameters. For example, to filter health results by subnetID `29uVeLPJB1eQJkzRemU8g8wZDw5uJRqpab5U2mX9euieVwiEbL` and `28nrH5T2BMvNrWecFcV3mfccjs6axM1TVyqe79MCv2Mhs8kxiY` use the following query:

```sh
curl 'http://localhost:9650/ext/health?tag=29uVeLPJB1eQJkzRemU8g8wZDw5uJRqpab5U2mX9euieVwiEbL&tag=28nrH5T2BMvNrWecFcV3mfccjs6axM1TVyqe79MCv2Mhs8kxiY'
```

The returned results will include health checks for both subnetIDs as well as global health checks.

### Endpoints

The available endpoints for GET requests are:

- `/ext/health` returns a holistic report of the status of the node. **Most operators should monitor this status.**
- `/ext/health/health` is the same as `/ext/health`.
- `/ext/health/readiness` returns healthy once the node has finished initializing.
- `/ext/health/liveness` returns healthy once the endpoint is available.

## JSON RPC Request

### Format

This API uses the `json 2.0` RPC format. For more information on making JSON RPC calls, see [here](https://build.avax.network/docs/api-reference/guides/issuing-api-calls).

### Endpoint

### Methods

#### `health.health`

This method returns the last set of health check results.

**Example Call**:

```sh
curl  -H 'Content-Type: application/json' --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"health.health",
    "params": {
        "tags": ["11111111111111111111111111111111LpoYY", "29uVeLPJB1eQJkzRemU8g8wZDw5uJRqpab5U2mX9euieVwiEbL"]
    }
}' 'http://localhost:9650/ext/health'
```

**Example Response**:

```json
{
    "jsonrpc": "2.0",
    "result": {
        "checks": {
            "C": {
                "message": {
                    "engine": {
                        "consensus": {
                            "lastAcceptedHeight": 31273749,
                            "lastAcceptedID": "2Y4gZGzQnu8UjnHod8j1BLewHFVEbzhULPNzqrSWEHkHNqDrYL",
                            "longestProcessingBlock": "0s",
                            "processingBlocks": 0
                        },
                        "vm": null
                    },
                    "networking": {
                        "percentConnected": 0.9999592612587486
                    }
                },
                "timestamp": "2024-03-26T19:44:45.2931-04:00",
                "duration": 20375
            },
            "P": {
                "message": {
                    "engine": {
                        "consensus": {
                            "lastAcceptedHeight": 142517,
                            "lastAcceptedID": "2e1FEPCBEkG2Q7WgyZh1v4nt3DXj1HDbDthyhxdq2Ltg3shSYq",
                            "longestProcessingBlock": "0s",
                            "processingBlocks": 0
                        },
                        "vm": null
                    },
                    "networking": {
                        "percentConnected": 0.9999592612587486
                    }
                },
                "timestamp": "2024-03-26T19:44:45.293115-04:00",
                "duration": 8750
            },
            "X": {
                "message": {
                    "engine": {
                        "consensus": {
                            "lastAcceptedHeight": 24464,
                            "lastAcceptedID": "XuFCsGaSw9cn7Vuz5e2fip4KvP46Xu53S8uDRxaC2QJmyYc3w",
                            "longestProcessingBlock": "0s",
                            "processingBlocks": 0
                        },
                        "vm": null
                    },
                    "networking": {
                        "percentConnected": 0.9999592612587486
                    }
                },
                "timestamp": "2024-03-26T19:44:45.29312-04:00",
                "duration": 23291
            },
            "bootstrapped": {
                "message": [],
                "timestamp": "2024-03-26T19:44:45.293078-04:00",
                "duration": 3375
            },
            "database": {
                "timestamp": "2024-03-26T19:44:45.293102-04:00",
                "duration": 1959
            },
            "diskspace": {
                "message": {
                    "availableDiskBytes": 227332591616
                },
                "timestamp": "2024-03-26T19:44:45.293106-04:00",
                "duration": 3042
            },
            "network": {
                "message": {
                    "connectedPeers": 284,
                    "sendFailRate": 0,
                    "timeSinceLastMsgReceived": "293.098ms",
                    "timeSinceLastMsgSent": "293.098ms"
                },
                "timestamp": "2024-03-26T19:44:45.2931-04:00",
                "duration": 2333
            },
            "router": {
                "message": {
                    "longestRunningRequest": "66.90725ms",
                    "outstandingRequests": 3
                },
                "timestamp": "2024-03-26T19:44:45.293097-04:00",
                "duration": 3542
            }
        },
        "healthy": true
    },
    "id": 1
}
```

In this example response, every check has passed. So, the node is healthy.

**Response Explanation**:

- `checks` is a list of health check responses.
    - A check response may include a `message` with additional context.
    - A check response may include an `error` describing why the check failed.
    - `timestamp` is the timestamp of the last health check.
    - `duration` is the execution duration of the last health check, in nanoseconds.
    - `contiguousFailures` is the number of times in a row this check failed.
    - `timeOfFirstFailure` is the time this check first failed.
- `healthy` is true all the health checks are passing.

#### `health.readiness`

This method returns the last evaluation of the startup health check results.

**Example Call**:

```sh
curl  -H 'Content-Type: application/json' --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"health.readiness",
    "params": {
        "tags": ["11111111111111111111111111111111LpoYY", "29uVeLPJB1eQJkzRemU8g8wZDw5uJRqpab5U2mX9euieVwiEbL"]
    }
}' 'http://localhost:9650/ext/health'
```

**Example Response**:

```json
{
    "jsonrpc": "2.0",
    "result": {
        "checks": {
            "bootstrapped": {
                "message": [],
                "timestamp": "2024-03-26T20:02:45.299114-04:00",
                "duration": 2834
            }
        },
        "healthy": true
    },
    "id": 1
}
```

In this example response, every check has passed. So, the node has finished the startup process.

**Response Explanation**:

- `checks` is a list of health check responses.
    - A check response may include a `message` with additional context.
    - A check response may include an `error` describing why the check failed.
    - `timestamp` is the timestamp of the last health check.
    - `duration` is the execution duration of the last health check, in nanoseconds.
    - `contiguousFailures` is the number of times in a row this check failed.
    - `timeOfFirstFailure` is the time this check first failed.
- `healthy` is true all the health checks are passing.

#### `health.liveness`

This method returns healthy.

**Example Call**:

```sh
curl  -H 'Content-Type: application/json' --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"health.liveness"
}' 'http://localhost:9650/ext/health'
```

**Example Response**:

```json
{
    "jsonrpc": "2.0",
    "result": {
        "checks": {},
        "healthy": true
    },
    "id": 1
}
```

In this example response, the node was able to handle the request and mark the service as healthy.

**Response Explanation**:

- `checks` is an empty list.
- `healthy` is true.

# Index RPC (/docs/rpcs/other/index-rpc)

---
title: "Index RPC"
description: "This page is an overview of the Index RPC associated with AvalancheGo."
edit_url: https://github.com/ava-labs/avalanchego/edit/master/indexer/service.md
---

AvalancheGo can be configured to run with an indexer. That is, it saves (indexes) every container (a block, vertex or transaction) it accepts on the X-Chain, P-Chain and C-Chain. To run AvalancheGo with indexing enabled, set command line flag [\--index-enabled](https://build.avax.network/docs/nodes/configure/configs-flags#--index-enabled-boolean) to true.

**AvalancheGo will only index containers that are accepted when running with `--index-enabled` set to true.** To ensure your node has a complete index, run a node with a fresh database and `--index-enabled` set to true. The node will accept every block, vertex and transaction in the network history during bootstrapping, ensuring your index is complete.

It is OK to turn off your node if it is running with indexing enabled. If it restarts with indexing still enabled, it will accept all containers that were accepted while it was offline. The indexer should never fail to index an accepted block, vertex or transaction.

Indexed containers (that is, accepted blocks, vertices and transactions) are timestamped with the time at which the node accepted that container. Note that if the container was indexed during bootstrapping, other nodes may have accepted the container much earlier. Every container indexed during bootstrapping will be timestamped with the time at which the node bootstrapped, not when it was first accepted by the network.

If `--index-enabled` is changed to `false` from `true`, AvalancheGo won't start as doing so would cause a previously complete index to become incomplete, unless the user explicitly says to do so with `--index-allow-incomplete`. This protects you from accidentally running with indexing disabled, after previously running with it enabled, which would result in an incomplete index.

This document shows how to query data from AvalancheGo's Index API. The Index API is only available when running with `--index-enabled`.

## Go Client

There is a Go implementation of an Index API client. See documentation [here](https://pkg.go.dev/github.com/ava-labs/avalanchego/indexer#Client). This client can be used inside a Go program to connect to an AvalancheGo node that is running with the Index API enabled and make calls to the Index API.

## Format

This API uses the `json 2.0` RPC format. For more information on making JSON RPC calls, see [here](https://build.avax.network/docs/api-reference/guides/issuing-api-calls).

## Endpoints

Each chain has one or more index. To see if a C-Chain block is accepted, for example, send an API call to the C-Chain block index. To see if an X-Chain vertex is accepted, for example, send an API call to the X-Chain vertex index.

### C-Chain Blocks

```
/ext/index/C/block
```

### P-Chain Blocks

```
/ext/index/P/block
```

### X-Chain Transactions

```
/ext/index/X/tx
```

### X-Chain Blocks

```
/ext/index/X/block
```

<Callout type="warn">
To ensure historical data can be accessed, the `/ext/index/X/vtx` is still accessible, even though it is no longer populated with chain data since the Cortina activation. If you are using `V1.10.0` or higher, you need to migrate to using the `/ext/index/X/block` endpoint.
</Callout>

## Methods

### `index.getContainerByID`

Get container by ID.

**Signature**:

```
index.getContainerByID({
  id: string,
  encoding: string
}) -> {
  id: string,
  bytes: string,
  timestamp: string,
  encoding: string,
  index: string
}
```

**Request**:

- `id` is the container's ID
- `encoding` is `"hex"` only.

**Response**:

- `id` is the container's ID
- `bytes` is the byte representation of the container
- `timestamp` is the time at which this node accepted the container
- `encoding` is `"hex"` only.
- `index` is how many containers were accepted in this index before this one

**Example Call**:

```sh
curl --location --request POST 'localhost:9650/ext/index/X/tx' \
--header 'Content-Type: application/json' \
--data-raw '{
    "jsonrpc": "2.0",
    "method": "index.getContainerByID",
    "params": {
        "id": "6fXf5hncR8LXvwtM8iezFQBpK5cubV6y1dWgpJCcNyzGB1EzY",
        "encoding":"hex"
    },
    "id": 1
}'
```

**Example Response**:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "id": "6fXf5hncR8LXvwtM8iezFQBpK5cubV6y1dWgpJCcNyzGB1EzY",
    "bytes": "0x00000000000400003039d891ad56056d9c01f18f43f58b5c784ad07a4a49cf3d1f11623804b5cba2c6bf00000001dbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db000000070429ccc5c5eb3b80000000000000000000000001000000013cb7d3842e8cee6a0ebd09f1fe884f6861e1b29c00000001dbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db00000001dbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db000000050429d069189e0000000000010000000000000000c85fc1980a77c5da78fe5486233fc09a769bb812bcb2cc548cf9495d046b3f1b00000001dbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db00000007000003a352a38240000000000000000000000001000000013cb7d3842e8cee6a0ebd09f1fe884f6861e1b29c0000000100000009000000011cdb75d4e0b0aeaba2ebc1ef208373fedc1ebbb498f8385ad6fb537211d1523a70d903b884da77d963d56f163191295589329b5710113234934d0fd59c01676b00b63d2108",
    "timestamp": "2021-04-02T15:34:00.262979-07:00",
    "encoding": "hex",
    "index": "0"
  }
}
```

### `index.getContainerByIndex`

Get container by index. The first container accepted is at index 0, the second is at index 1, etc.

**Signature**:

```
index.getContainerByIndex({
  index: uint64,
  encoding: string
}) -> {
  id: string,
  bytes: string,
  timestamp: string,
  encoding: string,
  index: string
}
```

**Request**:

- `index` is how many containers were accepted in this index before this one
- `encoding` is `"hex"` only.

**Response**:

- `id` is the container's ID
- `bytes` is the byte representation of the container
- `timestamp` is the time at which this node accepted the container
- `index` is how many containers were accepted in this index before this one
- `encoding` is `"hex"` only.

**Example Call**:

```sh
curl --location --request POST 'localhost:9650/ext/index/X/tx' \
--header 'Content-Type: application/json' \
--data-raw '{
    "jsonrpc": "2.0",
    "method": "index.getContainerByIndex",
    "params": {
        "index":0,
        "encoding": "hex"
    },
    "id": 1
}'
```

**Example Response**:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "id": "6fXf5hncR8LXvwtM8iezFQBpK5cubV6y1dWgpJCcNyzGB1EzY",
    "bytes": "0x00000000000400003039d891ad56056d9c01f18f43f58b5c784ad07a4a49cf3d1f11623804b5cba2c6bf00000001dbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db000000070429ccc5c5eb3b80000000000000000000000001000000013cb7d3842e8cee6a0ebd09f1fe884f6861e1b29c00000001dbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db00000001dbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db000000050429d069189e0000000000010000000000000000c85fc1980a77c5da78fe5486233fc09a769bb812bcb2cc548cf9495d046b3f1b00000001dbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db00000007000003a352a38240000000000000000000000001000000013cb7d3842e8cee6a0ebd09f1fe884f6861e1b29c0000000100000009000000011cdb75d4e0b0aeaba2ebc1ef208373fedc1ebbb498f8385ad6fb537211d1523a70d903b884da77d963d56f163191295589329b5710113234934d0fd59c01676b00b63d2108",
    "timestamp": "2021-04-02T15:34:00.262979-07:00",
    "encoding": "hex",
    "index": "0"
  }
}
```

### `index.getContainerRange`

Returns the transactions at index \[`startIndex`\], \[`startIndex+1`\], ... , \[`startIndex+n-1`\]

- If \[`n`\] == 0, returns an empty response (for example: null).
- If \[`startIndex`\] > the last accepted index, returns an error (unless the above apply.)
- If \[`n`\] > \[`MaxFetchedByRange`\], returns an error.
- If we run out of transactions, returns the ones fetched before running out.
- `numToFetch` must be in `[0,1024]`.

**Signature**:

```
index.getContainerRange({
  startIndex: uint64,
  numToFetch: uint64,
  encoding: string
}) -> []{
  id: string,
  bytes: string,
  timestamp: string,
  encoding: string,
  index: string
}
```

**Request**:

- `startIndex` is the beginning index
- `numToFetch` is the number of containers to fetch
- `encoding` is `"hex"` only.

**Response**:

- `id` is the container's ID
- `bytes` is the byte representation of the container
- `timestamp` is the time at which this node accepted the container
- `encoding` is `"hex"` only.
- `index` is how many containers were accepted in this index before this one

**Example Call**:

```sh
curl --location --request POST 'localhost:9650/ext/index/X/tx' \
--header 'Content-Type: application/json' \
--data-raw '{
    "jsonrpc": "2.0",
    "method": "index.getContainerRange",
    "params": {
        "startIndex":0,
        "numToFetch":100,
        "encoding": "hex"
    },
    "id": 1
}'
```

**Example Response**:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": [
    {
      "id": "6fXf5hncR8LXvwtM8iezFQBpK5cubV6y1dWgpJCcNyzGB1EzY",
      "bytes": "0x00000000000400003039d891ad56056d9c01f18f43f58b5c784ad07a4a49cf3d1f11623804b5cba2c6bf00000001dbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db000000070429ccc5c5eb3b80000000000000000000000001000000013cb7d3842e8cee6a0ebd09f1fe884f6861e1b29c00000001dbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db00000001dbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db000000050429d069189e0000000000010000000000000000c85fc1980a77c5da78fe5486233fc09a769bb812bcb2cc548cf9495d046b3f1b00000001dbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db00000007000003a352a38240000000000000000000000001000000013cb7d3842e8cee6a0ebd09f1fe884f6861e1b29c0000000100000009000000011cdb75d4e0b0aeaba2ebc1ef208373fedc1ebbb498f8385ad6fb537211d1523a70d903b884da77d963d56f163191295589329b5710113234934d0fd59c01676b00b63d2108",
      "timestamp": "2021-04-02T15:34:00.262979-07:00",
      "encoding": "hex",
      "index": "0"
    }
  ]
}
```

### `index.getIndex`

Get a container's index.

**Signature**:

```
index.getIndex({
  id: string,
  encoding: string
}) -> {
  index: string
}
```

**Request**:

- `id` is the ID of the container to fetch
- `encoding` is `"hex"` only.

**Response**:

- `index` is how many containers were accepted in this index before this one

**Example Call**:

```sh
curl --location --request POST 'localhost:9650/ext/index/X/tx' \
--header 'Content-Type: application/json' \
--data-raw '{
    "jsonrpc": "2.0",
    "method": "index.getIndex",
    "params": {
        "id":"6fXf5hncR8LXvwtM8iezFQBpK5cubV6y1dWgpJCcNyzGB1EzY",
        "encoding": "hex"
    },
    "id": 1
}'
```

**Example Response**:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "index": "0"
  },
  "id": 1
}
```

### `index.getLastAccepted`

Get the most recently accepted container.

**Signature**:

```
index.getLastAccepted({
  encoding:string
}) -> {
  id: string,
  bytes: string,
  timestamp: string,
  encoding: string,
  index: string
}
```

**Request**:

- `encoding` is `"hex"` only.

**Response**:

- `id` is the container's ID
- `bytes` is the byte representation of the container
- `timestamp` is the time at which this node accepted the container
- `encoding` is `"hex"` only.

**Example Call**:

```sh
curl --location --request POST 'localhost:9650/ext/index/X/tx' \
--header 'Content-Type: application/json' \
--data-raw '{
    "jsonrpc": "2.0",
    "method": "index.getLastAccepted",
    "params": {
        "encoding": "hex"
    },
    "id": 1
}'
```

**Example Response**:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "id": "6fXf5hncR8LXvwtM8iezFQBpK5cubV6y1dWgpJCcNyzGB1EzY",
    "bytes": "0x00000000000400003039d891ad56056d9c01f18f43f58b5c784ad07a4a49cf3d1f11623804b5cba2c6bf00000001dbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db000000070429ccc5c5eb3b80000000000000000000000001000000013cb7d3842e8cee6a0ebd09f1fe884f6861e1b29c00000001dbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db00000001dbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db000000050429d069189e0000000000010000000000000000c85fc1980a77c5da78fe5486233fc09a769bb812bcb2cc548cf9495d046b3f1b00000001dbcf890f77f49b96857648b72b77f9f82937f28a68704af05da0dc12ba53f2db00000007000003a352a38240000000000000000000000001000000013cb7d3842e8cee6a0ebd09f1fe884f6861e1b29c0000000100000009000000011cdb75d4e0b0aeaba2ebc1ef208373fedc1ebbb498f8385ad6fb537211d1523a70d903b884da77d963d56f163191295589329b5710113234934d0fd59c01676b00b63d2108",
    "timestamp": "2021-04-02T15:34:00.262979-07:00",
    "encoding": "hex",
    "index": "0"
  }
}
```

### `index.isAccepted`

Returns true if the container is in this index.

**Signature**:

```
index.isAccepted({
  id: string,
  encoding: string
}) -> {
  isAccepted: bool
}
```

**Request**:

- `id` is the ID of the container to fetch
- `encoding` is `"hex"` only.

**Response**:

- `isAccepted` displays if the container has been accepted

**Example Call**:

```sh
curl --location --request POST 'localhost:9650/ext/index/X/tx' \
--header 'Content-Type: application/json' \
--data-raw '{
    "jsonrpc": "2.0",
    "method": "index.isAccepted",
    "params": {
        "id":"6fXf5hncR8LXvwtM8iezFQBpK5cubV6y1dWgpJCcNyzGB1EzY",
        "encoding": "hex"
    },
    "id": 1
}'
```

**Example Response**:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "isAccepted": true
  },
  "id": 1
}
```

## Example: Iterating Through X-Chain Transaction

Here is an example of how to iterate through all transactions on the X-Chain.

You can use the Index API to get the ID of every transaction that has been accepted on the X-Chain, and use the X-Chain API method `avm.getTx` to get a human-readable representation of the transaction.

To get an X-Chain transaction by its index (the order it was accepted in), use Index API method [index.getlastaccepted](#indexgetlastaccepted).

For example, to get the second transaction (note that `"index":1`) accepted on the X-Chain, do:

```sh
curl --location --request POST 'https://indexer-demo.avax.network/ext/index/X/tx' \
--header 'Content-Type: application/json' \
--data-raw '{
   "jsonrpc": "2.0",
   "method": "index.getContainerByIndex",
   "params": {
       "encoding":"hex",
       "index":1
   },
   "id": 1
}'
```

This returns the ID of the second transaction accepted in the X-Chain's history. To get the third transaction on the X-Chain, use `"index":2`, and so on.

The above API call gives the response below:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "id": "ZGYTSU8w3zUP6VFseGC798vA2Vnxnfj6fz1QPfA9N93bhjJvo",
    "bytes": "0x00000000000000000001ed5f38341e436e5d46e2bb00b45d62ae97d1b050c64bc634ae10626739e35c4b0000000221e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff000000070000000129f6afc0000000000000000000000001000000017416792e228a765c65e2d76d28ab5a16d18c342f21e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff0000000700000222afa575c00000000000000000000000010000000187d6a6dd3cd7740c8b13a410bea39b01fa83bb3e000000016f375c785edb28d52edb59b54035c96c198e9d80f5f5f5eee070592fe9465b8d0000000021e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff0000000500000223d9ab67c0000000010000000000000000000000010000000900000001beb83d3d29f1247efb4a3a1141ab5c966f46f946f9c943b9bc19f858bd416d10060c23d5d9c7db3a0da23446b97cd9cf9f8e61df98e1b1692d764c84a686f5f801a8da6e40",
    "timestamp": "2021-11-04T00:42:55.01643414Z",
    "encoding": "hex",
    "index": "1"
  },
  "id": 1
}
```

The ID of this transaction is `ZGYTSU8w3zUP6VFseGC798vA2Vnxnfj6fz1QPfA9N93bhjJvo`.

To get the transaction by its ID, use API method `avm.getTx`:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"avm.getTx",
    "params" :{
        "txID":"ZGYTSU8w3zUP6VFseGC798vA2Vnxnfj6fz1QPfA9N93bhjJvo",
        "encoding": "json"
    }
}' -H 'content-type:application/json;' https://api.avax.network/ext/bc/X
```

**Response**:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "tx": {
      "unsignedTx": {
        "networkID": 1,
        "blockchainID": "2oYMBNV4eNHyqk2fjjV5nVQLDbtmNJzq5s3qs3Lo6ftnC6FByM",
        "outputs": [
          {
            "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z",
            "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ",
            "output": {
              "addresses": ["X-avax1wst8jt3z3fm9ce0z6akj3266zmgccdp03hjlaj"],
              "amount": 4999000000,
              "locktime": 0,
              "threshold": 1
            }
          },
          {
            "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z",
            "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ",
            "output": {
              "addresses": ["X-avax1slt2dhfu6a6qezcn5sgtagumq8ag8we75f84sw"],
              "amount": 2347999000000,
              "locktime": 0,
              "threshold": 1
            }
          }
        ],
        "inputs": [
          {
            "txID": "qysTYUMCWdsR3MctzyfXiSvoSf6evbeFGRLLzA4j2BjNXTknh",
            "outputIndex": 0,
            "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z",
            "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ",
            "input": {
              "amount": 2352999000000,
              "signatureIndices": [0]
            }
          }
        ],
        "memo": "0x"
      },
      "credentials": [
        {
          "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ",
          "credential": {
            "signatures": [
              "0xbeb83d3d29f1247efb4a3a1141ab5c966f46f946f9c943b9bc19f858bd416d10060c23d5d9c7db3a0da23446b97cd9cf9f8e61df98e1b1692d764c84a686f5f801"
            ]
          }
        }
      ]
    },
    "encoding": "json"
  },
  "id": 1
}
```

# Admin RPC (/docs/rpcs/other)

---
title: "Admin RPC"
description: "This page is an overview of the Admin RPC associated with AvalancheGo."
edit_url: https://github.com/ava-labs/avalanchego/edit/master/api/admin/service.md
---

The Admin API can be used for measuring node health and debugging.

<Callout title="Note">
The Admin API is disabled by default for security reasons. To run a node with the Admin API enabled, use [`config flag --api-admin-enabled=true`](https://build.avax.network/docs/nodes/configure/configs-flags#--api-admin-enabled-boolean).

This API set is for a specific node, it is unavailable on the [public server](https://build.avax.network/docs/tooling/rpc-providers).
</Callout>

## Format

This API uses the `json 2.0` RPC format. For details, see [here](https://build.avax.network/docs/api-reference/guides/issuing-api-calls).

## Endpoint

```
/ext/admin
```

## Methods

### `admin.alias`

Assign an API endpoint an alias, a different endpoint for the API. The original endpoint will still work. This change only affects this node; other nodes will not know about this alias.

**Signature**:

```
admin.alias({endpoint:string, alias:string}) -> {}
```

- `endpoint` is the original endpoint of the API. `endpoint` should only include the part of the endpoint after `/ext/`.
- The API being aliased can now be called at `ext/alias`.
- `alias` can be at most 512 characters.

**Example Call**:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin.alias",
    "params": {
        "alias":"myAlias",
        "endpoint":"bc/X"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/admin
```

**Example Response**:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {}
}
```

Now, calls to the X-Chain can be made to either `/ext/bc/X` or, equivalently, to `/ext/myAlias`.

### `admin.aliasChain`

Give a blockchain an alias, a different name that can be used any place the blockchain's ID is used.

<Callout title="Note">
Aliasing a chain can also be done via the [Node API](https://build.avax.network/docs/nodes/configure/configs-flags#--chain-aliases-file-string).

Note that the alias is set for each chain on each node individually. In a multi-node Avalanche L1, the same alias should be configured on each node to use an alias across an Avalanche L1 successfully. Setting an alias for a chain on one node does not register that alias with other nodes automatically.
</Callout>

**Signature**:

```
admin.aliasChain(
    {
        chain:string,
        alias:string
    }
) -> {}
```

- `chain` is the blockchain's ID.
- `alias` can now be used in place of the blockchain's ID (in API endpoints, for example.)

**Example Call**:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin.aliasChain",
    "params": {
        "chain":"sV6o671RtkGBcno1FiaDbVcFv2sG5aVXMZYzKdP4VQAWmJQnM",
        "alias":"myBlockchainAlias"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/admin
```

**Example Response**:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {}
}
```

Now, instead of interacting with the blockchain whose ID is `sV6o671RtkGBcno1FiaDbVcFv2sG5aVXMZYzKdP4VQAWmJQnM` by making API calls to `/ext/bc/sV6o671RtkGBcno1FiaDbVcFv2sG5aVXMZYzKdP4VQAWmJQnM`, one can also make calls to `ext/bc/myBlockchainAlias`.

### `admin.getChainAliases`

Returns the aliases of the chain

**Signature**:

```
admin.getChainAliases(
  {
    chain:string
  }
) -> {aliases:string[]}
```

- `chain` is the blockchain's ID.

**Example Call**:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin.getChainAliases",
    "params": {
        "chain":"sV6o671RtkGBcno1FiaDbVcFv2sG5aVXMZYzKdP4VQAWmJQnM"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/admin
```

**Example Response**:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "aliases": [
      "X",
      "avm",
      "2eNy1mUFdmaxXNj1eQHUe7Np4gju9sJsEtWQ4MX3ToiNKuADed"
    ]
  },
  "id": 1
}
```

### `admin.getLoggerLevel`

Returns log and display levels of loggers.

**Signature**:

```
admin.getLoggerLevel(
  {
    loggerName:string // optional
  }
) -> {
        loggerLevels: {
          loggerName: {
            logLevel: string,
            displayLevel: string
          }
        }
    }
```

- `loggerName` is the name of the logger to be returned. This is an optional argument. If not specified, it returns all possible loggers.

**Example Call**:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin.getLoggerLevel",
    "params": {
        "loggerName": "C"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/admin
```

**Example Response**:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "loggerLevels": {
      "C": {
        "logLevel": "DEBUG",
        "displayLevel": "INFO"
      }
    }
  },
  "id": 1
}
```

### `admin.loadVMs`

Dynamically loads any virtual machines installed on the node as plugins. See [here](https://build.avax.network/docs/virtual-machines#installing-a-vm) for more information on how to install a virtual machine on a node.

**Signature**:

```
admin.loadVMs() -> {
  newVMs: map[string][]string
  failedVMs: map[string]string,
}
```

- `failedVMs` is only included in the response if at least one virtual machine fails to be loaded.

**Example Call**:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin.loadVMs",
    "params" :{}
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/admin
```

**Example Response**:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "newVMs": {
      "tGas3T58KzdjLHhBDMnH2TvrddhqTji5iZAMZ3RXs2NLpSnhH": ["foovm"]
    },
    "failedVMs": {
      "rXJsCSEYXg2TehWxCEEGj6JU2PWKTkd6cBdNLjoe2SpsKD9cy": "error message"
    }
  },
  "id": 1
}
```

### `admin.lockProfile`

Writes a profile of mutex statistics to `lock.profile`.

**Signature**:

```
admin.lockProfile() -> {}
```

**Example Call**:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin.lockProfile",
    "params" :{}
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/admin
```

**Example Response**:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {}
}
```

### `admin.memoryProfile`

Writes a memory profile of the to `mem.profile`.

**Signature**:

```
admin.memoryProfile() -> {}
```

**Example Call**:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin.memoryProfile",
    "params" :{}
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/admin
```

**Example Response**:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {}
}
```

### `admin.setLoggerLevel`

Sets log and display levels of loggers.

**Signature**:

```
admin.setLoggerLevel(
  {
    loggerName: string, // optional
    logLevel: string, // optional
    displayLevel: string, // optional
  }
) -> {}
```

- `loggerName` is the logger's name to be changed. This is an optional parameter. If not specified, it changes all possible loggers.
- `logLevel` is the log level of written logs, can be omitted.
- `displayLevel` is the log level of displayed logs, can be omitted.

`logLevel` and `displayLevel` cannot be omitted at the same time.

**Example Call**:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin.setLoggerLevel",
    "params": {
        "loggerName": "C",
        "logLevel": "DEBUG",
        "displayLevel": "INFO"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/admin
```

**Example Response**:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {}
}
```

### `admin.startCPUProfiler`

Start profiling the CPU utilization of the node. To stop, call `admin.stopCPUProfiler`. On stop, writes the profile to `cpu.profile`.

**Signature**:

```
admin.startCPUProfiler() -> {}
```

**Example Call**:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin.startCPUProfiler",
    "params" :{}
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/admin
```

**Example Response**:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {}
}
```

### `admin.stopCPUProfiler`

Stop the CPU profile that was previously started.

**Signature**:

```
admin.stopCPUProfiler() -> {}
```

**Example Call**:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin.stopCPUProfiler"
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/admin
```

**Example Response**:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {}
}
```

# Info RPC (/docs/rpcs/other/info-rpc)

---
title: "Info RPC"
description: "This page is an overview of the Info RPC associated with AvalancheGo."
edit_url: https://github.com/ava-labs/avalanchego/edit/master/api/info/service.md
---

The Info API can be used to access basic information about an Avalanche node.

## Format

This API uses the `json 2.0` RPC format. For more information on making JSON RPC calls, see [here](https://build.avax.network/docs/api-reference/guides/issuing-api-calls).

## Endpoint

```
/ext/info
```

## Methods

### `info.acps`

Returns peer preferences for Avalanche Community Proposals (ACPs)

**Signature**:

```
info.acps() -> {
  acps: map[uint32]{
    supportWeight: uint64
    supporters:    set[string]
    objectWeight:  uint64
    objectors:     set[string]
    abstainWeight: uint64
  }
}
```

**Example Call**:

```sh
curl -sX POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"info.acps",
    "params" :{}
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info
```

**Example Response**:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "acps": {
      "23": {
        "supportWeight": "0",
        "supporters": [],
        "objectWeight": "0",
        "objectors": [],
        "abstainWeight": "161147778098286584"
      },
      "24": {
        "supportWeight": "0",
        "supporters": [],
        "objectWeight": "0",
        "objectors": [],
        "abstainWeight": "161147778098286584"
      },
      "25": {
        "supportWeight": "0",
        "supporters": [],
        "objectWeight": "0",
        "objectors": [],
        "abstainWeight": "161147778098286584"
      },
      "30": {
        "supportWeight": "0",
        "supporters": [],
        "objectWeight": "0",
        "objectors": [],
        "abstainWeight": "161147778098286584"
      },
      "31": {
        "supportWeight": "0",
        "supporters": [],
        "objectWeight": "0",
        "objectors": [],
        "abstainWeight": "161147778098286584"
      },
      "41": {
        "supportWeight": "0",
        "supporters": [],
        "objectWeight": "0",
        "objectors": [],
        "abstainWeight": "161147778098286584"
      },
      "62": {
        "supportWeight": "0",
        "supporters": [],
        "objectWeight": "0",
        "objectors": [],
        "abstainWeight": "161147778098286584"
      }
    }
  },
  "id": 1
}
```

### `info.isBootstrapped`

Check whether a given chain is done bootstrapping

**Signature**:

```
info.isBootstrapped({chain: string}) -> {isBootstrapped: bool}
```

`chain` is the ID or alias of a chain.

**Example Call**:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"info.isBootstrapped",
    "params": {
        "chain":"X"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info
```

**Example Response**:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "isBootstrapped": true
  },
  "id": 1
}
```

### `info.getBlockchainID`

Given a blockchain's alias, get its ID. (See [`admin.aliasChain`](https://build.avax.network/docs/api-reference/admin-api#adminaliaschain).)

**Signature**:

```
info.getBlockchainID({alias:string}) -> {blockchainID:string}
```

**Example Call**:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"info.getBlockchainID",
    "params": {
        "alias":"X"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info
```

**Example Response**:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "blockchainID": "sV6o671RtkGBcno1FiaDbVcFv2sG5aVXMZYzKdP4VQAWmJQnM"
  }
}
```

### `info.getNetworkID`

Get the ID of the network this node is participating in.

**Signature**:

```
info.getNetworkID() -> { networkID: int }
```

**Example Call**:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"info.getNetworkID"
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info
```

**Example Response**:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "networkID": "2"
  }
}
```

Network ID of 1 = Mainnet Network ID of 5 = Fuji (testnet)

### `info.getNetworkName`

Get the name of the network this node is participating in.

**Signature**:

```
info.getNetworkName() -> { networkName:string }
```

**Example Call**:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"info.getNetworkName"
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info
```

**Example Response**:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "networkName": "local"
  }
}
```

### `info.getNodeID`

Get the ID, the BLS key, and the proof of possession(BLS signature) of this node.

<Callout title="Note">
This endpoint set is for a specific node, it is unavailable on the [public server](https://build.avax.network/docs/tooling/rpc-providers).
</Callout>

**Signature**:

```
info.getNodeID() -> {
    nodeID: string,
    nodePOP: {
        publicKey: string,
        proofOfPossession: string
    }
}
```

- `nodeID` Node ID is the unique identifier of the node that you set to act as a validator on the Primary Network.
- `nodePOP` is this node's BLS key and proof of possession. Nodes must register a BLS key to act as a validator on the Primary Network. Your node's POP is logged on startup and is accessible over this endpoint.
  - `publicKey` is the 48 byte hex representation of the BLS key.
  - `proofOfPossession` is the 96 byte hex representation of the BLS signature.

**Example Call**:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"info.getNodeID"
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info
```

**Example Response**:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "nodeID": "NodeID-5mb46qkSBj81k9g9e4VFjGGSbaaSLFRzD",
    "nodePOP": {
      "publicKey": "0x8f95423f7142d00a48e1014a3de8d28907d420dc33b3052a6dee03a3f2941a393c2351e354704ca66a3fc29870282e15",
      "proofOfPossession": "0x86a3ab4c45cfe31cae34c1d06f212434ac71b1be6cfe046c80c162e057614a94a5bc9f1ded1a7029deb0ba4ca7c9b71411e293438691be79c2dbf19d1ca7c3eadb9c756246fc5de5b7b89511c7d7302ae051d9e03d7991138299b5ed6a570a98"
    }
  },
  "id": 1
}
```

### `info.getNodeIP`

Get the IP of this node.

<Callout title="Note">
This endpoint set is for a specific node, it is unavailable on the [public server](https://build.avax.network/docs/tooling/rpc-providers).
</Callout>

**Signature**:

```
info.getNodeIP() -> {ip: string}
```

**Example Call**:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"info.getNodeIP"
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info
```

**Example Response**:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "ip": "192.168.1.1:9651"
  },
  "id": 1
}
```

### `info.getNodeVersion`

Get the version of this node.

**Signature**:

```
info.getNodeVersion() -> {
  version: string,
  databaseVersion: string,
  gitCommit: string,
  vmVersions: map[string]string,
  rpcProtocolVersion: string,
}
```

where:

- `version` is this node's version
- `databaseVersion` is the version of the database this node is using
- `gitCommit` is the Git commit that this node was built from
- `vmVersions` is map where each key/value pair is the name of a VM, and the version of that VM this node runs
- `rpcProtocolVersion` is the RPCChainVM protocol version

**Example Call**:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"info.getNodeVersion"
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info
```

**Example Response**:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "version": "avalanche/1.9.1",
    "databaseVersion": "v1.4.5",
    "rpcProtocolVersion": "18",
    "gitCommit": "79cd09ba728e1cecef40acd60702f0a2d41ea404",
    "vmVersions": {
      "avm": "v1.9.1",
      "evm": "v0.11.1",
      "platform": "v1.9.1"
    }
  },
  "id": 1
}
```

### `info.getTxFee`

<Callout type="warn">
Deprecated as of [v1.12.2](https://github.com/ava-labs/avalanchego/releases/tag/v1.12.2).
</Callout>

Get the fees of the network.

**Signature**:

```
info.getTxFee() ->
{
  txFee: uint64,
  createAssetTxFee: uint64,
  createSubnetTxFee: uint64,
  transformSubnetTxFee: uint64,
  createBlockchainTxFee: uint64,
  addPrimaryNetworkValidatorFee: uint64,
  addPrimaryNetworkDelegatorFee: uint64,
  addSubnetValidatorFee: uint64,
  addSubnetDelegatorFee: uint64
}
```

- `txFee` is the default fee for issuing X-Chain transactions.
- `createAssetTxFee` is the fee for issuing a `CreateAssetTx` on the X-Chain.
- `createSubnetTxFee` is no longer used.
- `transformSubnetTxFee` is no longer used.
- `createBlockchainTxFee` is no longer used.
- `addPrimaryNetworkValidatorFee` is no longer used.
- `addPrimaryNetworkDelegatorFee` is no longer used.
- `addSubnetValidatorFee` is no longer used.
- `addSubnetDelegatorFee` is no longer used.

All fees are denominated in nAVAX.

**Example Call**:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"info.getTxFee"
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info
```

**Example Response**:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "txFee": "1000000",
    "createAssetTxFee": "10000000",
    "createSubnetTxFee": "1000000000",
    "transformSubnetTxFee": "10000000000",
    "createBlockchainTxFee": "1000000000",
    "addPrimaryNetworkValidatorFee": "0",
    "addPrimaryNetworkDelegatorFee": "0",
    "addSubnetValidatorFee": "1000000",
    "addSubnetDelegatorFee": "1000000"
  }
}
```

### `info.getVMs`

Get the virtual machines installed on this node.

<Callout title="Note">
This endpoint set is for a specific node, it is unavailable on the [public server](https://build.avax.network/docs/tooling/rpc-providers).
</Callout>

**Signature**:

```
info.getVMs() -> {
  vms: map[string][]string
}
```

**Example Call**:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"info.getVMs",
    "params" :{}
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info
```

**Example Response**:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "vms": {
      "jvYyfQTxGMJLuGWa55kdP2p2zSUYsQ5Raupu4TW34ZAUBAbtq": ["avm"],
      "mgj786NP7uDwBCcq6YwThhaN8FLyybkCa4zBWTQbNgmK6k9A6": ["evm"],
      "qd2U4HDWUvMrVUeTcCHp6xH3Qpnn1XbU5MDdnBoiifFqvgXwT": ["nftfx"],
      "rWhpuQPF1kb72esV2momhMuTYGkEb1oL29pt2EBXWmSy4kxnT": ["platform"],
      "rXJsCSEYXg2TehWxCEEGj6JU2PWKTkd6cBdNLjoe2SpsKD9cy": ["propertyfx"],
      "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ": ["secp256k1fx"]
    }
  },
  "id": 1
}
```

### `info.peers`

Get a description of peer connections.

**Signature**:

```
info.peers({
  nodeIDs: string[] // optional
}) ->
{
  numPeers: int,
  peers:[]{
    ip: string,
    publicIP: string,
    nodeID: string,
    version: string,
    lastSent: string,
    lastReceived: string,
    benched: string[],
    observedUptime: int,
  }
}
```

- `nodeIDs` is an optional parameter to specify what NodeID's descriptions should be returned. If this parameter is left empty, descriptions for all active connections will be returned. If the node is not connected to a specified NodeID, it will be omitted from the response.
- `ip` is the remote IP of the peer.
- `publicIP` is the public IP of the peer.
- `nodeID` is the prefixed Node ID of the peer.
- `version` shows which version the peer runs on.
- `lastSent` is the timestamp of last message sent to the peer.
- `lastReceived` is the timestamp of last message received from the peer.
- `benched` shows chain IDs that the peer is currently benched on.
- `observedUptime` is this node's primary network uptime, observed by the peer.

**Example Call**:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"info.peers",
    "params": {
        "nodeIDs": []
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info
```

**Example Response**:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "numPeers": 3,
    "peers": [
      {
        "ip": "206.189.137.87:9651",
        "publicIP": "206.189.137.87:9651",
        "nodeID": "NodeID-8PYXX47kqLDe2wD4oPbvRRchcnSzMA4J4",
        "version": "avalanche/1.9.4",
        "lastSent": "2020-06-01T15:23:02Z",
        "lastReceived": "2020-06-01T15:22:57Z",
        "benched": [],
        "observedUptime": "99",
        "trackedSubnets": [],
        "benched": []
      },
      {
        "ip": "158.255.67.151:9651",
        "publicIP": "158.255.67.151:9651",
        "nodeID": "NodeID-C14fr1n8EYNKyDfYixJ3rxSAVqTY3a8BP",
        "version": "avalanche/1.9.4",
        "lastSent": "2020-06-01T15:23:02Z",
        "lastReceived": "2020-06-01T15:22:34Z",
        "benched": [],
        "observedUptime": "75",
        "trackedSubnets": [
          "29uVeLPJB1eQJkzRemU8g8wZDw5uJRqpab5U2mX9euieVwiEbL"
        ],
        "benched": []
      },
      {
        "ip": "83.42.13.44:9651",
        "publicIP": "83.42.13.44:9651",
        "nodeID": "NodeID-LPbcSMGJ4yocxYxvS2kBJ6umWeeFbctYZ",
        "version": "avalanche/1.9.3",
        "lastSent": "2020-06-01T15:23:02Z",
        "lastReceived": "2020-06-01T15:22:55Z",
        "benched": [],
        "observedUptime": "95",
        "trackedSubnets": [],
        "benched": []
      }
    ]
  }
}
```

### `info.uptime`

Returns the network's observed uptime of this node. This is the only reliable source of data for your node's uptime. Other sources may be using data gathered with incomplete (limited) information.

**Signature**:

```
info.uptime() ->
{
  rewardingStakePercentage: float64,
  weightedAveragePercentage: float64
}
```

- `rewardingStakePercentage` is the percent of stake which thinks this node is above the uptime requirement.
- `weightedAveragePercentage` is the stake-weighted average of all observed uptimes for this node.

**Example Call**:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"info.uptime"
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info
```

**Example Response**:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "rewardingStakePercentage": "100.0000",
    "weightedAveragePercentage": "99.0000"
  }
}
```

#### Example Avalanche L1 Call

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"info.uptime",
    "params" :{
        "subnetID":"29uVeLPJB1eQJkzRemU8g8wZDw5uJRqpab5U2mX9euieVwiEbL"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info
```

#### Example Avalanche L1 Response

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "rewardingStakePercentage": "74.0741",
    "weightedAveragePercentage": "72.4074"
  }
}
```

### `info.upgrades`

Returns the upgrade history and configuration of the network.

**Example Call**:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"info.upgrades"
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info
```

**Example Response**:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "apricotPhase1Time": "2020-12-05T05:00:00Z",
    "apricotPhase2Time": "2020-12-05T05:00:00Z",
    "apricotPhase3Time": "2020-12-05T05:00:00Z",
    "apricotPhase4Time": "2020-12-05T05:00:00Z",
    "apricotPhase4MinPChainHeight": 0,
    "apricotPhase5Time": "2020-12-05T05:00:00Z",
    "apricotPhasePre6Time": "2020-12-05T05:00:00Z",
    "apricotPhase6Time": "2020-12-05T05:00:00Z",
    "apricotPhasePost6Time": "2020-12-05T05:00:00Z",
    "banffTime": "2020-12-05T05:00:00Z",
    "cortinaTime": "2020-12-05T05:00:00Z",
    "cortinaXChainStopVertexID": "11111111111111111111111111111111LpoYY",
    "durangoTime": "2020-12-05T05:00:00Z",
    "etnaTime": "2024-10-09T20:00:00Z",
    "fortunaTime": "9999-12-01T05:00:00Z",
    "graniteTime": "9999-12-01T05:00:00Z"
  },
  "id": 1
}
```

# Metrics RPC (/docs/rpcs/other/metrics-rpc)

---
title: "Metrics RPC"
description: "This page is an overview of the Metrics RPC associated with AvalancheGo."
edit_url: https://github.com/ava-labs/avalanchego/edit/master/api/metrics/service.md
---

The Metrics API allows clients to get statistics about a node's health and performance.

<Callout title="Note">
This API set is for a specific node, it is unavailable on the [public server](https://build.avax.network/docs/tooling/rpc-providers).
</Callout>

## Endpoint

```
/ext/metrics
```

## Usage

To get the node metrics:

```sh
curl -X POST 127.0.0.1:9650/ext/metrics
```

## Format

This API produces Prometheus compatible metrics. See [here](https://prometheus.io/docs/instrumenting/exposition_formats) for information on Prometheus' formatting.

[Here](https://build.avax.network/docs/nodes/maintain/monitoring) is a tutorial that shows how to set up Prometheus and Grafana to monitor AvalancheGo node using the Metrics API.

# ProposerVM RPC (/docs/rpcs/other/proposervm-rpc)

---
title: "ProposerVM RPC"
description: "This page is an overview of the ProposerVM RPC associated with AvalancheGo."
edit_url: https://github.com/ava-labs/avalanchego/edit/master/vms/proposervm/service.md
---

# ProposerVM API

The ProposerVM API allows clients to fetch information about a chain's Snowman++ wrapper information.

## Endpoint

```text
/ext/bc/{blockchainID}/proposervm
```

## Format

This API uses the `JSON-RPC 2.0` RPC format.

## Methods

### `proposervm.getProposedHeight`

Returns this node's current proposer VM height.

**Signature:**

```
proposervm.getProposedHeight() ->
{
  height: int,
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "proposervm.getProposedHeight",
    "params": {},
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P/proposervm
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "height": "56"
  },
  "id": 1
}
```

### `proposervm.getCurrentEpoch`

Returns the current epoch information.

**Signature:**

```
proposervm.getCurrentEpoch() ->
{
  number: int,
  startTime: int,
  pChainHeight: int
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "proposervm.getCurrentEpoch",
    "params": {},
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P/proposervm
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "number": "56",
    "startTime":"1755802182",
    "pChainHeight": "21857141"
  },
  "id": 1
}
```

# AvalancheGo P-Chain RPC (/docs/rpcs/p-chain)

---
title: "AvalancheGo P-Chain RPC"
description: "This page is an overview of the P-Chain RPC associated with AvalancheGo."
edit_url: https://github.com/ava-labs/avalanchego/edit/master/vms/platformvm/service.md
---

The P-Chain API allows clients to interact with the [P-Chain](https://build.avax.network/docs/quick-start/primary-network#p-chain), which maintains Avalanche’s validator set and handles blockchain creation.

## Endpoint

```
/ext/bc/P
```

## Format

This API uses the `json 2.0` RPC format.

## Methods

### `platform.getBalance`

<Callout title="Caution" type="warn">

Deprecated as of [**v1.9.12**](https://github.com/ava-labs/avalanchego/releases/tag/v1.9.12).

</Callout>

Get the balance of AVAX controlled by a given address.

**Signature:**

```
platform.getBalance({
    addresses: []string
}) -> {
    balances: string -> int,
    unlockeds: string -> int,
    lockedStakeables: string -> int,
    lockedNotStakeables: string -> int,
    utxoIDs: []{
        txID: string,
        outputIndex: int
    }
}
```

- `addresses` are the addresses to get the balance of.
- `balances` is a map from assetID to the total balance.
- `unlockeds` is a map from assetID to the unlocked balance.
- `lockedStakeables` is a map from assetID to the locked stakeable balance.
- `lockedNotStakeables` is a map from assetID to the locked and not stakeable balance.
- `utxoIDs` are the IDs of the UTXOs that reference `address`.

**Example Call:**

```sh
curl -X POST --data '{
  "jsonrpc":"2.0",
  "id"     : 1,
  "method" :"platform.getBalance",
  "params" :{
      "addresses":["P-custom18jma8ppw3nhx5r4ap8clazz0dps7rv5u9xde7p"]
  }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "balance": "30000000000000000",
    "unlocked": "20000000000000000",
    "lockedStakeable": "10000000000000000",
    "lockedNotStakeable": "0",
    "balances": {
      "BUuypiq2wyuLMvyhzFXcPyxPMCgSp7eeDohhQRqTChoBjKziC": "30000000000000000"
    },
    "unlockeds": {
      "BUuypiq2wyuLMvyhzFXcPyxPMCgSp7eeDohhQRqTChoBjKziC": "20000000000000000"
    },
    "lockedStakeables": {
      "BUuypiq2wyuLMvyhzFXcPyxPMCgSp7eeDohhQRqTChoBjKziC": "10000000000000000"
    },
    "lockedNotStakeables": {},
    "utxoIDs": [
      {
        "txID": "11111111111111111111111111111111LpoYY",
        "outputIndex": 1
      },
      {
        "txID": "11111111111111111111111111111111LpoYY",
        "outputIndex": 0
      }
    ]
  },
  "id": 1
}
```

### `platform.getBlock`

Get a block by its ID.

**Signature:**

```
platform.getBlock({
    blockID: string
    encoding: string // optional
}) -> {
    block: string,
    encoding: string
}
```

**Request:**

- `blockID` is the block ID. It should be in cb58 format.
- `encoding` is the encoding format to use. Can be either `hex` or `json`. Defaults to `hex`.

**Response:**

- `block` is the block encoded to `encoding`.
- `encoding` is the `encoding`.

#### Hex Example

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getBlock",
    "params": {
        "blockID": "d7WYmb8VeZNHsny3EJCwMm6QA37s1EHwMxw1Y71V3FqPZ5EFG",
        "encoding": "hex"
    },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "block": "0x00000000000309473dc99a0851a29174d84e522da8ccb1a56ac23f7b0ba79f80acce34cf576900000000000f4241000000010000001200000001000000000000000000000000000000000000000000000000000000000000000000000000000000011c4c57e1bcb3c567f9f03caa75563502d1a21393173c06d9d79ea247b20e24800000000021e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff000000050000000338e0465f0000000100000000000000000427d4b22a2a78bcddd456742caf91b56badbff985ee19aef14573e7343fd6520000000121e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff000000070000000338d1041f0000000000000000000000010000000195a4467dd8f939554ea4e6501c08294386938cbf000000010000000900000001c79711c4b48dcde205b63603efef7c61773a0eb47efb503fcebe40d21962b7c25ebd734057400a12cce9cf99aceec8462923d5d91fffe1cb908372281ed738580119286dde",
    "encoding": "hex"
  },
  "id": 1
}
```

#### JSON Example

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getBlock",
    "params": {
        "blockID": "d7WYmb8VeZNHsny3EJCwMm6QA37s1EHwMxw1Y71V3FqPZ5EFG",
        "encoding": "json"
    },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "block": {
      "parentID": "5615di9ytxujackzaXNrVuWQy5y8Yrt8chPCscMr5Ku9YxJ1S",
      "height": 1000001,
      "txs": [
        {
          "unsignedTx": {
            "inputs": {
              "networkID": 1,
              "blockchainID": "11111111111111111111111111111111LpoYY",
              "outputs": [],
              "inputs": [
                {
                  "txID": "DTqiagiMFdqbNQ62V2Gt1GddTVLkKUk2caGr4pyza9hTtsfta",
                  "outputIndex": 0,
                  "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z",
                  "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ",
                  "input": {
                    "amount": 13839124063,
                    "signatureIndices": [0]
                  }
                }
              ],
              "memo": "0x"
            },
            "destinationChain": "2q9e4r6Mu3U68nU1fYjgbR6JvwrRx36CohpAX5UQxse55x1Q5",
            "exportedOutputs": [
              {
                "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z",
                "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ",
                "output": {
                  "addresses": [
                    "P-avax1jkjyvlwclyu42n4yuegpczpfgwrf8r9lyj0d3c"
                  ],
                  "amount": 13838124063,
                  "locktime": 0,
                  "threshold": 1
                }
              }
            ]
          },
          "credentials": [
            {
              "signatures": [
                "0xc79711c4b48dcde205b63603efef7c61773a0eb47efb503fcebe40d21962b7c25ebd734057400a12cce9cf99aceec8462923d5d91fffe1cb908372281ed7385801"
              ]
            }
          ]
        }
      ]
    },
    "encoding": "json"
  },
  "id": 1
}
```

### `platform.getBlockByHeight`

Get a block by its height.

**Signature:**

```
platform.getBlockByHeight({
    height: int
    encoding: string // optional
}) -> {
    block: string,
    encoding: string
}
```

**Request:**

- `height` is the block height.
- `encoding` is the encoding format to use. Can be either `hex` or `json`. Defaults to `hex`.

**Response:**

- `block` is the block encoded to `encoding`.
- `encoding` is the `encoding`.

#### Hex Example

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getBlockByHeight",
    "params": {
        "height": 1000001,
        "encoding": "hex"
    },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "block": "0x00000000000309473dc99a0851a29174d84e522da8ccb1a56ac23f7b0ba79f80acce34cf576900000000000f4241000000010000001200000001000000000000000000000000000000000000000000000000000000000000000000000000000000011c4c57e1bcb3c567f9f03caa75563502d1a21393173c06d9d79ea247b20e24800000000021e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff000000050000000338e0465f0000000100000000000000000427d4b22a2a78bcddd456742caf91b56badbff985ee19aef14573e7343fd6520000000121e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff000000070000000338d1041f0000000000000000000000010000000195a4467dd8f939554ea4e6501c08294386938cbf000000010000000900000001c79711c4b48dcde205b63603efef7c61773a0eb47efb503fcebe40d21962b7c25ebd734057400a12cce9cf99aceec8462923d5d91fffe1cb908372281ed738580119286dde",
    "encoding": "hex"
  },
  "id": 1
}
```

#### JSON Example

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getBlockByHeight",
    "params": {
        "height": 1000001,
        "encoding": "json"
    },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "block": {
      "parentID": "5615di9ytxujackzaXNrVuWQy5y8Yrt8chPCscMr5Ku9YxJ1S",
      "height": 1000001,
      "txs": [
        {
          "unsignedTx": {
            "inputs": {
              "networkID": 1,
              "blockchainID": "11111111111111111111111111111111LpoYY",
              "outputs": [],
              "inputs": [
                {
                  "txID": "DTqiagiMFdqbNQ62V2Gt1GddTVLkKUk2caGr4pyza9hTtsfta",
                  "outputIndex": 0,
                  "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z",
                  "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ",
                  "input": {
                    "amount": 13839124063,
                    "signatureIndices": [0]
                  }
                }
              ],
              "memo": "0x"
            },
            "destinationChain": "2q9e4r6Mu3U68nU1fYjgbR6JvwrRx36CohpAX5UQxse55x1Q5",
            "exportedOutputs": [
              {
                "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z",
                "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ",
                "output": {
                  "addresses": [
                    "P-avax1jkjyvlwclyu42n4yuegpczpfgwrf8r9lyj0d3c"
                  ],
                  "amount": 13838124063,
                  "locktime": 0,
                  "threshold": 1
                }
              }
            ]
          },
          "credentials": [
            {
              "signatures": [
                "0xc79711c4b48dcde205b63603efef7c61773a0eb47efb503fcebe40d21962b7c25ebd734057400a12cce9cf99aceec8462923d5d91fffe1cb908372281ed7385801"
              ]
            }
          ]
        }
      ]
    },
    "encoding": "json"
  },
  "id": 1
}
```

### `platform.getBlockchains`

<Callout title="Caution" type="warn">

Deprecated as of [**v1.9.12**](https://github.com/ava-labs/avalanchego/releases/tag/v1.9.12).

</Callout>

Get all the blockchains that exist (excluding the P-Chain).

**Signature:**

```
platform.getBlockchains() ->
{
  blockchains: []{
    id: string,
    name: string,
    subnetID: string,
    vmID: string
  }
}
```

- `blockchains` is all of the blockchains that exists on the Avalanche network.
- `name` is the human-readable name of this blockchain.
- `id` is the blockchain’s ID.
- `subnetID` is the ID of the Subnet that validates this blockchain.
- `vmID` is the ID of the Virtual Machine the blockchain runs.

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getBlockchains",
    "params": {},
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "blockchains": [
      {
        "id": "2oYMBNV4eNHyqk2fjjV5nVQLDbtmNJzq5s3qs3Lo6ftnC6FByM",
        "name": "X-Chain",
        "subnetID": "11111111111111111111111111111111LpoYY",
        "vmID": "jvYyfQTxGMJLuGWa55kdP2p2zSUYsQ5Raupu4TW34ZAUBAbtq"
      },
      {
        "id": "2q9e4r6Mu3U68nU1fYjgbR6JvwrRx36CohpAX5UQxse55x1Q5",
        "name": "C-Chain",
        "subnetID": "11111111111111111111111111111111LpoYY",
        "vmID": "mgj786NP7uDwBCcq6YwThhaN8FLyybkCa4zBWTQbNgmK6k9A6"
      },
      {
        "id": "CqhF97NNugqYLiGaQJ2xckfmkEr8uNeGG5TQbyGcgnZ5ahQwa",
        "name": "Simple DAG Payments",
        "subnetID": "11111111111111111111111111111111LpoYY",
        "vmID": "sqjdyTKUSrQs1YmKDTUbdUhdstSdtRTGRbUn8sqK8B6pkZkz1"
      },
      {
        "id": "VcqKNBJsYanhVFxGyQE5CyNVYxL3ZFD7cnKptKWeVikJKQkjv",
        "name": "Simple Chain Payments",
        "subnetID": "11111111111111111111111111111111LpoYY",
        "vmID": "sqjchUjzDqDfBPGjfQq2tXW1UCwZTyvzAWHsNzF2cb1eVHt6w"
      },
      {
        "id": "2SMYrx4Dj6QqCEA3WjnUTYEFSnpqVTwyV3GPNgQqQZbBbFgoJX",
        "name": "Simple Timestamp Server",
        "subnetID": "11111111111111111111111111111111LpoYY",
        "vmID": "tGas3T58KzdjLHhBDMnH2TvrddhqTji5iZAMZ3RXs2NLpSnhH"
      },
      {
        "id": "KDYHHKjM4yTJTT8H8qPs5KXzE6gQH5TZrmP1qVr1P6qECj3XN",
        "name": "My new timestamp",
        "subnetID": "2bRCr6B4MiEfSjidDwxDpdCyviwnfUVqB2HGwhm947w9YYqb7r",
        "vmID": "tGas3T58KzdjLHhBDMnH2TvrddhqTji5iZAMZ3RXs2NLpSnhH"
      },
      {
        "id": "2TtHFqEAAJ6b33dromYMqfgavGPF3iCpdG3hwNMiart2aB5QHi",
        "name": "My new AVM",
        "subnetID": "2bRCr6B4MiEfSjidDwxDpdCyviwnfUVqB2HGwhm947w9YYqb7r",
        "vmID": "jvYyfQTxGMJLuGWa55kdP2p2zSUYsQ5Raupu4TW34ZAUBAbtq"
      }
    ]
  },
  "id": 1
}
```

### `platform.getBlockchainStatus`

Get the status of a blockchain.

**Signature:**

```
platform.getBlockchainStatus(
  {
    blockchainID: string
  }
) -> {status: string}
```

`status` is one of:

- `Validating`: The blockchain is being validated by this node.
- `Created`: The blockchain exists but isn’t being validated by this node.
- `Preferred`: The blockchain was proposed to be created and is likely to be created but the
  transaction isn’t yet accepted.
- `Syncing`: This node is participating in this blockchain as a non-validating node.
- `Unknown`: The blockchain either wasn’t proposed or the proposal to create it isn’t preferred. The
  proposal may be resubmitted.

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getBlockchainStatus",
    "params":{
        "blockchainID":"2NbS4dwGaf2p1MaXb65PrkZdXRwmSX4ZzGnUu7jm3aykgThuZE"
    },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "status": "Created"
  },
  "id": 1
}
```

### `platform.getCurrentSupply`

Returns an upper bound on amount of tokens that exist that can stake the requested Subnet. This is
an upper bound because it does not account for burnt tokens, including transaction fees.

**Signature:**

```
platform.getCurrentSupply ({
  subnetID: string // optional
}) -> { supply: int }
```

- `supply` is an upper bound on the number of tokens that exist.

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getCurrentSupply",
    "params": {
        "subnetID": "11111111111111111111111111111111LpoYY"
    },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "supply": "365865167637779183"
  },
  "id": 1
}
```

The response in this example indicates that AVAX’s supply is at most 365.865 million.

### `platform.getCurrentValidators`

List the current validators of the given Subnet.

**Signature:**

```
platform.getCurrentValidators({
  subnetID: string, // optional
  nodeIDs: string[], // optional
}) -> {
    validators: []{
        txID: string,
        startTime: string,
        endTime: string,
        nodeID: string,
        weight: string,
        validationID: string,
        publicKey: string,
        remainingBalanceOwner: {
            locktime: string,
            threshold: string,
            addresses: string[]
        },
        deactivationOwner: {
            locktime: string,
            threshold: string,
            addresses: string[]
        },
        minNonce: string,
        balance: string,
        validationRewardOwner: {
            locktime: string,
            threshold: string,
            addresses: string[]
        },
        delegationRewardOwner: {
            locktime: string,
            threshold: string,
            addresses: string[]
        },
        potentialReward: string,
        delegationFee: string,
        uptime: string,
        connected: bool,
        signer: {
            publicKey: string,
            proofOfPosession: string
        },
        delegatorCount: string,
        delegatorWeight: string,
        delegators: []{
            txID: string,
            startTime: string,
            endTime: string,
            weight: string,
            nodeID: string,
            rewardOwner: {
                locktime: string,
                threshold: string,
                addresses: string[]
            },
            potentialReward: string,
        }
    }
}
```

- `subnetID` is the Subnet whose current validators are returned. If omitted, returns the current
  validators of the Primary Network.
- `nodeIDs` is a list of the NodeIDs of current validators to request. If omitted, all current
  validators are returned. If a specified NodeID is not in the set of current validators, it will
  not be included in the response.
- `validators` can include different fields based on the subnet type (L1, PoA Subnets, the Primary Network):
  - `txID` is the validator transaction.
  - `startTime` is the Unix time when the validator starts validating the Subnet.
  - `endTime` is the Unix time when the validator stops validating the Subnet. Omitted if `subnetID` is a L1 Subnet.
  - `nodeID` is the validator’s node ID.
  - `weight` is the validator’s weight (stake) when sampling validators.
  - `validationID` is the ID for L1 subnet validator registration transaction. Omitted if `subnetID` is not an L1 Subnet.
  - `publicKey` is the compressed BLS public key of the validator. Omitted if `subnetID` is not an L1 Subnet.
  - `remainingBalanceOwner` is an `OutputOwners` which includes a `locktime`, `threshold`, and an array of `addresses`. It specifies the owner that will receive any withdrawn balance. Omitted if `subnetID` is not an L1 Subnet.
  - `deactivationOwner` is an `OutputOwners` which includes a `locktime`, `threshold`, and an array of `addresses`. It specifies the owner that can withdraw the balance. Omitted if `subnetID` is not an L1 Subnet.
  - `minNonce` is minimum nonce that must be included in a `SetL1ValidatorWeightTx` for the transaction to be valid. Omitted if `subnetID` is not an L1 Subnet.
  - `balance` is current remaining balance that can be used to pay for the validators continuous fee. Omitted if `subnetID` is not an L1 Subnet.
  - `validationRewardOwner` is an `OutputOwners` output which includes `locktime`, `threshold` and
    array of `addresses`. Specifies the owner of the potential reward earned from staking. Omitted
    if `subnetID` is not the Primary Network.
  - `delegationRewardOwner` is an `OutputOwners` output which includes `locktime`, `threshold` and
    array of `addresses`. Specifies the owner of the potential reward earned from delegations. Omitted if `subnetID` is not the Primary Network.
  - `potentialReward` is the potential reward earned from staking. Omitted if `subnetID` is not the Primary Network.
  - `delegationFeeRate` is the percent fee this validator charges when others delegate stake to
    them. Omitted if `subnetID` is not the Primary Network.
  - `uptime` is the % of time the queried node has reported the peer as online and validating the
    Subnet. Omitted if `subnetID` is not the Primary Network.
  - `connected` is if the node is connected and tracks the Subnet. Omitted if `subnetID` is not the Primary Network.
  - `signer` is the node's BLS public key and proof of possession. Omitted if the validator doesn't
    have a BLS public key. Omitted if `subnetID` is not the Primary Network.
  - `delegatorCount` is the number of delegators on this validator.
    Omitted if `subnetID` is not the Primary Network.
  - `delegatorWeight` is total weight of delegators on this validator.
    Omitted if `subnetID` is not the Primary Network.
  - `delegators` is the list of delegators to this validator. Omitted if `subnetID` is not the Primary Network. Omitted unless `nodeIDs` specifies a single NodeID.
    - `txID` is the delegator transaction.
    - `startTime` is the Unix time when the delegator started.
    - `endTime` is the Unix time when the delegator stops.
    - `weight` is the amount of nAVAX this delegator staked.
    - `nodeID` is the validating node’s node ID.
    - `rewardOwner` is an `OutputOwners` output which includes `locktime`, `threshold` and array of
      `addresses`.
    - `potentialReward` is the potential reward earned from staking

Note: An L1 Subnet can include both initial legacy PoA validators (before L1 conversion) and L1 validators. The response will include both types of validators.

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getCurrentValidators",
    "params": {
      "nodeIDs": ["NodeID-5mb46qkSBj81k9g9e4VFjGGSbaaSLFRzD"]
    },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response (Primary Network):**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "validators": [
      {
        "txID": "2NNkpYTGfTFLSGXJcHtVv6drwVU2cczhmjK2uhvwDyxwsjzZMm",
        "startTime": "1600368632",
        "endTime": "1602960455",
        "weight": "2000000000000",
        "nodeID": "NodeID-5mb46qkSBj81k9g9e4VFjGGSbaaSLFRzD",
        "validationRewardOwner": {
          "locktime": "0",
          "threshold": "1",
          "addresses": ["P-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5"]
        },
        "delegationRewardOwner": {
          "locktime": "0",
          "threshold": "1",
          "addresses": ["P-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5"]
        },
        "potentialReward": "117431493426",
        "delegationFee": "10.0000",
        "uptime": "0.0000",
        "connected": false,
        "delegatorCount": "1",
        "delegatorWeight": "25000000000",
        "delegators": [
          {
            "txID": "Bbai8nzGVcyn2VmeYcbS74zfjJLjDacGNVuzuvAQkHn1uWfoV",
            "startTime": "1600368523",
            "endTime": "1602960342",
            "weight": "25000000000",
            "nodeID": "NodeID-5mb46qkSBj81k9g9e4VFjGGSbaaSLFRzD",
            "rewardOwner": {
              "locktime": "0",
              "threshold": "1",
              "addresses": ["P-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5"]
            },
            "potentialReward": "11743144774"
          }
        ]
      }
    ]
  },
  "id": 1
}
```

**Example Response (L1):**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "validators": [
      {
        "validationID": "2wTscvX3JUsMbZHFRd9t8Ywz2q9j2BmETg8cTvgUHgawjbSvZX",
        "nodeID": "NodeID-5mb46qkSBj81k9g9e4VFjGGSbaaSLFRzD",
        "publicKey": "0x91951771ff32b1a985a4936592bce8512a986353c4c2eb5a0f12dbb76bda3a0a0c975e26413ff44c0ee9d8d689eff8ed",
        "remainingBalanceOwner": {
          "locktime": "0",
          "threshold": "1",
          "addresses": [
            "P-fuji1ywzvrftfqexh5g6qa9zyrytj6pqdfetza2hqln"
          ]
        },
        "deactivationOwner": {
          "locktime": "0",
          "threshold": "1",
          "addresses": [
            "P-fuji1ywzvrftfqexh5g6qa9zyrytj6pqdfetza2hqln"
          ]
        },
        "startTime": "1734034648",
        "weight": "20",
        "minNonce": "0",
        "balance": "8780477952"
      }
    ]
  },
  "id": 1
}
```

### `platform.getFeeConfig`

Returns the dynamic fee configuration of the P-chain.

**Signature:**

```
platform.getFeeConfig() -> {
  weights: []uint64,
  maxCapacity: uint64,
  maxPerSecond: uint64,
  targetPerSecond: uint64,
  minPrice: uint64,
  excessConversionConstant: uint64
}
```

- `weights` to merge fee dimensions into a single gas value
- `maxCapacity` is the amount of gas the chain is allowed to store for future use
- `maxPerSecond` is the amount of gas the chain is allowed to consume per second
- `targetPerSecond` is the target amount of gas the chain should consume per second to keep fees stable
- `minPrice` is the minimum price per unit of gas
- `excessConversionConstant` is used to convert excess gas to a gas price

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getFeeConfig",
    "params": {},
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "weights": [1, 1000, 1000, 4],
    "maxCapacity": 1000000,
    "maxPerSecond": 100000,
    "targetPerSecond": 50000,
    "minPrice": 1,
    "excessConversionConstant": 2164043
  },
  "id": 1
}
```

### `platform.getFeeState`

Returns the current fee state of the P-chain.

**Signature:**

```
platform.getFeeState() -> {
  capacity: uint64,
  excess: uint64,
  price: uint64,
  timestamp: string
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getFeeState",
    "params": {},
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "capacity": 973044,
    "excess": 26956,
    "price": 1,
    "timestamp": "2024-12-16T17:19:07Z"
  },
  "id": 1
}
```

### `platform.getHeight`

Returns the height of the last accepted block.

**Signature:**

```
platform.getHeight() ->
{
  height: int,
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getHeight",
    "params": {},
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "height": "56"
  },
  "id": 1
}
```

### `platform.getL1Validator`

Returns a current L1 validator.

**Signature:**

```
platform.getL1Validator({
    validationID: string,
}) -> {
    validationID: string,
    subnetID: string,
    nodeID: string,
    publicKey: string,
    remainingBalanceOwner: {
      locktime: string,
      threshold: string,
      addresses: string[]
    },
    deactivationOwner: {
      locktime: string,
      threshold: string,
      addresses: string[]
    },
    startTime: string,
    weight: string,
    minNonce: string,
    balance: string,
    height: string
}
```

- `validationID` is the ID for L1 subnet validator registration transaction.
- `subnetID` is the L1 this validator is validating.
- `nodeID` is the node ID of the validator.
- `publicKey` is the compressed BLS public key of the validator.
- `remainingBalanceOwner` is an `OutputOwners` which includes a `locktime`, `threshold`, and an array of `addresses`. It specifies the owner that will receive any withdrawn balance.
- `deactivationOwner` is an `OutputOwners` which includes a `locktime`, `threshold`, and an array of `addresses`. It specifies the owner that can withdraw the balance.
- `startTime` is the unix timestamp, in seconds, of when this validator was added to the validator set.
- `weight` is weight of this validator used for consensus voting and ICM.
- `minNonce` is minimum nonce that must be included in a `SetL1ValidatorWeightTx` for the transaction to be valid.
- `balance` is current remaining balance that can be used to pay for the validators continuous fee.
- `height` is height of the last accepted block.

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getL1Validator",
    "params": {
      "validationID": ["9FAftNgNBrzHUMMApsSyV6RcFiL9UmCbvsCu28xdLV2mQ7CMo"]
    },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "subnetID": "2DeHa7Qb6sufPkmQcFWG2uCd4pBPv9WB6dkzroiMQhd1NSRtof",
    "nodeID": "NodeID-7Xhw2mDxuDS44j42TCB6U5579esbSt3Lg",
    "validationID": "9FAftNgNBrzHUMMApsSyV6RcFiL9UmCbvsCu28xdLV2mQ7CMo",
    "publicKey": "0x900c9b119b5c82d781d4b49be78c3fc7ae65f2b435b7ed9e3a8b9a03e475edff86d8a64827fec8db23a6f236afbf127d",
    "remainingBalanceOwner": {
      "locktime": "0",
      "threshold": "0",
      "addresses": []
    },
    "deactivationOwner": {
      "locktime": "0",
      "threshold": "0",
      "addresses": []
    },
    "startTime": "1731445206",
    "weight": "49463",
    "minNonce": "0",
    "balance": "1000000000",
    "height": "3"
  },
  "id": 1
}
```

### `platform.getProposedHeight`

Returns this node's current proposer VM height

**Signature:**

```
platform.getProposedHeight() ->
{
  height: int,
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getProposedHeight",
    "params": {},
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "height": "56"
  },
  "id": 1
}
```

### `platform.getMinStake`

Get the minimum amount of tokens required to validate the requested Subnet and the minimum amount of
tokens that can be delegated.

**Signature:**

```
platform.getMinStake({
  subnetID: string // optional
}) ->
{
  minValidatorStake : uint64,
  minDelegatorStake : uint64
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"platform.getMinStake",
    "params": {
        "subnetID":"11111111111111111111111111111111LpoYY"
    },
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "minValidatorStake": "2000000000000",
    "minDelegatorStake": "25000000000"
  },
  "id": 1
}
```

### `platform.getRewardUTXOs`

<Callout title="Caution" type="warn">

Deprecated as of [**v1.9.12**](https://github.com/ava-labs/avalanchego/releases/tag/v1.9.12).

</Callout>

Returns the UTXOs that were rewarded after the provided transaction's staking or delegation period
ended.

**Signature:**

```
platform.getRewardUTXOs({
    txID: string,
    encoding: string // optional
}) -> {
    numFetched: integer,
    utxos: []string,
    encoding: string
}
```

- `txID` is the ID of the staking or delegating transaction
- `numFetched` is the number of returned UTXOs
- `utxos` is an array of encoded reward UTXOs
- `encoding` specifies the format for the returned UTXOs. Can only be `hex` when a value is
  provided.

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getRewardUTXOs",
    "params": {
        "txID": "2nmH8LithVbdjaXsxVQCQfXtzN9hBbmebrsaEYnLM9T32Uy2Y5"
    },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "numFetched": "2",
    "utxos": [
      "0x0000a195046108a85e60f7a864bb567745a37f50c6af282103e47cc62f036cee404700000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216c1f01765",
      "0x0000ae8b1b94444eed8de9a81b1222f00f1b4133330add23d8ac288bffa98b85271100000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216473d042a"
    ],
    "encoding": "hex"
  },
  "id": 1
}
```

### `platform.getStake`

<Callout title="Caution" type="warn">

Deprecated as of [**v1.9.12**](https://github.com/ava-labs/avalanchego/releases/tag/v1.9.12).

</Callout>

Get the amount of nAVAX staked by a set of addresses. The amount returned does not include staking
rewards.

**Signature:**

```
platform.getStake({
    addresses: []string,
    validatorsOnly: true or false
}) ->
{
    stakeds: string -> int,
    stakedOutputs:  []string,
    encoding: string
}
```

- `addresses` are the addresses to get information about.
- `validatorsOnly` can be either `true` or `false`. If `true`, will skip checking delegators for stake.
- `stakeds` is a map from assetID to the amount staked by addresses provided.
- `stakedOutputs` are the string representation of staked outputs.
- `encoding` specifies the format for the returned outputs.

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getStake",
    "params": {
        "addresses": [
            "P-avax1pmgmagjcljjzuz2ve339dx82khm7q8getlegte"
          ],
        "validatorsOnly": true
    },
    "id": 1
}
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "staked": "6500000000000",
    "stakeds": {
      "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z": "6500000000000"
    },
    "stakedOutputs": [
      "0x000021e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff00000007000005e96630e800000000000000000000000001000000011f1c933f38da6ba0ba46f8c1b0a7040a9a991a80dd338ed1"
    ],
    "encoding": "hex"
  },
  "id": 1
}
```

### `platform.getStakingAssetID`

Retrieve an assetID for a Subnet’s staking asset.

**Signature:**

```
platform.getStakingAssetID({
    subnetID: string // optional
}) -> {
    assetID: string
}
```

- `subnetID` is the Subnet whose assetID is requested.
- `assetID` is the assetID for a Subnet’s staking asset.

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getStakingAssetID",
    "params": {
        "subnetID": "11111111111111111111111111111111LpoYY"
    },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "assetID": "2fombhL7aGPwj3KH4bfrmJwW6PVnMobf9Y2fn9GwxiAAJyFDbe"
  },
  "id": 1
}
```

<Callout title="Note">

The AssetID for AVAX differs depending on the network you are on.

Mainnet: FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z

Testnet: U8iRqJoiJm8xZHAacmvYyZVwqQx6uDNtQeP3CQ6fcgQk3JqnK

</Callout>

### `platform.getSubnet`

Get owners and info about the Subnet or L1.

**Signature:**

```
platform.getSubnet({
    subnetID: string
}) ->
{
    isPermissioned: bool,
    controlKeys: []string,
    threshold: string,
    locktime: string,
    subnetTransformationTxID: string,
    conversionID: string,
    managerChainID: string,
    managerAddress: string
}
```

- `subnetID` is the ID of the Subnet to get information about. If omitted, fails.
- `threshold` signatures from addresses in `controlKeys` are needed to make changes to
  a permissioned subnet. If the Subnet is not a PoA Subnet, then `threshold` will be `0` and `controlKeys`
  will be empty.
- changes can not be made into the subnet until `locktime` is in the past.
- `subnetTransformationTxID` is the ID of the transaction that changed the subnet into an elastic one, if it exists.
- `conversionID` is the ID of the conversion from a permissioned Subnet into an L1, if it exists.
- `managerChainID` is the ChainID that has the ability to modify this L1s validator set, if it exists.
- `managerAddress` is the address that has the ability to modify this L1s validator set, if it exists.

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getSubnet",
    "params": {"subnetID":"Vz2ArUpigHt7fyE79uF3gAXvTPLJi2LGgZoMpgNPHowUZJxBb"},
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "isPermissioned": true,
    "controlKeys": [
      "P-fuji1ztvstx6naeg6aarfd047fzppdt8v4gsah88e0c",
      "P-fuji193kvt4grqewv6ce2x59wnhydr88xwdgfcedyr3"
    ],
    "threshold": "1",
    "locktime": "0",
    "subnetTransformationTxID": "11111111111111111111111111111111LpoYY",
    "conversionID": "11111111111111111111111111111111LpoYY",
    "managerChainID": "11111111111111111111111111111111LpoYY",
    "managerAddress": null
  },
  "id": 1
}
```

### `platform.getSubnets`

<Callout title="Caution" type="warn">

Deprecated as of [**v1.9.12**](https://github.com/ava-labs/avalanchego/releases/tag/v1.9.12).

</Callout>

Get info about the Subnets.

**Signature:**

```
platform.getSubnets({
    ids: []string
}) ->
{
    subnets: []{
        id: string,
        controlKeys: []string,
        threshold: string
    }
}
```

- `ids` are the IDs of the Subnets to get information about. If omitted, gets information about all
  Subnets.
- `id` is the Subnet’s ID.
- `threshold` signatures from addresses in `controlKeys` are needed to add a validator to the
  Subnet. If the Subnet is not a PoA Subnet, then `threshold` will be `0` and `controlKeys` will be
  empty.

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getSubnets",
    "params": {"ids":["hW8Ma7dLMA7o4xmJf3AXBbo17bXzE7xnThUd3ypM4VAWo1sNJ"]},
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "subnets": [
      {
        "id": "hW8Ma7dLMA7o4xmJf3AXBbo17bXzE7xnThUd3ypM4VAWo1sNJ",
        "controlKeys": [
          "KNjXsaA1sZsaKCD1cd85YXauDuxshTes2",
          "Aiz4eEt5xv9t4NCnAWaQJFNz5ABqLtJkR"
        ],
        "threshold": "2"
      }
    ]
  },
  "id": 1
}
```

### `platform.getTimestamp`

Get the current P-Chain timestamp.

**Signature:**

```
platform.getTimestamp() -> {time: string}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getTimestamp",
    "params": {},
    "id": 1
}
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "timestamp": "2021-09-07T00:00:00-04:00"
  },
  "id": 1
}
```

### `platform.getTotalStake`

Get the total amount of tokens staked on the requested Subnet.

**Signature:**

```
platform.getTotalStake({
    subnetID: string
}) -> {
    stake: int
    weight: int
}
```

#### Primary Network Example

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getTotalStake",
    "params": {
      "subnetID": "11111111111111111111111111111111LpoYY"
    },
    "id": 1
}
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "stake": "279825917679866811",
    "weight": "279825917679866811"
  },
  "id": 1
}
```

#### Subnet Example

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getTotalStake",
    "params": {
        "subnetID": "2bRCr6B4MiEfSjidDwxDpdCyviwnfUVqB2HGwhm947w9YYqb7r",
    },
    "id": 1
}
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "weight": "100000"
  },
  "id": 1
}
```

### `platform.getTx`

Gets a transaction by its ID.

Optional `encoding` parameter to specify the format for the returned transaction. Can be either
`hex` or `json`. Defaults to `hex`.

**Signature:**

```
platform.getTx({
    txID: string,
    encoding: string // optional
}) -> {
    tx: string,
    encoding: string,
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getTx",
    "params": {
        "txID":"28KVjSw5h3XKGuNpJXWY74EdnGq4TUWvCgEtJPymgQTvudiugb",
        "encoding": "json"
    },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "tx": {
      "unsignedTx": {
        "networkID": 1,
        "blockchainID": "11111111111111111111111111111111LpoYY",
        "outputs": [],
        "inputs": [
          {
            "txID": "NXNJHKeaJyjjWVSq341t6LGQP5UNz796o1crpHPByv1TKp9ZP",
            "outputIndex": 0,
            "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z",
            "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ",
            "input": {
              "amount": 20824279595,
              "signatureIndices": [0]
            }
          },
          {
            "txID": "2ahK5SzD8iqi5KBqpKfxrnWtrEoVwQCqJsMoB9kvChCaHgAQC9",
            "outputIndex": 1,
            "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z",
            "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ",
            "input": {
              "amount": 28119890783,
              "signatureIndices": [0]
            }
          }
        ],
        "memo": "0x",
        "validator": {
          "nodeID": "NodeID-VT3YhgFaWEzy4Ap937qMeNEDscCammzG",
          "start": 1682945406,
          "end": 1684155006,
          "weight": 48944170378
        },
        "stake": [
          {
            "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z",
            "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ",
            "output": {
              "addresses": ["P-avax1tnuesf6cqwnjw7fxjyk7lhch0vhf0v95wj5jvy"],
              "amount": 48944170378,
              "locktime": 0,
              "threshold": 1
            }
          }
        ],
        "rewardsOwner": {
          "addresses": ["P-avax19zfygxaf59stehzedhxjesads0p5jdvfeedal0"],
          "locktime": 0,
          "threshold": 1
        }
      },
      "credentials": [
        {
          "signatures": [
            "0x6954e90b98437646fde0c1d54c12190fc23ae5e319c4d95dda56b53b4a23e43825251289cdc3728f1f1e0d48eac20e5c8f097baa9b49ea8a3cb6a41bb272d16601"
          ]
        },
        {
          "signatures": [
            "0x6954e90b98437646fde0c1d54c12190fc23ae5e319c4d95dda56b53b4a23e43825251289cdc3728f1f1e0d48eac20e5c8f097baa9b49ea8a3cb6a41bb272d16601"
          ]
        }
      ],
      "id": "28KVjSw5h3XKGuNpJXWY74EdnGq4TUWvCgEtJPymgQTvudiugb"
    },
    "encoding": "json"
  },
  "id": 1
}
```

### `platform.getTxStatus`

Gets a transaction’s status by its ID. If the transaction was dropped, response will include a
`reason` field with more information why the transaction was dropped.

**Signature:**

```
platform.getTxStatus({
  txID: string
}) -> { status: string }
```

`status` is one of:

- `Committed`: The transaction is (or will be) accepted by every node
- `Processing`: The transaction is being voted on by this node
- `Dropped`: The transaction will never be accepted by any node in the network, check `reason` field
  for more information
- `Unknown`: The transaction hasn’t been seen by this node

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getTxStatus",
    "params": {
        "txID":"TAG9Ns1sa723mZy1GSoGqWipK6Mvpaj7CAswVJGM6MkVJDF9Q"
   },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "status": "Committed"
  },
  "id": 1
}
```

### `platform.getUTXOs`

Gets the UTXOs that reference a given set of addresses.

**Signature:**

```
platform.getUTXOs(
    {
        addresses: []string,
        limit: int, // optional
        startIndex: { // optional
            address: string,
            utxo: string
        },
        sourceChain: string, // optional
        encoding: string, // optional
    },
) ->
{
    numFetched: int,
    utxos: []string,
    endIndex: {
        address: string,
        utxo: string
    },
    encoding: string,
}
```

- `utxos` is a list of UTXOs such that each UTXO references at least one address in `addresses`.
- At most `limit` UTXOs are returned. If `limit` is omitted or greater than 1024, it is set to 1024.
- This method supports pagination. `endIndex` denotes the last UTXO returned. To get the next set of
  UTXOs, use the value of `endIndex` as `startIndex` in the next call.
- If `startIndex` is omitted, will fetch all UTXOs up to `limit`.
- When using pagination (that is when `startIndex` is provided), UTXOs are not guaranteed to be unique
  across multiple calls. That is, a UTXO may appear in the result of the first call, and then again
  in the second call.
- When using pagination, consistency is not guaranteed across multiple calls. That is, the UTXO set
  of the addresses may have changed between calls.
- `encoding` specifies the format for the returned UTXOs. Can only be `hex` when a value is
  provided.

#### **Example**

Suppose we want all UTXOs that reference at least one of
`P-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5` and `P-avax1d09qn852zcy03sfc9hay2llmn9hsgnw4tp3dv6`.

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"platform.getUTXOs",
    "params" :{
        "addresses":["P-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5", "P-avax1d09qn852zcy03sfc9hay2llmn9hsgnw4tp3dv6"],
        "limit":5,
        "encoding": "hex"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

This gives response:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "numFetched": "5",
    "utxos": [
      "0x0000a195046108a85e60f7a864bb567745a37f50c6af282103e47cc62f036cee404700000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216c1f01765",
      "0x0000ae8b1b94444eed8de9a81b1222f00f1b4133330add23d8ac288bffa98b85271100000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216473d042a",
      "0x0000731ce04b1feefa9f4291d869adc30a33463f315491e164d89be7d6d2d7890cfc00000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f21600dd3047",
      "0x0000b462030cc4734f24c0bc224cf0d16ee452ea6b67615517caffead123ab4fbf1500000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216c71b387e",
      "0x000054f6826c39bc957c0c6d44b70f961a994898999179cc32d21eb09c1908d7167b00000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f2166290e79d"
    ],
    "endIndex": {
      "address": "P-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5",
      "utxo": "kbUThAUfmBXUmRgTpgD6r3nLj7rJUGho6xyht5nouNNypH45j"
    },
    "encoding": "hex"
  },
  "id": 1
}
```

Since `numFetched` is the same as `limit`, we can tell that there may be more UTXOs that were not
fetched. We call the method again, this time with `startIndex`:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"platform.getUTXOs",
    "params" :{
        "addresses":["P-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5"],
        "limit":5,
        "startIndex": {
            "address": "P-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5",
            "utxo": "0x62fc816bb209857923770c286192ab1f9e3f11e4a7d4ba0943111c3bbfeb9e4a5ea72fae"
        },
        "encoding": "hex"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

This gives response:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "numFetched": "4",
    "utxos": [
      "0x000020e182dd51ee4dcd31909fddd75bb3438d9431f8e4efce86a88a684f5c7fa09300000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f21662861d59",
      "0x0000a71ba36c475c18eb65dc90f6e85c4fd4a462d51c5de3ac2cbddf47db4d99284e00000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f21665f6f83f",
      "0x0000925424f61cb13e0fbdecc66e1270de68de9667b85baa3fdc84741d048daa69fa00000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216afecf76a",
      "0x000082f30327514f819da6009fad92b5dba24d27db01e29ad7541aa8e6b6b554615c00000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216779c2d59"
    ],
    "endIndex": {
      "address": "P-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5",
      "utxo": "21jG2RfqyHUUgkTLe2tUp6ETGLriSDTW3th8JXFbPRNiSZ11jK"
    },
    "encoding": "hex"
  },
  "id": 1
}
```

Since `numFetched` is less than `limit`, we know that we are done fetching UTXOs and don’t need to
call this method again.

Suppose we want to fetch the UTXOs exported from the X Chain to the P Chain in order to build an
ImportTx. Then we need to call GetUTXOs with the `sourceChain` argument in order to retrieve the
atomic UTXOs:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"platform.getUTXOs",
    "params" :{
        "addresses":["P-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5"],
        "sourceChain": "X",
        "encoding": "hex"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

This gives response:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "numFetched": "1",
    "utxos": [
      "0x00001f989ffaf18a18a59bdfbf209342aa61c6a62a67e8639d02bb3c8ddab315c6fa0000000139c33a499ce4c33a3b09cdd2cfa01ae70dbf2d18b2d7d168524440e55d55008800000007000000746a528800000000000000000000000001000000013cb7d3842e8cee6a0ebd09f1fe884f6861e1b29cd704fe76"
    ],
    "endIndex": {
      "address": "P-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5",
      "utxo": "S5UKgWoVpoGFyxfisebmmRf8WqC7ZwcmYwS7XaDVZqoaFcCwK"
    },
    "encoding": "hex"
  },
  "id": 1
}
```

### `platform.getValidatorsAt`

Get the validators and their weights of a Subnet or the Primary Network at a given P-Chain height.

**Signature:**

```
platform.getValidatorsAt(
    {
        height: [int|string],
        subnetID: string, // optional
    }
)
```

- `height` is the P-Chain height to get the validator set at, or the string literal "proposed"
  to return the validator set at this node's ProposerVM height.
- `subnetID` is the Subnet ID to get the validator set of. If not given, gets validator set of the
  Primary Network.

**Example Call:**

```bash
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getValidatorsAt",
    "params": {
        "height":1
    },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "validators": {
      "NodeID-7Xhw2mDxuDS44j42TCB6U5579esbSt3Lg": 2000000000000000,
      "NodeID-GWPcbFJZFfZreETSoWjPimr846mXEKCtu": 2000000000000000,
      "NodeID-MFrZFVCXPv5iCn6M9K6XduxGTYp891xXZ": 2000000000000000,
      "NodeID-NFBbbJ4qCmNaCzeW7sxErhvWqvEQMnYcN": 2000000000000000,
      "NodeID-P7oB2McjBGgW2NXXWVYjV8JEDFoW9xDE5": 2000000000000000
    }
  },
  "id": 1
}
```

### `platform.getAllValidatorsAt`

Get the validators and their weights of all Subnets and the Primary Network at a given P-Chain height.

**Signature:**

```
platform.getAllValidatorsAt(
    {
        height: [int|string],
    }
)
```

```bash
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getAllValidatorsAt",
    "params": {
        "height":1
    },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
    "jsonrpc": "2.0",
    "result": {
        "validatorSets": {
            "11111111111111111111111111111111LpoYY": {
                "validators": [
                    {
                        "publicKey": "0x8048109c3da13de0700f9f3590c3270bfc42277417f6d0cc84282947e1a1f8b4980fd3e3fe223acf0f56a5838890814a",
                        "weight": "2000000000000000",
                        "nodeIDs": [
                            "NodeID-P7oB2McjBGgW2NXXWVYjV8JEDFoW9xDE5"
                        ]
                    },
                    {
                        "publicKey": "0xa058ff27a4c570664bfa28e34939368539a1340867951943d0f56fa8aac13bc09ff64f341acf8cc0cef74202c2d6f9c0",
                        "weight": "2000000000000000",
                        "nodeIDs": [
                            "NodeID-MFrZFVCXPv5iCn6M9K6XduxGTYp891xXZ"
                        ]
                    },
                    {
                        "publicKey": "0xa10b6955a85684a0f5c94b8381f04506f1bee60625927d372323f78b3d30196cc56c8618c77eaf429298e74673d832c3",
                        "weight": "2000000000000000",
                        "nodeIDs": [
                            "NodeID-NFBbbJ4qCmNaCzeW7sxErhvWqvEQMnYcN"
                        ]
                    },
                    {
                        "publicKey": "0xaccd61ceb90c61628aa0fa34acab27ecb08f6897e9ccad283578c278c52109f9e10e4f8bc31aa6d7905c4e1623de367e",
                        "weight": "2000000000000000",
                        "nodeIDs": [
                            "NodeID-GWPcbFJZFfZreETSoWjPimr846mXEKCtu"
                        ]
                    },
                    {
                        "publicKey": "0x900c9b119b5c82d781d4b49be78c3fc7ae65f2b435b7ed9e3a8b9a03e475edff86d8a64827fec8db23a6f236afbf127d",
                        "weight": "2000000000000000",
                        "nodeIDs": [
                            "NodeID-7Xhw2mDxuDS44j42TCB6U5579esbSt3Lg"
                        ]
                    }
                ],
                "totalWeight": "10000000000000000"
            }
        }
    },
    "id": 1
}
```

- `height` is the P-Chain height to get the validator set at, or the string literal "proposed"
  to return the validator set at this node's ProposerVM height.

**Example Call:**

### `platform.getValidatorFeeConfig`

Returns the validator fee configuration of the P-Chain.

**Signature:**

```
platform.getValidatorFeeConfig() -> {
  capacity: uint64,
  target: uint64,
  minPrice: uint64,
  excessConversionConstant: uint64
}
```

- `capacity` is the maximum number of L1 validators the chain is allowed to have at any given time
- `target` is the target number of L1 validators the chain should have to keep fees stable
- `minPrice` is the minimum price per L1 validator
- `excessConversionConstant` is used to convert excess L1 validators to a gas price

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getValidatorFeeConfig",
    "params": {},
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "capacity": 20000,
    "target": 10000,
    "targetPerSecond": 50000,
    "minPrice": 512,
    "excessConversionConstant": 1246488515
  },
  "id": 1
}
```

### `platform.getValidatorFeeState`

Returns the current validator fee state of the P-Chain.

**Signature:**

```
platform.getValidatorFeeState() -> {
  excess: uint64,
  price: uint64,
  timestamp: string
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.getValidatorFeeState",
    "params": {},
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "excess": 26956,
    "price": 512,
    "timestamp": "2024-12-16T17:19:07Z"
  },
  "id": 1
}
```

### `platform.issueTx`

Issue a transaction to the Platform Chain.

**Signature:**

```
platform.issueTx({
    tx: string,
    encoding: string, // optional
}) -> { txID: string }
```

- `tx` is the byte representation of a transaction.
- `encoding` specifies the encoding format for the transaction bytes. Can only be `hex` when a value
  is provided.
- `txID` is the transaction’s ID.

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.issueTx",
    "params": {
        "tx":"0x00000009de31b4d8b22991d51aa6aa1fc733f23a851a8c9400000000000186a0000000005f041280000000005f9ca900000030390000000000000001fceda8f90fcb5d30614b99d79fc4baa29307762668f16eb0259a57c2d3b78c875c86ec2045792d4df2d926c40f829196e0bb97ee697af71f5b0a966dabff749634c8b729855e937715b0e44303fd1014daedc752006011b730",
        "encoding": "hex"
    },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "txID": "G3BuH6ytQ2averrLxJJugjWZHTRubzCrUZEXoheG5JMqL5ccY"
  },
  "id": 1
}
```

### `platform.sampleValidators`

Sample validators from the specified Subnet.

**Signature:**

```
platform.sampleValidators(
    {
        size: int,
        subnetID: string, // optional
    }
) ->
{
    validators: []string
}
```

- `size` is the number of validators to sample.
- `subnetID` is the Subnet to sampled from. If omitted, defaults to the Primary Network.
- Each element of `validators` is the ID of a validator.

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"platform.sampleValidators",
    "params" :{
        "size":2
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "validators": [
      "NodeID-MFrZFVCXPv5iCn6M9K6XduxGTYp891xXZ",
      "NodeID-NFBbbJ4qCmNaCzeW7sxErhvWqvEQMnYcN"
    ]
  }
}
```

### `platform.validatedBy`

Get the Subnet that validates a given blockchain.

**Signature:**

```
platform.validatedBy(
    {
        blockchainID: string
    }
) -> { subnetID: string }
```

- `blockchainID` is the blockchain’s ID.
- `subnetID` is the ID of the Subnet that validates the blockchain.

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.validatedBy",
    "params": {
        "blockchainID": "KDYHHKjM4yTJTT8H8qPs5KXzE6gQH5TZrmP1qVr1P6qECj3XN"
    },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "subnetID": "2bRCr6B4MiEfSjidDwxDpdCyviwnfUVqB2HGwhm947w9YYqb7r"
  },
  "id": 1
}
```

### `platform.validates`

Get the IDs of the blockchains a Subnet validates.

**Signature:**

```
platform.validates(
    {
        subnetID: string
    }
) -> { blockchainIDs: []string }
```

- `subnetID` is the Subnet’s ID.
- Each element of `blockchainIDs` is the ID of a blockchain the Subnet validates.

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "platform.validates",
    "params": {
        "subnetID":"2bRCr6B4MiEfSjidDwxDpdCyviwnfUVqB2HGwhm947w9YYqb7r"
    },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/P
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "blockchainIDs": [
      "KDYHHKjM4yTJTT8H8qPs5KXzE6gQH5TZrmP1qVr1P6qECj3XN",
      "2TtHFqEAAJ6b33dromYMqfgavGPF3iCpdG3hwNMiart2aB5QHi"
    ]
  },
  "id": 1
}
```

# Transaction Format (/docs/rpcs/p-chain/txn-format)

---
title: Transaction Format
---

This file is meant to be the single source of truth for how we serialize
transactions in Avalanche's Platform Virtual Machine, aka the `Platform Chain`
or `P-Chain`. This document uses the [primitive serialization](/docs/api-reference/standards/serialization-primitives) format for packing and
[secp256k1](/docs/api-reference/standards/cryptographic-primitives#secp256k1-addresses) for cryptographic
user identification.

## Codec ID

Some data is prepended with a codec ID (unt16) that denotes how the data should
be deserialized. Right now, the only valid codec ID is 0 (`0x00 0x00`).

## Proof of Possession

A BLS public key and a proof of possession of the key.

### What Proof of Possession Contains

- **PublicKey** is the 48 byte representation of the public key.
- **Signature** is the 96 byte signature by the private key over its public key.

### Proof of Possession Specification

```text
+------------+----------+-------------------------+
| public_key : [48]byte |                48 bytes |
+------------+----------+-------------------------+
| signature  : [96]byte |                96 bytes |
+------------+----------+-------------------------+
                        |               144 bytes |
                        +-------------------------+
```

### Proof of Possession Specification

```text
message ProofOfPossession {
    bytes public_key = 1; // 48 bytes
    bytes signature = 2;  // 96 bytes
}
```

### Proof of Possession Example

```text
    // Public Key:
    0x85, 0x02, 0x5b, 0xca, 0x6a, 0x30, 0x2d, 0xc6,
    0x13, 0x38, 0xff, 0x49, 0xc8, 0xba, 0xa5, 0x72,
    0xde, 0xd3, 0xe8, 0x6f, 0x37, 0x59, 0x30, 0x4c,
    0x7f, 0x61, 0x8a, 0x2a, 0x25, 0x93, 0xc1, 0x87,
    0xe0, 0x80, 0xa3, 0xcf, 0xde, 0xc9, 0x50, 0x40,
    0x30, 0x9a, 0xd1, 0xf1, 0x58, 0x95, 0x30, 0x67,
    // Signature:
    0x8b, 0x1d, 0x61, 0x33, 0xd1, 0x7e, 0x34, 0x83,
    0x22, 0x0a, 0xd9, 0x60, 0xb6, 0xfd, 0xe1, 0x1e,
    0x4e, 0x12, 0x14, 0xa8, 0xce, 0x21, 0xef, 0x61,
    0x62, 0x27, 0xe5, 0xd5, 0xee, 0xf0, 0x70, 0xd7,
    0x50, 0x0e, 0x6f, 0x7d, 0x44, 0x52, 0xc5, 0xa7,
    0x60, 0x62, 0x0c, 0xc0, 0x67, 0x95, 0xcb, 0xe2,
    0x18, 0xe0, 0x72, 0xeb, 0xa7, 0x6d, 0x94, 0x78,
    0x8d, 0x9d, 0x01, 0x17, 0x6c, 0xe4, 0xec, 0xad,
    0xfb, 0x96, 0xb4, 0x7f, 0x94, 0x22, 0x81, 0x89,
    0x4d, 0xdf, 0xad, 0xd1, 0xc1, 0x74, 0x3f, 0x7f,
    0x54, 0x9f, 0x1d, 0x07, 0xd5, 0x9d, 0x55, 0x65,
    0x59, 0x27, 0xf7, 0x2b, 0xc6, 0xbf, 0x7c, 0x12
```

## Transferable Output

Transferable outputs wrap an output with an asset ID.

### What Transferable Output Contains

A transferable output contains an `AssetID` and an `Output`.

- **`AssetID`** is a 32-byte array that defines which asset this output
  references. The only valid `AssetID` is the AVAX `AssetID`.
- **`Output`** is an output, as defined below. For example, this can be a SECP256K1 transfer output.

### Gantt Transferable Output Specification

```text
+----------+----------+-------------------------+
| asset_id : [32]byte |                32 bytes |
+----------+----------+-------------------------+
| output   : Output   |      size(output) bytes |
+----------+----------+-------------------------+
                      | 32 + size(output) bytes |
                      +-------------------------+
```

### Proto Transferable Output Specification

```text
message TransferableOutput {
    bytes asset_id = 1; // 32 bytes
    Output output = 2;  // size(output)
}
```

### Transferable Output Example

Let's make a transferable output:

- `AssetID: 0x6870b7d66ac32540311379e5b5dbad28ec7eb8ddbfc8f4d67299ebb48475907a`
- `Output: "Example SECP256K1 Transfer Output from below"`

```text
[
    AssetID <- 0x6870b7d66ac32540311379e5b5dbad28ec7eb8ddbfc8f4d67299ebb48475907a,
    Output  <- 0x0000000700000000ee5be5c000000000000000000000000100000001da2bee01be82ecc00c34f361eda8eb30fb5a715c,
]
=
[
    // assetID:
    0x68, 0x70, 0xb7, 0xd6, 0x6a, 0xc3, 0x25, 0x40,
    0x31, 0x13, 0x79, 0xe5, 0xb5, 0xdb, 0xad, 0x28,
    0xec, 0x7e, 0xb8, 0xdd, 0xbf, 0xc8, 0xf4, 0xd6,
    0x72, 0x99, 0xeb, 0xb4, 0x84, 0x75, 0x90, 0x7a,
    // output:
    0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00,
    0xee, 0x5b, 0xe5, 0xc0, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x01, 0xda, 0x2b, 0xee, 0x01,
    0xbe, 0x82, 0xec, 0xc0, 0x0c, 0x34, 0xf3, 0x61,
    0xed, 0xa8, 0xeb, 0x30, 0xfb, 0x5a, 0x71, 0x5c,
]
```

## Transferable Input

Transferable inputs describe a specific UTXO with a provided transfer input.

### What Transferable Input Contains

A transferable input contains a `TxID`, `UTXOIndex` `AssetID` and an `Input`.

- **`TxID`** is a 32-byte array that defines which transaction this input is consuming an output from.
- **`UTXOIndex`** is an int that defines which utxo this input is consuming the specified transaction.
- **`AssetID`** is a 32-byte array that defines which asset this input
  references. The only valid `AssetID` is the AVAX `AssetID`.
- **`Input`** is a transferable input object.

### Gantt Transferable Input Specification

```text
+------------+----------+------------------------+
| tx_id      : [32]byte |               32 bytes |
+------------+----------+------------------------+
| utxo_index : int      |               04 bytes |
+------------+----------+------------------------+
| asset_id   : [32]byte |               32 bytes |
+------------+----------+------------------------+
| input      : Input    |      size(input) bytes |
+------------+----------+------------------------+
                        | 68 + size(input) bytes |
                        +------------------------+
```

### Proto Transferable Input Specification

```text
message TransferableInput {
    bytes tx_id = 1;       // 32 bytes
    uint32 utxo_index = 2; // 04 bytes
    bytes asset_id = 3;    // 32 bytes
    Input input = 4;       // size(input)
}
```

### Transferable Input Example

Let's make a transferable input:

- **`TxID`**: `0x0dfafbdf5c81f635c9257824ff21c8e3e6f7b632ac306e11446ee540d34711a15`
- **`UTXOIndex`**: `0`
- **`AssetID`**: `0x6870b7d66ac32540311379e5b5dbad28ec7eb8ddbfc8f4d67299ebb48475907a`
- **`Input`**: `"Example SECP256K1 Transfer Input from below"`

```text
[
    TxID      <- 0x0dfafbdf5c81f635c9257824ff21c8e3e6f7b632ac306e11446ee540d34711a15
    UTXOIndex <- 0x00000001
    AssetID   <- 0x6870b7d66ac32540311379e5b5dbad28ec7eb8ddbfc8f4d67299ebb48475907a
    Input     <- 0x0000000500000000ee6b28000000000100000000
]
=
[
    // txID:
    0xdf, 0xaf, 0xbd, 0xf5, 0xc8, 0x1f, 0x63, 0x5c,
    0x92, 0x57, 0x82, 0x4f, 0xf2, 0x1c, 0x8e, 0x3e,
    0x6f, 0x7b, 0x63, 0x2a, 0xc3, 0x06, 0xe1, 0x14,
    0x46, 0xee, 0x54, 0x0d, 0x34, 0x71, 0x1a, 0x15,
    // utxoIndex:
    0x00, 0x00, 0x00, 0x01,
    // assetID:
    0x68, 0x70, 0xb7, 0xd6, 0x6a, 0xc3, 0x25, 0x40,
    0x31, 0x13, 0x79, 0xe5, 0xb5, 0xdb, 0xad, 0x28,
    0xec, 0x7e, 0xb8, 0xdd, 0xbf, 0xc8, 0xf4, 0xd6,
    0x72, 0x99, 0xeb, 0xb4, 0x84, 0x75, 0x90, 0x7a,
    // input:
    0x00, 0x00, 0x00, 0x05, 0x00, 0x00, 0x00, 0x00,
    0xee, 0x6b, 0x28, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x00
]
```

## Outputs

Outputs have two possible type: `SECP256K1TransferOutput`, `SECP256K1OutputOwners`.

## SECP256K1 Transfer Output

A [secp256k1](/docs/api-reference/standards/cryptographic-primitives#secp256k1-addresses) transfer output
allows for sending a quantity of an asset to a collection of addresses after a
specified Unix time. The only valid asset is AVAX.

### What SECP256K1 Transfer Output Contains

A secp256k1 transfer output contains a `TypeID`, `Amount`, `Locktime`, `Threshold`, and `Addresses`.

- **`TypeID`** is the ID for this output type. It is `0x00000007`.
- **`Amount`** is a long that specifies the quantity of the asset that this output owns. Must be positive.
- **`Locktime`** is a long that contains the Unix timestamp that this output can
  be spent after. The Unix timestamp is specific to the second.
- **`Threshold`** is an int that names the number of unique signatures required
  to spend the output. Must be less than or equal to the length of
  **`Addresses`**. If **`Addresses`** is empty, must be 0.
- **`Addresses`** is a list of unique addresses that correspond to the private
  keys that can be used to spend this output. Addresses must be sorted
  lexicographically.

### Gantt SECP256K1 Transfer Output Specification

```text
+-----------+------------+--------------------------------+
| type_id   : int        |                        4 bytes |
+-----------+------------+--------------------------------+
| amount    : long       |                        8 bytes |
+-----------+------------+--------------------------------+
| locktime  : long       |                        8 bytes |
+-----------+------------+--------------------------------+
| threshold : int        |                        4 bytes |
+-----------+------------+--------------------------------+
| addresses : [][20]byte |  4 + 20 * len(addresses) bytes |
+-----------+------------+--------------------------------+
                         | 28 + 20 * len(addresses) bytes |
                         +--------------------------------+
```

### Proto SECP256K1 Transfer Output Specification

```text
message SECP256K1TransferOutput {
    uint32 type_id = 1;           // 04 bytes
    uint64 amount = 2;            // 08 bytes
    uint64 locktime = 3;          // 08 bytes
    uint32 threshold = 4;         // 04 bytes
    repeated bytes addresses = 5; // 04 bytes + 20 bytes * len(addresses)
}
```

### SECP256K1 Transfer Output Example

Let's make a secp256k1 transfer output with:

- **`TypeID`**: 7
- **`Amount`**: 3999000000
- **`Locktime`**: 0
- **`Threshold`**: 1
- **`Addresses`**:
  - 0xda2bee01be82ecc00c34f361eda8eb30fb5a715c

```text
[
    TypeID    <- 0x00000007
    Amount    <- 0x00000000ee5be5c0
    Locktime  <- 0x0000000000000000
    Threshold <- 0x00000001
    Addresses <- [
        0xda2bee01be82ecc00c34f361eda8eb30fb5a715c,
    ]
]
=
[
    // type_id:
    0x00, 0x00, 0x00, 0x07,
    // amount:
    0x00, 0x00, 0x00, 0x00, 0xee, 0x5b, 0xe5, 0xc0,
    // locktime:
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    // threshold:
    0x00, 0x00, 0x00, 0x01,
    // number of addresses:
    0x00, 0x00, 0x00, 0x01,
    // addrs[0]:
    0xda, 0x2b, 0xee, 0x01, 0xbe, 0x82, 0xec, 0xc0,
    0x0c, 0x34, 0xf3, 0x61, 0xed, 0xa8, 0xeb, 0x30,
    0xfb, 0x5a, 0x71, 0x5c,
]
```

## SECP256K1 Output Owners Output

A [secp256k1](/docs/api-reference/standards/cryptographic-primitives#secp256k1-addresses) output owners
output will receive the staking rewards when the lock up period ends.

### What SECP256K1 Output Owners Output Contains

A secp256k1 output owners output contains a `TypeID`, `Locktime`, `Threshold`, and `Addresses`.

- **`TypeID`** is the ID for this output type. It is `0x0000000b`.
- **`Locktime`** is a long that contains the Unix timestamp that this output can
  be spent after. The Unix timestamp is specific to the second.
- **`Threshold`** is an int that names the number of unique signatures required
  to spend the output. Must be less than or equal to the length of
  **`Addresses`**. If **`Addresses`** is empty, must be 0.
- **`Addresses`** is a list of unique addresses that correspond to the private
  keys that can be used to spend this output. Addresses must be sorted
  lexicographically.

### Gantt SECP256K1 Output Owners Output Specification

```text
+-----------+------------+--------------------------------+
| type_id   : int        |                        4 bytes |
+-----------+------------+--------------------------------+
| locktime  : long       |                        8 bytes |
+-----------+------------+--------------------------------+
| threshold : int        |                        4 bytes |
+-----------+------------+--------------------------------+
| addresses : [][20]byte |  4 + 20 * len(addresses) bytes |
+-----------+------------+--------------------------------+
                         | 20 + 20 * len(addresses) bytes |
                         +--------------------------------+
```

### Proto SECP256K1 Output Owners Output Specification

```text
message SECP256K1OutputOwnersOutput {
    uint32 type_id = 1;           // 04 bytes
    uint64 locktime = 2;          // 08 bytes
    uint32 threshold = 3;         // 04 bytes
    repeated bytes addresses = 4; // 04 bytes + 20 bytes * len(addresses)
}
```

### SECP256K1 Output Owners Output Example

Let's make a secp256k1 output owners output with:

- **`TypeID`**: 11
- **`Locktime`**: 0
- **`Threshold`**: 1
- **`Addresses`**:
  - 0xda2bee01be82ecc00c34f361eda8eb30fb5a715c

```text
[
    TypeID    <- 0x0000000b
    Locktime  <- 0x0000000000000000
    Threshold <- 0x00000001
    Addresses <- [
        0xda2bee01be82ecc00c34f361eda8eb30fb5a715c,
    ]
]
=
[
    // type_id:
    0x00, 0x00, 0x00, 0x0b,
    // locktime:
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    // threshold:
    0x00, 0x00, 0x00, 0x01,
    // number of addresses:
    0x00, 0x00, 0x00, 0x01,
    // addrs[0]:
    0xda, 0x2b, 0xee, 0x01, 0xbe, 0x82, 0xec, 0xc0,
    0x0c, 0x34, 0xf3, 0x61, 0xed, 0xa8, 0xeb, 0x30,
    0xfb, 0x5a, 0x71, 0x5c,
]
```

## Inputs

Inputs have one possible type: `SECP256K1TransferInput`.

## SECP256K1 Transfer Input

A [secp256k1](/docs/api-reference/standards/cryptographic-primitives#secp256k1-addresses) transfer input
allows for spending an unspent secp256k1 transfer output.

### What SECP256K1 Transfer Input Contains

A secp256k1 transfer input contains an `Amount` and `AddressIndices`.

- **`TypeID`** is the ID for this output type. It is `0x00000005`.
- **`Amount`** is a long that specifies the quantity that this input should be
  consuming from the UTXO. Must be positive. Must be equal to the amount
  specified in the UTXO.
- **`AddressIndices`** is a list of unique ints that define the private keys are
  being used to spend the UTXO. Each UTXO has an array of addresses that can
  spend the UTXO. Each int represents the index in this address array that will
  sign this transaction. The array must be sorted low to high.

### Gantt SECP256K1 Transfer Input Specification

```text
+-------------------------+-------------------------------------+
| type_id         : int   |                             4 bytes |
+-----------------+-------+-------------------------------------+
| amount          : long  |                             8 bytes |
+-----------------+-------+-------------------------------------+
| address_indices : []int |  4 + 4 * len(address_indices) bytes |
+-----------------+-------+-------------------------------------+
                          | 16 + 4 * len(address_indices) bytes |
                          +-------------------------------------+
```

**Proto SECP256K1 Transfer Input Specification**

```text
message SECP256K1TransferInput {
    uint32 type_id = 1;                  // 04 bytes
    uint64 amount = 2;                   // 08 bytes
    repeated uint32 address_indices = 3; // 04 bytes + 4 bytes * len(address_indices)
}
```

### SECP256K1 Transfer Input Example

Let's make a payment input with:

- **`TypeID`**: 5
- **`Amount`**: 4000000000
- **`AddressIndices`**: \[0\]

```text
[
    TypeID         <- 0x00000005
    Amount         <- 0x00000000ee6b2800,
    AddressIndices <- [0x00000000]
]
=
[
    // type_id:
    0x00, 0x00, 0x00, 0x05,
    // amount:
    0x00, 0x00, 0x00, 0x00, 0xee, 0x6b, 0x28, 0x00,
    // length:
    0x00, 0x00, 0x00, 0x01,
    // address_indices[0]
    0x00, 0x00, 0x00, 0x00
]
```

## Unsigned Transactions

Unsigned transactions contain the full content of a transaction with only the
signatures missing. Unsigned transactions have six possible types:
`AddValidatorTx`, `AddSubnetValidatorTx`, `AddDelegatorTx`, `CreateSubnetTx`,
`ImportTx`, and `ExportTx`. They embed `BaseTx`, which contains common fields
and operations.

## Unsigned BaseTx

### What Base TX Contains

A base TX contains a `TypeID`, `NetworkID`, `BlockchainID`, `Outputs`, `Inputs`, and `Memo`.

- **`TypeID`** is the ID for this type. It is `0x00000000`.
- **`NetworkID`** is an int that defines which network this transaction is meant
  to be issued to. This value is meant to support transaction routing and is not
  designed for replay attack prevention.
- **`BlockchainID`** is a 32-byte array that defines which blockchain this
  transaction was issued to. This is used for replay attack prevention for
  transactions that could potentially be valid across network or blockchain.
- **`Outputs`** is an array of transferable output objects. Outputs must be
  sorted lexicographically by their serialized representation. The total
  quantity of the assets created in these outputs must be less than or equal to
  the total quantity of each asset consumed in the inputs minus the transaction
  fee.
- **`Inputs`** is an array of transferable input objects. Inputs must be sorted
  and unique. Inputs are sorted first lexicographically by their **`TxID`** and
  then by the **`UTXOIndex`** from low to high. If there are inputs that have
  the same **`TxID`** and **`UTXOIndex`**, then the transaction is invalid as
  this would result in a double spend.
- **`Memo`** Memo field contains arbitrary bytes, up to 256 bytes.

### Gantt Base TX Specification

```text
+---------------+----------------------+-----------------------------------------+
| type_id       : int                  |                                 4 bytes |
+---------------+----------------------+-----------------------------------------+
| network_id    : int                  |                                 4 bytes |
+---------------+----------------------+-----------------------------------------+
| blockchain_id : [32]byte             |                                32 bytes |
+---------------+----------------------+-----------------------------------------+
| outputs       : []TransferableOutput |                 4 + size(outputs) bytes |
+---------------+----------------------+-----------------------------------------+
| inputs        : []TransferableInput  |                  4 + size(inputs) bytes |
+---------------+----------------------+-----------------------------------------+
| memo          : [256]byte            |                    4 + size(memo) bytes |
+---------------+----------------------+-----------------------------------------+
                          | 52 + size(outputs) + size(inputs) + size(memo) bytes |
                          +------------------------------------------------------+
```

### Proto Base TX Specification

```text
message BaseTx {
    uint32 type_id = 1;          // 04 bytes
    uint32 network_id = 2;       // 04 bytes
    bytes blockchain_id = 3;     // 32 bytes
    repeated Output outputs = 4; // 04 bytes + size(outs)
    repeated Input inputs = 5;   // 04 bytes + size(ins)
    bytes memo = 6;              // 04 bytes + size(memo)
}
```

### Base TX Example

Let's make a base TX that uses the inputs and outputs from the previous examples:

- **`TypeID`**: `0`
- **`NetworkID`**: `12345`
- **`BlockchainID`**: `0x000000000000000000000000000000000000000000000000000000000000000`
- **`Outputs`**:
  - `"Example Transferable Output as defined above"`
- **`Inputs`**:
  - `"Example Transferable Input as defined above"`

```text
[
    TypeID       <- 0x00000000
    NetworkID    <- 0x00003039
    BlockchainID <- 0x000000000000000000000000000000000000000000000000000000000000000
    Outputs      <- [
        0x6870b7d66ac32540311379e5b5dbad28ec7eb8ddbfc8f4d67299ebb48475907a0000000700000000ee5be5c000000000000000000000000100000001da2bee01be82ecc00c34f361eda8eb30fb5a715c
    ]
    Inputs       <- [
        0xdfafbdf5c81f635c9257824ff21c8e3e6f7b632ac306e11446ee540d34711a15000000016870b7d66ac32540311379e5b5dbad28ec7eb8ddbfc8f4d67299ebb48475907a0000000500000000ee6b28000000000100000000
    ]
]
=
[
    // type_id:
    0x00, 0x00, 0x00, 0x00,
    // networkID:
    0x00, 0x00, 0x30, 0x39,
    // blockchainID:
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    // number of outputs:
    0x00, 0x00, 0x00, 0x01,
    // transferable output:
    0x68, 0x70, 0xb7, 0xd6, 0x6a, 0xc3, 0x25, 0x40,
    0x31, 0x13, 0x79, 0xe5, 0xb5, 0xdb, 0xad, 0x28,
    0xec, 0x7e, 0xb8, 0xdd, 0xbf, 0xc8, 0xf4, 0xd6,
    0x72, 0x99, 0xeb, 0xb4, 0x84, 0x75, 0x90, 0x7a,
    0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00,
    0xee, 0x5b, 0xe5, 0xc0, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x01, 0xda, 0x2b, 0xee, 0x01,
    0xbe, 0x82, 0xec, 0xc0, 0x0c, 0x34, 0xf3, 0x61,
    0xed, 0xa8, 0xeb, 0x30, 0xfb, 0x5a, 0x71, 0x5c,
    // number of inputs:
    0x00, 0x00, 0x00, 0x01,
    // transferable input:
    0xdf, 0xaf, 0xbd, 0xf5, 0xc8, 0x1f, 0x63, 0x5c,
    0x92, 0x57, 0x82, 0x4f, 0xf2, 0x1c, 0x8e, 0x3e,
    0x6f, 0x7b, 0x63, 0x2a, 0xc3, 0x06, 0xe1, 0x14,
    0x46, 0xee, 0x54, 0x0d, 0x34, 0x71, 0x1a, 0x15,
    0x00, 0x00, 0x00, 0x01,
    0x68, 0x70, 0xb7, 0xd6, 0x6a, 0xc3, 0x25, 0x40,
    0x31, 0x13, 0x79, 0xe5, 0xb5, 0xdb, 0xad, 0x28,
    0xec, 0x7e, 0xb8, 0xdd, 0xbf, 0xc8, 0xf4, 0xd6,
    0x72, 0x99, 0xeb, 0xb4, 0x84, 0x75, 0x90, 0x7a,
    0x00, 0x00, 0x00, 0x05, 0x00, 0x00, 0x00, 0x00,
    0xee, 0x6b, 0x28, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x00,
    // Memo length:
    0x00, 0x00, 0x00, 0x00,
]
```

## Unsigned Add Validator TX

### What Unsigned Add Validator TX Contains

An unsigned add validator TX contains a `BaseTx`, `Validator`, `Stake`,
`RewardsOwner`, and `Shares`. The `TypeID` for this type is `0x0000000c`.

- **`BaseTx`**
- **`Validator`** Validator has a `NodeID`, `StartTime`, `EndTime`, and `Weight`
  - **`NodeID`** is 20 bytes which is the node ID of the validator.
  - **`StartTime`** is a long which is the Unix time when the validator starts validating.
  - **`EndTime`** is a long which is the Unix time when the validator stops validating.
  - **`Weight`** is a long which is the amount the validator stakes
- **`Stake`** Stake has `LockedOuts`
  - **`LockedOuts`** An array of Transferable Outputs that are locked for the
    duration of the staking period. At the end of the staking period, these
    outputs are refunded to their respective addresses.
- **`RewardsOwner`** A `SECP256K1OutputOwners`
- **`Shares`** 10,000 times percentage of reward taken from delegators

### Gantt Unsigned Add Validator TX Specification

```text
+---------------+-----------------------+-----------------------------------------+
| base_tx       : BaseTx                |                     size(base_tx) bytes |
+---------------+-----------------------+-----------------------------------------+
| validator     : Validator             |                                44 bytes |
+---------------+-----------------------+-----------------------------------------+
| stake         : Stake                 |                  size(LockedOuts) bytes |
+---------------+-----------------------+-----------------------------------------+
| rewards_owner : SECP256K1OutputOwners |               size(rewards_owner) bytes |
+---------------+-----------------------+-----------------------------------------+
| shares        : Shares                |                                 4 bytes |
+---------------+-----------------------+-----------------------------------------+
                  | 48 + size(stake) + size(rewards_owner) + size(base_tx) bytes |
                  +--------------------------------------------------------------+
```

### Proto Unsigned Add Validator TX Specification

```text
message AddValidatorTx {
    BaseTx base_tx = 1;                      // size(base_tx)
    Validator validator = 2;                 // 44 bytes
    Stake stake = 3;                         // size(LockedOuts)
    SECP256K1OutputOwners rewards_owner = 4; // size(rewards_owner)
    uint32 shares = 5;                       // 04 bytes
}
```

### Unsigned Add Validator TX Example

Let's make an unsigned add validator TX that uses the inputs and outputs from the previous examples:

- **`BaseTx`**: `"Example BaseTx as defined above with ID set to 0c"`
- **`Validator`** Validator has a `NodeID`, `StartTime`, `EndTime`, and `Weight`
  - **`NodeID`** is 20 bytes which is the node ID of the validator.
  - **`StartTime`** is a long which is the Unix time when the validator starts validating.
  - **`EndTime`** is a long which is the Unix time when the validator stops validating.
  - **`Weight`** is a long which is the amount the validator stakes
- **`Stake`**: `0x0000000139c33a499ce4c33a3b09cdd2cfa01ae70dbf2d18b2d7d168524440e55d55008800000007000001d1a94a2000000000000000000000000001000000013cb7d3842e8cee6a0ebd09f1fe884f6861e1b29c`
- **`RewardsOwner`**: `0x0000000b00000000000000000000000100000001da2bee01be82ecc00c34f361eda8eb30fb5a715c`
- **`Shares`**: `0x00000064`

```text
[
    BaseTx       <- 0x0000000c000030390000000000000000000000000000000000000000000000000000000000000006870b7d66ac32540311379e5b5dbad28ec7eb8ddbfc8f4d67299ebb48475907a0000000700000000ee5be5c000000000000000000000000100000001da2bee01be82ecc00c34f361eda8eb30fb5a715cdfafbdf5c81f635c9257824ff21c8e3e6f7b632ac306e11446ee540d34711a15000000016870b7d66ac32540311379e5b5dbad28ec7eb8ddbfc8f4d67299ebb48475907a0000000500000000ee6b28000000000100000000
    NodeID       <- 0xe9094f73698002fd52c90819b457b9fbc866ab80
    StarTime     <- 0x000000005f21f31d
    EndTime      <- 0x000000005f497dc6
    Weight       <- 0x000000000000d431
    Stake        <- 0x0000000139c33a499ce4c33a3b09cdd2cfa01ae70dbf2d18b2d7d168524440e55d55008800000007000001d1a94a2000000000000000000000000001000000013cb7d3842e8cee6a0ebd09f1fe884f6861e1b29c
    RewardsOwner <- 0x0000000b00000000000000000000000100000001da2bee01be82ecc00c34f361eda8eb30fb5a715c
    Shares       <- 0x00000064
]
=
[
    // base tx:
    0x00, 0x00, 0x00, 0x0c, 0x00, 0x00, 0x30, 0x39,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x01, 0x68, 0x70, 0xb7, 0xd6,
    0x6a, 0xc3, 0x25, 0x40, 0x31, 0x13, 0x79, 0xe5,
    0xb5, 0xdb, 0xad, 0x28, 0xec, 0x7e, 0xb8, 0xdd,
    0xbf, 0xc8, 0xf4, 0xd6,
    0x72, 0x99, 0xeb, 0xb4, 0x84, 0x75, 0x90, 0x7a,
    0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00,
    0xee, 0x5b, 0xe5, 0xc0, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x01, 0xda, 0x2b, 0xee, 0x01,
    0xbe, 0x82, 0xec, 0xc0, 0x0c, 0x34, 0xf3, 0x61,
    0xed, 0xa8, 0xeb, 0x30, 0xfb, 0x5a, 0x71, 0x5c,
    0x00, 0x00, 0x00, 0x01,
    0xdf, 0xaf, 0xbd, 0xf5, 0xc8, 0x1f, 0x63, 0x5c,
    0x92, 0x57, 0x82, 0x4f, 0xf2, 0x1c, 0x8e, 0x3e,
    0x6f, 0x7b, 0x63, 0x2a, 0xc3, 0x06, 0xe1, 0x14,
    0x46, 0xee, 0x54, 0x0d, 0x34, 0x71, 0x1a, 0x15,
    0x00, 0x00, 0x00, 0x01,
    0x68, 0x70, 0xb7, 0xd6, 0x6a, 0xc3, 0x25, 0x40,
    0x31, 0x13, 0x79, 0xe5, 0xb5, 0xdb, 0xad, 0x28,
    0xec, 0x7e, 0xb8, 0xdd, 0xbf, 0xc8, 0xf4, 0xd6,
    0x72, 0x99, 0xeb, 0xb4, 0x84, 0x75, 0x90, 0x7a,
    0x00, 0x00, 0x00, 0x05, 0x00, 0x00, 0x00, 0x00,
    0xee, 0x6b, 0x28, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00,
    // Node ID
    0xe9, 0x09, 0x4f, 0x73, 0x69, 0x80, 0x02, 0xfd,
    0x52, 0xc9, 0x08, 0x19, 0xb4, 0x57, 0xb9, 0xfb,
    0xc8, 0x66, 0xab, 0x80,
    // StartTime
    0x00, 0x00, 0x00, 0x00, 0x5f, 0x21, 0xf3, 0x1d,
    // EndTime
    0x00, 0x00, 0x00, 0x00, 0x5f, 0x49, 0x7d, 0xc6,
    // Weight
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xd4, 0x31,
    // Stake
    0x00, 0x00, 0x00, 0x01, 0x39, 0xc3, 0x3a, 0x49,
    0x9c, 0xe4, 0xc3, 0x3a, 0x3b, 0x09, 0xcd, 0xd2,
    0xcf, 0xa0, 0x1a, 0xe7, 0x0d, 0xbf, 0x2d, 0x18,
    0xb2, 0xd7, 0xd1, 0x68, 0x52, 0x44, 0x40, 0xe5,
    0x5d, 0x55, 0x00, 0x88, 0x00, 0x00, 0x00, 0x07,
    0x00, 0x00, 0x01, 0xd1, 0xa9, 0x4a, 0x20, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x01,
    0x3c, 0xb7, 0xd3, 0x84, 0x2e, 0x8c, 0xee, 0x6a,
    0x0e, 0xbd, 0x09, 0xf1, 0xfe, 0x88, 0x4f, 0x68,
    0x61, 0xe1, 0xb2, 0x9c,
    // RewardsOwner
    0x00, 0x00, 0x00, 0x0b, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x01, 0xda, 0x2b, 0xee, 0x01,
    0xbe, 0x82, 0xec, 0xc0, 0x0c, 0x34, 0xf3, 0x61,
    0xed, 0xa8, 0xeb, 0x30, 0xfb, 0x5a, 0x71, 0x5c,
    // Shares
    0x00, 0x00, 0x00, 0x64,
]
```

## Unsigned Remove Avalanche L1 Validator TX

### What Unsigned Remove Avalanche L1 Validator TX Contains

An unsigned remove Avalanche L1 validator TX contains a `BaseTx`, `NodeID`,
`SubnetID`, and `SubnetAuth`. The `TypeID` for this type is 23 or `0x00000017`.

- **`BaseTx`**
- **`NodeID`** is the 20 byte node ID of the validator.
- **`SubnetID`** is the 32 byte Avalanche L1 ID (SubnetID) that the validator is being removed from.
- **`SubnetAuth`** contains `SigIndices` and has a type id of `0x0000000a`.
  `SigIndices` is a list of unique ints that define the addresses signing the
  control signature which proves that the issuer has the right to remove the
  node from the Avalanche L1. The array must be sorted low to high.

### Gantt Unsigned Remove Avalanche L1 Validator TX Specification

```text
+---------------+----------------------+------------------------------------------------+
| base_tx       : BaseTx               |                            size(base_tx) bytes |
+---------------+----------------------+------------------------------------------------+
| node_id       : [20]byte             |                                       20 bytes |
+---------------+----------------------+------------------------------------------------+
| subnet_id     : [32]byte             |                                       32 bytes |
+---------------+----------------------+------------------------------------------------+
| sig_indices   : SubnetAuth           |               4 bytes + len(sig_indices) bytes |
+---------------+----------------------+------------------------------------------------+
| 56 + len(sig_indices) + size(base_tx) bytes                                           |
+---------------------------------------------------------------------------------------+
```

### Proto Unsigned Remove Avalanche L1 Validator TX Specification

```text
message RemoveSubnetValidatorTx {
    BaseTx base_tx = 1;         // size(base_tx)
    string node_id = 2;         // 20 bytes
    SubnetID subnet_id = 3;     // 32 bytes
    SubnetAuth subnet_auth = 4; // 04 bytes + len(sig_indices)
}
```

### Unsigned Remove Avalanche L1 Validator TX Example

Let's make an unsigned remove Avalanche L1 validator TX that uses the inputs and
outputs from the previous examples:

- **`BaseTx`**: `"Example BaseTx as defined above with ID set to 17"`
- **`NodeID`**: `0xe902a9a86640bfdb1cd0e36c0cc982b83e5765fa`
- **`SubnetID`**: `0x4a177205df5c29929d06db9d941f83d5ea985de302015e99252d16469a6610db`
- **`SubnetAuth`**: `0x0000000a0000000100000000`

```text
[
    BaseTx       <- 0x0000000000013d0ad12b8ee8928edf248ca91ca55600fb383f07c32bff1d6dec472b25cf59a700000000000000000000000
    NodeID       <- 0xe902a9a86640bfdb1cd0e36c0cc982b83e5765fa
    SubnetID     <- 0x4a177205df5c29929d06db9d941f83d5ea985de302015e99252d16469a6610db
    SubnetAuth   <- 0x0000000a0000000100000000
]
=
[
    // BaseTx
    0x00, 0x00, 0x00, 0x17, 0x00, 0x00, 0x30, 0x39,
    0x3d, 0x0a, 0xd1, 0x2b, 0x8e, 0xe8, 0x92, 0x8e,
    0xdf, 0x24, 0x8c, 0xa9, 0x1c, 0xa5, 0x56, 0x00,
    0xfb, 0x38, 0x3f, 0x07, 0xc3, 0x2b, 0xff, 0x1d,
    0x6d, 0xec, 0x47, 0x2b, 0x25, 0xcf, 0x59, 0xa7,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00,
    // NodeID
    0xe9, 0x02, 0xa9, 0xa8, 0x66, 0x40, 0xbf, 0xdb,
    0x1c, 0xd0, 0xe3, 0x6c, 0x0c, 0xc9, 0x82, 0xb8,
    0x3e, 0x57, 0x65, 0xfa,
    // SubnetID
    0x4a, 0x17, 0x72, 0x05, 0xdf, 0x5c, 0x29, 0x92,
    0x9d, 0x06, 0xdb, 0x9d, 0x94, 0x1f, 0x83, 0xd5,
    0xea, 0x98, 0x5d, 0xe3, 0x02, 0x01, 0x5e, 0x99,
    0x25, 0x2d, 0x16, 0x46, 0x9a, 0x66, 0x10, 0xdb,
    // SubnetAuth
    // SubnetAuth TypeID
    0x00, 0x00, 0x00, 0x0a,
    // SigIndices length
    0x00, 0x00, 0x00, 0x01,
    // SigIndices
    0x00, 0x00, 0x00, 0x00,
]
```

## Unsigned Add Permissionless Validator TX

### What Unsigned Add Permissionless Validator TX Contains

An unsigned add permissionless validator TX contains a `BaseTx`, `Validator`,
`SubnetID`, `Signer`, `StakeOuts`, `ValidatorRewardsOwner`,
`DelegatorRewardsOwner`, and `DelegationShares`. The `TypeID` for this type is
25 or `0x00000019`.

- **`BaseTx`**
- **`Validator`** Validator has a `NodeID`, `StartTime`, `EndTime`, and `Weight`
  - **`NodeID`** is the 20 byte node ID of the validator.
  - **`StartTime`** is a long which is the Unix time when the validator starts validating.
  - **`EndTime`** is a long which is the Unix time when the validator stops validating.
  - **`Weight`** is a long which is the amount the validator stakes
- **`SubnetID`** is the 32 byte Avalanche L1 ID (SubnetID) of the Avalanche L1 this validator will validate.
- **`Signer`** If the [SubnetID] is the primary network, [Signer] is the type ID
  28 (`0x1C`) followed by a [Proof of Possession](#proof-of-possession). If the
  [SubnetID] is not the primary network, this value is the empty signer, whose
  byte representation is only the type ID 27 (`0x1B`).
- **`StakeOuts`** An array of Transferable Outputs. Where to send staked tokens when done validating.
- **`ValidatorRewardsOwner`** Where to send validation rewards when done validating.
- **`DelegatorRewardsOwner`** Where to send delegation rewards when done validating.
- **`DelegationShares`** a short which is the fee this validator charges
  delegators as a percentage, times 10,000 For example, if this validator has
  DelegationShares=300,000 then they take 30% of rewards from delegators.

### Gantt Unsigned Add Permissionless Validator TX Specification

```text
+---------------+----------------------+------------------------------------------------+
| base_tx       : BaseTx               |                            size(base_tx) bytes |
+---------------+----------------------+------------------------------------------------+
| validator     : Validator            |                                       44 bytes |
+---------------+----------------------+------------------------------------------------+
| subnet_id     : [32]byte             |                                       32 bytes |
+---------------+----------------------+------------------------------------------------+
| signer        : Signer               |                                      144 bytes |
+---------------+----------------------+------------------------------------------------+
| stake_outs    : []TransferOut        |                     4 + size(stake_outs) bytes |
+---------------+----------------------+------------------------------------------------+
| validator_rewards_owner : SECP256K1OutputOwners | size(validator_rewards_owner) bytes |
+---------------+----------------------+------------------------------------------------+
| delegator_rewards_owner : SECP256K1OutputOwners | size(delegator_rewards_owner) bytes |
+---------------+----------------------+------------------------------------------------+
| delegation_shares   : uint32         |                                        4 bytes |
+---------------+----------------------+------------------------------------------------+
| 232 + size(base_tx) + size(stake_outs) +                                              |
| size(validator_rewards_owner) + size(delegator_rewards_owner) bytes                   |
+---------------------------------------------------------------------------------------+
```

### Proto Unsigned Add Permissionless Validator TX Specification

```text
message AddPermissionlessValidatorTx {
    BaseTx base_tx = 1;         // size(base_tx)
    Validator validator = 2;    // 44 bytes
    SubnetID subnet_id = 3;     // 32 bytes
    Signer signer = 4; // 148 bytes
    repeated TransferOut stake_outs = 5; // 4 bytes + size(stake_outs)
    SECP256K1OutputOwners validator_rewards_owner = 6; // size(validator_rewards_owner) bytes
    SECP256K1OutputOwners delegator_rewards_owner = 7; // size(delegator_rewards_owner) bytes
    uint32 delegation_shares = 8; // 4 bytes
}
```

### Unsigned Add Permissionless Validator TX Example

Let's make an unsigned add permissionless validator TX that uses the inputs and
outputs from the previous examples:

- **`BaseTx`**: `"Example BaseTx as defined above with ID set to 1a"`
- **`Validator`**: `0x5fa29ed4356903dac2364713c60f57d8472c7dda000000006397616e0000000063beee6e000001d1a94a2000`
- **`SubnetID`**: `0xf3086d7bfc35be1c68db664ba9ce61a2060126b0d6b4bfb09fd7a5fb7678cada`
- **`Signer`**: `0x0000001ca5af179e4188583893c2b99e1a8be27d90a9213cfbff1d75b74fe2bc9f3b072c2ded0863a9d9acd9033f223295810e429238e28d3c9b7f7212b63d746b2ae73a54fe08a3de61b132f2f89e9eeff97d4d7ca3a3c88986aa855cd36296fcfe8f02162d0258be494d267d4c5798bc081ab602ded90b0fc16d8a035e68ff5294794cb63ff1ee068fbfc2b4c8cd2d08ebf297`
- **`StakeOuts`**: `0x000000013d0ad12b8ee8928edf248ca91ca55600fb383f07c32bff1d6dec472b25cf59a700000007000001d1a94a20000000000000000000000000010000000133eeffc64785cf9d80e7731d9f31f67bd03c5cf0`
- **`ValidatorRewardsOwner`**: `0x0000000b0000000000000000000000010000000172f3eb9aeaf8283011ce6e437fdecd65eace8f52`
- **`DelegatorRewardsOwner`**: `0x0000000b00000000000000000000000100000001b2b91313ac487c222445254e26cd026d21f6f440`
- **`DelegationShares`**: `0x00004e20`

```text
[
    BaseTx       <- 0x0000001a00003039e902a9a86640bfdb1cd0e36c0cc982b83e5765fad5f6bbe6abdcce7b5ae7d7c700000000000000014a177205df5c29929d06db9d941f83d5ea985de302015e99252d16469a6610db000000003d0ad12b8ee8928edf248ca91ca55600fb383f07c32bff1d6dec472b25cf59a700000005000001d1a94a2000000000010000000000000000
    Validator    <- 0x5fa29ed4356903dac2364713c60f57d8472c7dda000000006397616e0000000063beee6e000001d1a94a2000
    SubnetID     <- 0xf3086d7bfc35be1c68db664ba9ce61a2060126b0d6b4bfb09fd7a5fb7678cada
    Signer       <- 0x0000001ca5af179e4188583893c2b99e1a8be27d90a9213cfbff1d75b74fe2bc9f3b072c2ded0863a9d9acd9033f223295810e429238e28d3c9b7f7212b63d746b2ae73a54fe08a3de61b132f2f89e9eeff97d4d7ca3a3c88986aa855cd36296fcfe8f02162d0258be494d267d4c5798bc081ab602ded90b0fc16d8a035e68ff5294794cb63ff1ee068fbfc2b4c8cd2d08ebf297
    StakeOuts    <- 0x000000013d0ad12b8ee8928edf248ca91ca55600fb383f07c32bff1d6dec472b25cf59a700000007000001d1a94a20000000000000000000000000010000000133eeffc64785cf9d80e7731d9f31f67bd03c5cf0
    ValidatorRewardsOwner  <- 0x0000000b0000000000000000000000010000000172f3eb9aeaf8283011ce6e437fdecd65eace8f52
    DelegatorRewardsOwner  <- 0x0000000b0000000000000000000000010000000172f3eb9aeaf8283011ce6e437fdecd65eace8f52
    DelegationShares       <- 0x00004e20
]
=
[
    // BaseTx
    0x00, 0x00, 0x00, 0x1a, 0x00, 0x00, 0x30, 0x39,
    0xe9, 0x02, 0xa9, 0xa8, 0x66, 0x40, 0xbf, 0xdb,
    0x1c, 0xd0, 0xe3, 0x6c, 0x0c, 0xc9, 0x82, 0xb8,
    0x3e, 0x57, 0x65, 0xfa, 0xd5, 0xf6, 0xbb, 0xe6,
    0xab, 0xdc, 0xce, 0x7b, 0x5a, 0xe7, 0xd7, 0xc7,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x4a, 0x17, 0x72, 0x05, 0xdf, 0x5c, 0x29, 0x92,
    0x9d, 0x06, 0xdb, 0x9d, 0x94, 0x1f, 0x83, 0xd5,
    0xea, 0x98, 0x5d, 0xe3, 0x02, 0x01, 0x5e, 0x99,
    0x25, 0x2d, 0x16, 0x46, 0x9a, 0x66, 0x10, 0xdb,
    0x00, 0x00, 0x00, 0x00, 0x3d, 0x0a, 0xd1, 0x2b,
    0x8e, 0xe8, 0x92, 0x8e, 0xdf, 0x24, 0x8c, 0xa9,
    0x1c, 0xa5, 0x56, 0x00, 0xfb, 0x38, 0x3f, 0x07,
    0xc3, 0x2b, 0xff, 0x1d, 0x6d, 0xec, 0x47, 0x2b,
    0x25, 0xcf, 0x59, 0xa7, 0x00, 0x00, 0x00, 0x05,
    0x00, 0x00, 0x01, 0xd1, 0xa9, 0x4a, 0x20, 0x00,
    0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00,
    // Validator
    // NodeID
    0x5f, 0xa2, 0x9e, 0xd4, 0x35, 0x69, 0x03, 0xda,
    0xc2, 0x36, 0x47, 0x13, 0xc6, 0x0f, 0x57, 0xd8,
    0x47, 0x2c, 0x7d, 0xda, 0x
    // Start time
    0x00, 0x00, 0x00, 0x00, 0x63, 0x97, 0x61, 0x6e,
    // End time
    0x00, 0x00, 0x00, 0x00, 0x63, 0xbe, 0xee, 0x6e,
    // Weight
    0x00, 0x00, 0x01, 0xd1, 0xa9, 0x4a, 0x20, 0x00,
    // SubnetID
    0xf3, 0x08, 0x6d, 0x7b, 0xfc, 0x35, 0xbe, 0x1c,
    0x68, 0xdb, 0x66, 0x4b, 0xa9, 0xce, 0x61, 0xa2,
    0x06, 0x01, 0x26, 0xb0, 0xd6, 0xb4, 0xbf, 0xb0,
    0x9f, 0xd7, 0xa5, 0xfb, 0x76, 0x78, 0xca, 0xda,
    // Signer
    // TypeID
    0x00, 0x00, 0x00, 0x1c,
    // Pub key
    0xa5, 0xaf, 0x17, 0x9e, 0x41, 0x88, 0x58, 0x38,
    0x93, 0xc2, 0xb9, 0x9e, 0x1a, 0x8b, 0xe2, 0x7d,
    0x90, 0xa9, 0x21, 0x3c, 0xfb, 0xff, 0x1d, 0x75,
    0xb7, 0x4f, 0xe2, 0xbc, 0x9f, 0x3b, 0x07, 0x2c,
    0x2d, 0xed, 0x08, 0x63, 0xa9, 0xd9, 0xac, 0xd9,
    0x03, 0x3f, 0x22, 0x32, 0x95, 0x81, 0x0e, 0x42,
    // Sig
    0x92, 0x38, 0xe2, 0x8d, 0x3c, 0x9b, 0x7f, 0x72,
    0x12, 0xb6, 0x3d, 0x74, 0x6b, 0x2a, 0xe7, 0x3a,
    0x54, 0xfe, 0x08, 0xa3, 0xde, 0x61, 0xb1, 0x32,
    0xf2, 0xf8, 0x9e, 0x9e, 0xef, 0xf9, 0x7d, 0x4d,
    0x7c, 0xa3, 0xa3, 0xc8, 0x89, 0x86, 0xaa, 0x85,
    0x5c, 0xd3, 0x62, 0x96, 0xfc, 0xfe, 0x8f, 0x02,
    0x16, 0x2d, 0x02, 0x58, 0xbe, 0x49, 0x4d, 0x26,
    0x7d, 0x4c, 0x57, 0x98, 0xbc, 0x08, 0x1a, 0xb6,
    0x02, 0xde, 0xd9, 0x0b, 0x0f, 0xc1, 0x6d, 0x8a,
    0x03, 0x5e, 0x68, 0xff, 0x52, 0x94, 0x79, 0x4c,
    0xb6, 0x3f, 0xf1, 0xee, 0x06, 0x8f, 0xbf, 0xc2,
    0xb4, 0xc8, 0xcd, 0x2d, 0x08, 0xeb, 0xf2, 0x97,
    // Stake outs
    // Num stake outs
    0x00, 0x00, 0x00, 0x01,
    // AssetID
    0x3d, 0x0a, 0xd1, 0x2b, 0x8e, 0xe8, 0x92, 0x8e,
    0xdf, 0x24, 0x8c, 0xa9, 0x1c, 0xa5, 0x56, 0x00,
    0xfb, 0x38, 0x3f, 0x07, 0xc3, 0x2b, 0xff, 0x1d,
    0x6d, 0xec, 0x47, 0x2b, 0x25, 0xcf, 0x59, 0xa7,
    // Output
    // typeID
    0x00, 0x00, 0x00, 0x07,
    // Amount
    0x00, 0x00, 0x01, 0xd1, 0xa9, 0x4a, 0x20, 0x00,
    // Locktime
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    // Threshold
    0x00, 0x00, 0x00, 0x01,
    // Num addrs
    0x00, 0x00, 0x00, 0x01,
    // Addr 0
    0x33, 0xee, 0xff, 0xc6, 0x47, 0x85, 0xcf, 0x9d,
    0x80, 0xe7, 0x73, 0x1d, 0x9f, 0x31, 0xf6, 0x7b,
    0xd0, 0x3c, 0x5c, 0xf0,
    // Validator rewards owner
    // TypeID
    0x00, 0x00, 0x00, 0x0b,
    // Locktime
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    // Threshold
    0x00, 0x00, 0x00, 0x01,
    // Num addrs
    0x00, 0x00, 0x00, 0x01,
    // Addr 0
    0x72, 0xf3, 0xeb, 0x9a, 0xea, 0xf8, 0x28, 0x30,
    0x11, 0xce, 0x6e, 0x43, 0x7f, 0xde, 0xcd, 0x65,
    0xea, 0xce, 0x8f, 0x52,
    // Delegator rewards owner
    // TypeID
    0x00, 0x00, 0x00, 0x0b,
    // Locktime
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    // Threshold
    0x00, 0x00, 0x00, 0x01,
    // Num addrs
    0x00, 0x00, 0x00, 0x01,
    // Addr 0
    0xb2, 0xb9, 0x13, 0x13, 0xac, 0x48, 0x7c, 0x22,
    0x24, 0x45, 0x25, 0x4e, 0x26, 0xcd, 0x02, 0x6d,
    0x21, 0xf6, 0xf4, 0x40,
    // Delegation shares
    0x00, 0x00, 0x4e, 0x20,
]
```

## Unsigned Add Permissionless Delegator TX

### What Unsigned Add Permissionless Delegator TX Contains

An unsigned add permissionless delegator TX contains a `BaseTx`, `Validator`,
`SubnetID`, `StakeOuts`, and `DelegatorRewardsOwner`. The `TypeID` for this type
is 26 or `0x0000001a`.

- **`BaseTx`**
- **`Validator`** Validator has a `NodeID`, `StartTime`, `EndTime`, and `Weight`
  - **`NodeID`** is the 20 byte node ID of the validator.
  - **`StartTime`** is a long which is the Unix time when the validator starts validating.
  - **`EndTime`** is a long which is the Unix time when the validator stops validating.
  - **`Weight`** is a long which is the amount the validator stakes
- **`SubnetID`** is the 32 byte Avalanche L1 ID (SubnetID) of the Avalanche L1 this delegation is on.
- **`StakeOuts`** An array of Transferable Outputs. Where to send staked tokens when done validating.
- **`DelegatorRewardsOwner`** Where to send staking rewards when done validating.

### Gantt Unsigned Add Permissionless Delegator TX Specification

```text
+---------------+----------------------+------------------------------------------------+
| base_tx       : BaseTx               |                            size(base_tx) bytes |
+---------------+----------------------+------------------------------------------------+
| validator     : Validator            |                                       44 bytes |
+---------------+----------------------+------------------------------------------------+
| subnet_id     : [32]byte             |                                       32 bytes |
+---------------+----------------------+------------------------------------------------+
| stake_outs    : []TransferOut        |                     4 + size(stake_outs) bytes |
+---------------+----------------------+------------------------------------------------+
| delegator_rewards_owner : SECP256K1OutputOwners | size(delegator_rewards_owner) bytes |
+---------------+----------------------+------------------------------------------------+
| 80 + size(base_tx) + size(stake_outs) + size(delegator_rewards_owner) bytes           |
+---------------------------------------------------------------------------------------+
```

### Proto Unsigned Add Permissionless Delegator TX Specification

```text
message AddPermissionlessDelegatorTx {
    BaseTx base_tx = 1;         // size(base_tx)
    Validator validator = 2;    // size(validator)
    SubnetID subnet_id = 3;     // 32 bytes
    repeated TransferOut stake_outs = 4; // 4 bytes + size(stake_outs)
    SECP256K1OutputOwners delegator_rewards_owner = 5; // size(delegator_rewards_owner) bytes
}
```

### Unsigned Add Permissionless Delegator TX Example

Let's make an unsigned add permissionless delegator TX that uses the inputs and
outputs from the previous examples:

- **`BaseTx`**: `"Example BaseTx as defined above with ID set to 1a"`
- **`Validator`**: `0x5fa29ed4356903dac2364713c60f57d8472c7dda00000000639761970000000063beee97000001d1a94a2000`
- **`SubnetID`**: `0xf3086d7bfc35be1c68db664ba9ce61a2060126b0d6b4bfb09fd7a5fb7678cada`
- **`StakeOuts`**: `0x000000013d0ad12b8ee8928edf248ca91ca55600fb383f07c32bff1d6dec472b25cf59a700000007000001d1a94a20000000000000000000000000010000000133eeffc64785cf9d80e7731d9f31f67bd03c5cf0`
- **`DelegatorRewardsOwner`**: `0x0000000b0000000000000000000000010000000172f3eb9aeaf8283011ce6e437fdecd65eace8f52`

```text
[
    BaseTx       <- 0x0000001a00003039e902a9a86640bfdb1cd0e36c0cc982b83e5765fad5f6bbe6abdcce7b5ae7d7c700000000000000014a177205df5c29929d06db9d941f83d5ea985de302015e99252d16469a6610db000000003d0ad12b8ee8928edf248ca91ca55600fb383f07c32bff1d6dec472b25cf59a700000005000001d1a94a2000000000010000000000000000
    Validator    <- 0x5fa29ed4356903dac2364713c60f57d8472c7dda00000000639761970000000063beee97000001d1a94a2000
    SubnetID     <- 0xf3086d7bfc35be1c68db664ba9ce61a2060126b0d6b4bfb09fd7a5fb7678cada
    StakeOuts    <- 0x000000013d0ad12b8ee8928edf248ca91ca55600fb383f07c32bff1d6dec472b25cf59a700000007000001d1a94a20000000000000000000000000010000000133eeffc64785cf9d80e7731d9f31f67bd03c5cf0
    DelegatorRewardsOwner <- 0x0000000b0000000000000000000000010000000172f3eb9aeaf8283011ce6e437fdecd65eace8f52
]
=
[
    // BaseTx
    0x00, 0x00, 0x00, 0x1a, 0x00, 0x00, 0x30, 0x39,
    0xe9, 0x02, 0xa9, 0xa8, 0x66, 0x40, 0xbf, 0xdb,
    0x1c, 0xd0, 0xe3, 0x6c, 0x0c, 0xc9, 0x82, 0xb8,
    0x3e, 0x57, 0x65, 0xfa, 0xd5, 0xf6, 0xbb, 0xe6,
    0xab, 0xdc, 0xce, 0x7b, 0x5a, 0xe7, 0xd7, 0xc7,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x4a, 0x17, 0x72, 0x05, 0xdf, 0x5c, 0x29, 0x92,
    0x9d, 0x06, 0xdb, 0x9d, 0x94, 0x1f, 0x83, 0xd5,
    0xea, 0x98, 0x5d, 0xe3, 0x02, 0x01, 0x5e, 0x99,
    0x25, 0x2d, 0x16, 0x46, 0x9a, 0x66, 0x10, 0xdb,
    0x00, 0x00, 0x00, 0x00, 0x3d, 0x0a, 0xd1, 0x2b,
    0x8e, 0xe8, 0x92, 0x8e, 0xdf, 0x24, 0x8c, 0xa9,
    0x1c, 0xa5, 0x56, 0x00, 0xfb, 0x38, 0x3f, 0x07,
    0xc3, 0x2b, 0xff, 0x1d, 0x6d, 0xec, 0x47, 0x2b,
    0x25, 0xcf, 0x59, 0xa7, 0x00, 0x00, 0x00, 0x05,
    0x00, 0x00, 0x01, 0xd1, 0xa9, 0x4a, 0x20, 0x00,
    0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00,
    // Validator
    // NodeID
    0x5f, 0xa2, 0x9e, 0xd4, 0x35, 0x69, 0x03, 0xda,
    0xc2, 0x36, 0x47, 0x13, 0xc6, 0x0f, 0x57, 0xd8,
    0x47, 0x2c, 0x7d, 0xda,
    // Start time
    0x00, 0x00, 0x00, 0x00, 0x63, 0x97, 0x61, 0x97,
    // End time
    0x00, 0x00, 0x00, 0x00, 0x63, 0xbe, 0xee, 0x97,
    // Weight
    0x00, 0x00, 0x01, 0xd1, 0xa9, 0x4a, 0x20, 0x00,
    // Stake_outs
    // Num stake outs
    0x00, 0x00, 0x00, 0x01,
    // Stake out 0
    // AssetID
    0x3d, 0x0a, 0xd1, 0x2b, 0x8e, 0xe8, 0x92, 0x8e,
    0xdf, 0x24, 0x8c, 0xa9, 0x1c, 0xa5, 0x56, 0x00,
    0xfb, 0x38, 0x3f, 0x07, 0xc3, 0x2b, 0xff, 0x1d,
    0x6d, 0xec, 0x47, 0x2b, 0x25, 0xcf, 0x59, 0xa7,
    // TypeID
    0x00, 0x00, 0x00, 0x07,
    // Amount
    0x00, 0x00, 0x01, 0xd1, 0xa9, 0x4a, 0x20, 0x00,
    // Locktime
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    // Threshold
    0x00, 0x00, 0x00, 0x01,
    // Num addrs
    0x00, 0x00, 0x00, 0x01,
    // Addr 0
    0x33, 0xee, 0xff, 0xc6, 0x47, 0x85, 0xcf, 0x9d,
    0x80, 0xe7, 0x73, 0x1d, 0x9f, 0x31, 0xf6, 0x7b,
    0xd0, 0x3c, 0x5c, 0xf0,
    // Delegator_rewards_owner
    // TypeID
    0x00, 0x00, 0x00, 0x0b,
    // Locktime
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    // Threshold
    0x00, 0x00, 0x00, 0x01,
    // Num addrs
    0x00, 0x00, 0x00, 0x01,
    // Addr 0
    0x72, 0xf3, 0xeb, 0x9a, 0xea, 0xf8, 0x28, 0x30,
    0x11, 0xce, 0x6e, 0x43, 0x7f, 0xde, 0xcd, 0x65,
    0xea, 0xce, 0x8f, 0x52,
]
```

## Unsigned Transform Avalanche L1 TX

> **Note:** This transaction type has been disabled post-activation of ACP-77 (Etna upgrade). The `TransformSubnetTx` is no longer accepted on the P-Chain after the activation of this upgrade.

Transforms a permissioned Avalanche L1 into a permissionless Avalanche L1. Must be signed by the Avalanche L1 owner.

### What Unsigned Transform Avalanche L1 TX Contains

An unsigned transform Avalanche L1 TX contains a `BaseTx`, `SubnetID`, `AssetID`,
`InitialSupply`, `MaximumSupply`, `MinConsumptionRate`, `MaxConsumptionRate`,
`MinValidatorStake`, `MaxValidatorStake`, `MinStakeDuration`,
`MaxStakeDuration`, `MinDelegationFee`, `MinDelegatorStake`,
`MaxValidatorWeightFactor`, `UptimeRequirement`, and `SubnetAuth`. The `TypeID`
for this type is 24 or `0x00000018`.

- **`BaseTx`**
- **`SubnetID`** a 32-byte Avalanche L1 ID of the Avalanche L1 to transform.
- **`AssetID`** is a 32-byte array that defines which asset to use when staking on the Avalanche L1.
  - Restrictions
    - Must not be the Empty ID
    - Must not be the AVAX ID
- **`InitialSupply`** is a long which is the amount to initially specify as the current supply.
  - Restrictions
    - Must be > 0
- **`MaximumSupply`** is a long which is the amount to specify as the maximum token supply.
  - Restrictions
    - Must be >= [InitialSupply]
- **`MinConsumptionRate`** is a long which is the rate to allocate funds if the
  validator's stake duration is 0.
- **`MaxConsumptionRate`** is a long which is the rate to allocate funds if the
  validator's stake duration is equal to the minting period.
  - Restrictions
    - Must be `>=` [MinConsumptionRate]
    - Must be `<=` [`reward.PercentDenominator`]
- **`MinValidatorStake`** is a long which the minimum amount of funds required to become a validator.
  - Restrictions
    - Must be `>` 0
    - Must be `<=` [InitialSupply]
- **`MaxValidatorStake`** is a long which is the maximum amount of funds a
  single validator can be allocated, including delegated funds.
  - Restrictions:
    - Must be `>=` [MinValidatorStake]
    - Must be `<=` [MaximumSupply]
- **`MinStakeDuration`** is a short which is the minimum number of seconds a staker can stake for.
  - Restrictions
    - Must be `>` 0
- **`MaxStakeDuration`** is a short which is the maximum number of seconds a staker can stake for.
  - Restrictions
    - Must be `>=` [MinStakeDuration]
    - Must be `<=` [GlobalMaxStakeDuration]
- **`MinDelegationFee`** is a short is the minimum percentage a validator must
  charge a delegator for delegating.
  - Restrictions
    - Must be `<=` [`reward.PercentDenominator`]
- **`MinDelegatorStake`** is a short which is the minimum amount of funds required to become a delegator.
  - Restrictions
    - Must be `>` 0
- **`MaxValidatorWeightFactor`** is a byte which is the factor which calculates
  the maximum amount of delegation a validator can receive. Note: a value of 1
  effectively disables delegation.
  - Restrictions
    - Must be `>` 0
- **`UptimeRequirement`** is a short which is the minimum percentage a validator
  must be online and responsive to receive a reward.
  - Restrictions
    - Must be `<=` [`reward.PercentDenominator`]
- **`SubnetAuth`** contains `SigIndices` and has a type id of `0x0000000a`.
  `SigIndices` is a list of unique ints that define the addresses signing the
  control signature to authorizes this transformation. The array must be sorted
  low to high.

### Gantt Unsigned Transform Avalanche L1 TX Specification

```text
+----------------------+------------------+----------------------------------+
| base_tx              : BaseTx           |              size(base_tx) bytes |
+----------------------+------------------+----------------------------------+
| subnet_id            : [32]byte         |                         32 bytes |
+----------------------+------------------+----------------------------------+
| asset_id             : [32]byte         |                         32 bytes |
+----------------------+------------------+----------------------------------+
| initial_supply       : long             |                          8 bytes |
+----------------------+------------------+----------------------------------+
| maximum_supply       : long             |                          8 bytes |
+----------------------+------------------+----------------------------------+
| min_consumption_rate : long             |                          8 bytes |
+----------------------+------------------+----------------------------------+
| max_consumption_rate : long             |                          8 bytes |
+----------------------+------------------+----------------------------------+
| min_validator_stake  : long             |                          8 bytes |
+----------------------+------------------+----------------------------------+
| max_validator_stake  : long             |                          8 bytes |
+----------------------+------------------+----------------------------------+
| min_stake_duration   : short            |                          4 bytes |
+----------------------+------------------+----------------------------------+
| max_stake_duration   : short            |                          4 bytes |
+----------------------+------------------+----------------------------------+
| min_delegation_fee   : short            |                          4 bytes |
+----------------------+------------------+----------------------------------+
| min_delegator_stake  : long             |                          8 bytes |
+----------------------+------------------+----------------------------------+
| max_validator_weight_factor : byte      |                           1 byte |
+----------------------+------------------+----------------------------------+
| uptime_requirement   : short            |                          4 bytes |
+----------------------+------------------+----------------------------------+
| subnet_auth          : SubnetAuth       | 4 bytes + len(sig_indices) bytes |
+----------------------+------------------+----------------------------------+
| 141 + size(base_tx) + len(sig_indices) bytes                               |
+----------------------------------------------------------------------------+
```

### Proto Unsigned Transform Avalanche L1 TX Specification

```text
message TransformSubnetTx {
    BaseTx base_tx = 1;              // size(base_tx)
    SubnetID subnet_id = 2;          // 32 bytes
    bytes asset_id = 3;              // 32 bytes
    uint64 initial_supply = 4;       // 08 bytes
    uint64 maximum_supply = 5;       // 08 bytes
    uint64 min_consumption_rate = 6; // 08 bytes
    uint64 max_consumption_rate = 7; // 08 bytes
    uint64 min_validator_stake = 8;  // 08 bytes
    uint64 max_validator_stake = 9;  // 08 bytes
    uint32 min_stake_duration = 10;  // 04 bytes
    uint32 max_stake_duration = 11;  // 04 bytes
    uint32 min_delegation_fee = 12;  // 04 bytes
    uint32 min_delegator_stake = 13; // 08 bytes
    byte max_validator_weight_factor = 14; // 01 byte
    uint32 uptime_requirement = 15; // 04 bytes
    SubnetAuth subnet_auth = 16;    // 04 bytes + len(sig_indices)
}
```

### Unsigned Transform Avalanche L1 TX Example

Let's make an unsigned transform Avalanche L1 TX that uses the inputs and outputs from the previous examples:

- **`BaseTx`**: `"Example BaseTx as defined above with ID set to 18"`
- **`SubnetID`**: `0x5fa29ed4356903dac2364713c60f57d8472c7dda4a5e08d88a88ad8ea71aed60`
- **`AssetID`**: `0xf3086d7bfc35be1c68db664ba9ce61a2060126b0d6b4bfb09fd7a5fb7678cada`
- **`InitialSupply`**: `0x000000e8d4a51000`
- **`MaximumSupply`**: `0x000009184e72a000`
- **`MinConsumptionRate`**: `0x0000000000000001`
- **`MaxConsumptionRate`**: `0x000000000000000a`
- **`MinValidatorStake`**: `0x000000174876e800`
- **`MaxValidatorStake`**: `0x000001d1a94a2000`
- **`MinStakeDuration`**: `0x00015180`
- **`MaxStakeDuration`**: `0x01e13380`
- **`MinDelegationFee`**: `0x00002710`
- **`MinDelegatorStake`**: `0x000000174876e800`
- **`MaxValidatorWeightFactor`**: `0x05`
- **`UptimeRequirement`**: `0x000c3500`
- **`SubnetAuth`**:
  - **`TypeID`**: `0x0000000a`
  - **`SigIndices`**: `0x00000000`

```text
[
    BaseTx       <- 0000001800003039e902a9a86640bfdb1cd0e36c0cc982b83e5765fad5f6bbe6abdcce7b5ae7d7c700000000000000014a177205df5c29929d06db9d941f83d5ea985de302015e99252d16469a6610db000000003d0ad12b8ee8928edf248ca91ca55600fb383f07c32bff1d6dec472b25cf59a70000000500000000000f4240000000010000000000000000
    SubnetID     <- 0x5fa29ed4356903dac2364713c60f57d8472c7dda4a5e08d88a88ad8ea71aed60
    AssetID      <- 0xf3086d7bfc35be1c68db664ba9ce61a2060126b0d6b4bfb09fd7a5fb7678cada
    InitialSupply <- 0x000000e8d4a51000
    MaximumSupply <- 0x000009184e72a000
    MinConsumptionRate <- 0x0000000000000001
    MaxConsumptionRate <- 0x000000000000000a
    MinValidatorStake <- 0x000000174876e800
    MaxValidatorStake <- 0x000001d1a94a2000
    MinStakeDuration <- 0x00015180
    MaxStakeDuration <- 0x01e13380
    MinDelegationFee <- 0x00002710
    MinDelegatorStake <- 0x000000174876e800
    MaxValidatorWeightFactor <- 0x05
    UptimeRequirement <- 0x000c3500
    SubnetAuth   <- 0x0000000a0000000100000000
]
=
[
    // BaseTx:
    0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x30, 0x39,
    0xe9, 0x02, 0xa9, 0xa8, 0x66, 0x40, 0xbf, 0xdb,
    0x1c, 0xd0, 0xe3, 0x6c, 0x0c, 0xc9, 0x82, 0xb8,
    0x3e, 0x57, 0x65, 0xfa, 0xd5, 0xf6, 0xbb, 0xe6,
    0xab, 0xdc, 0xce, 0x7b, 0x5a, 0xe7, 0xd7, 0xc7,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x4a, 0x17, 0x72, 0x05, 0xdf, 0x5c, 0x29, 0x92,
    0x9d, 0x06, 0xdb, 0x9d, 0x94, 0x1f, 0x83, 0xd5,
    0xea, 0x98, 0x5d, 0xe3, 0x02, 0x01, 0x5e, 0x99,
    0x25, 0x2d, 0x16, 0x46, 0x9a, 0x66, 0x10, 0xdb,
    0x00, 0x00, 0x00, 0x00, 0x3d, 0x0a, 0xd1, 0x2b,
    0x8e, 0xe8, 0x92, 0x8e, 0xdf, 0x24, 0x8c, 0xa9,
    0x1c, 0xa5, 0x56, 0x00, 0xfb, 0x38, 0x3f, 0x07,
    0xc3, 0x2b, 0xff, 0x1d, 0x6d, 0xec, 0x47, 0x2b,
    0x25, 0xcf, 0x59, 0xa7, 0x00, 0x00, 0x00, 0x05,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x0f, 0x42, 0x40,
    0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x5f, 0xa2, 0x9e, 0xd4,
    0x35, 0x69, 0x03, 0xda, 0xc2, 0x36, 0x47, 0x13,
    0xc6, 0x0f, 0x57, 0xd8, 0x47, 0x2c, 0x7d, 0xda,
    0x4a, 0x5e, 0x08, 0xd8, 0x8a, 0x88, 0xad, 0x8e,
    0xa7, 0x1a, 0xed, 0x60, 0xf3, 0x08, 0x6d, 0x7b,
    0xfc, 0x35, 0xbe, 0x1c, 0x68, 0xdb, 0x66, 0x4b,
    0xa9, 0xce, 0x61, 0xa2, 0x06, 0x01, 0x26, 0xb0,
    0xd6, 0xb4, 0xbf, 0xb0, 0x9f, 0xd7, 0xa5, 0xfb,
    0x76, 0x78, 0xca, 0xda, 0x00, 0x00, 0x00, 0xe8,
    0xd4, 0xa5, 0x10, 0x00, 0x00, 0x00, 0x09, 0x18,
    0x4e, 0x72, 0xa0, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x0a, 0x00, 0x00, 0x00, 0x17,
    0x48, 0x76, 0xe8, 0x00, 0x00, 0x00, 0x01, 0xd1,
    0xa9, 0x4a, 0x20, 0x00, 0x00, 0x01, 0x51, 0x80,
    0x01, 0xe1, 0x33, 0x80, 0x00, 0x00, 0x27, 0x10,
    0x00, 0x00, 0x00, 0x17, 0x48, 0x76, 0xe8, 0x00,
    0x05, 0x00, 0x0c, 0x35, 0x00, 0x00, 0x00, 0x00,
    0x0a, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00,
    0x00,
    // SubnetID
    0x5f, 0xa2, 0x9e, 0xd4, 0x35, 0x69, 0x03, 0xda,
    0xc2, 0x36, 0x47, 0x13, 0xc6, 0x0f, 0x57, 0xd8,
    0x47, 0x2c, 0x7d, 0xda, 0x4a, 0x5e, 0x08, 0xd8,
    0x8a, 0x88, 0xad, 0x8e, 0xa7, 0x1a, 0xed, 0x60,
    // AssetID
    0xf3, 0x08, 0x6d, 0x7b, 0xfc, 0x35, 0xbe, 0x1c,
    0x68, 0xdb, 0x66, 0x4b, 0xa9, 0xce, 0x61, 0xa2,
    0x06, 0x01, 0x26, 0xb0, 0xd6, 0xb4, 0xbf, 0xb0,
    0x9f, 0xd7, 0xa5, 0xfb, 0x76, 0x78, 0xca, 0xda,
    // InitialSupply
    0x00, 0x00, 0x00, 0xe8, 0xd4, 0xa5, 0x10, 0x00,
    // MaximumSupply
    0x00, 0x00, 0x09, 0x18, 0x4e, 0x72, 0xa0, 0x00,
    // MinConsumptionRate
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
    // MaxConsumptionRate
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x0a,
    // MinValidatorStake
    0x00, 0x00, 0x00, 0x17, 0x48, 0x76, 0xe8, 0x00,
    // MaxValidatorStake
    0x00, 0x00, 0x01, 0xd1, 0xa9, 0x4a, 0x20, 0x00,
    // MinStakeDuration
    0x00, 0x01, 0x51, 0x80,
    // MaxStakeDuration
    0x01, 0xe1, 0x33, 0x80,
    // MinDelegationFee
    0x00, 0x00, 0x27, 0x10,
    // MinDelegatorStake
    0x00, 0x00, 0x00, 0x17, 0x48, 0x76, 0xe8, 0x00,
    // MaxValidatorWeightFactor
    0x05,
    // UptimeRequirement
    0x00, 0x0c, 0x35, 0x00,
```
// SubnetAuth
```
    // SubnetAuth TypeID
    0x00, 0x00, 0x00, 0x0a,
    // SigIndices length
    0x00, 0x00, 0x00, 0x01,
    // SigIndices
    0x00, 0x00, 0x00, 0x00,
]
```

## Unsigned Add Avalanche L1 Validator TX

### What Unsigned Add Avalanche L1 Validator TX Contains

An unsigned add Avalanche L1 validator TX contains a `BaseTx`, `Validator`,
`SubnetID`, and `SubnetAuth`. The `TypeID` for this type is `0x0000000d`.

- **`BaseTx`**
- **`Validator`** Validator has a `NodeID`, `StartTime`, `EndTime`, and `Weight`
  - **`NodeID`** is the 20 byte node ID of the validator.
  - **`StartTime`** is a long which is the Unix time when the validator starts validating.
  - **`EndTime`** is a long which is the Unix time when the validator stops validating.
  - **`Weight`** is a long which is the amount the validator stakes
- **`SubnetID`** is the 32 byte Avalanche L1 ID to add the validator to.
- **`SubnetAuth`** contains `SigIndices` and has a type id of `0x0000000a`.
  `SigIndices` is a list of unique ints that define the addresses signing the
  control signature to add a validator to an Avalanche L1. The array must be sorted low
  to high.

### Gantt Unsigned Add Avalanche L1 Validator TX Specification

```text
+---------------+----------------------+-----------------------------------------+
| base_tx       : BaseTx               |                     size(base_tx) bytes |
+---------------+----------------------+-----------------------------------------+
| validator     : Validator            |                                44 bytes |
+---------------+----------------------+-----------------------------------------+
| subnet_id     : [32]byte             |                                32 bytes |
+---------------+----------------------+-----------------------------------------+
| subnet_auth   : SubnetAuth           |        4 bytes + len(sig_indices) bytes |
+---------------+----------------------+-----------------------------------------+
                                   | 80 + len(sig_indices) + size(base_tx) bytes |
                                   +---------------------------------------------+
```

### Proto Unsigned Add Avalanche L1 Validator TX Specification

```text
message AddSubnetValidatorTx {
    BaseTx base_tx = 1;         // size(base_tx)
    Validator validator = 2;    // size(validator)
    SubnetID subnet_id = 3;     // 32 bytes
    SubnetAuth subnet_auth = 4; // 04 bytes + len(sig_indices)
}
```

### Unsigned Add Avalanche L1 Validator TX Example

Let's make an unsigned add Avalanche L1 validator TX that uses the inputs and outputs from the previous examples:

- **`BaseTx`**: `"Example BaseTx as defined above with ID set to 0d"`
- **`NodeID`**: `0xe9094f73698002fd52c90819b457b9fbc866ab80`
- **`StarTime`**: `0x000000005f21f31d`
- **`EndTime`**: `0x000000005f497dc6`
- **`Weight`**: `0x000000000000d431`
- **`SubnetID`**: `0x58b1092871db85bc752742054e2e8be0adf8166ec1f0f0769f4779f14c71d7eb`
- **`SubnetAuth`**:
  - **`TypeID`**: `0x0000000a`
  - **`SigIndices`**: `0x00000000`

```text
[
    BaseTx       <- 0x0000000d000030390000000000000000000000000000000000000000000000000000000000000006870b7d66ac32540311379e5b5dbad28ec7eb8ddbfc8f4d67299ebb48475907a0000000700000000ee5be5c000000000000000000000000100000001da2bee01be82ecc00c34f361eda8eb30fb5a715cdfafbdf5c81f635c9257824ff21c8e3e6f7b632ac306e11446ee540d34711a15000000016870b7d66ac32540311379e5b5dbad28ec7eb8ddbfc8f4d67299ebb48475907a0000000500000000ee6b28000000000100000000
    NodeID       <- 0xe9094f73698002fd52c90819b457b9fbc866ab80
    StarTime     <- 0x000000005f21f31d
    EndTime      <- 0x000000005f497dc6
    Weight       <- 0x000000000000d431
    SubnetID     <- 0x58b1092871db85bc752742054e2e8be0adf8166ec1f0f0769f4779f14c71d7eb
    SubnetAuth TypeID   <- 0x0000000a
    SubnetAuth   <- 0x00000000
]
=
[
    // base tx:
    0x00, 0x00, 0x00, 0x0d,
    0x00, 0x00, 0x30, 0x39,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x01,
    0x68, 0x70, 0xb7, 0xd6, 0x6a, 0xc3, 0x25, 0x40,
    0x31, 0x13, 0x79, 0xe5, 0xb5, 0xdb, 0xad, 0x28,
    0xec, 0x7e, 0xb8, 0xdd, 0xbf, 0xc8, 0xf4, 0xd6,
    0x72, 0x99, 0xeb, 0xb4, 0x84, 0x75, 0x90, 0x7a,
    0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00,
    0xee, 0x5b, 0xe5, 0xc0, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x01, 0xda, 0x2b, 0xee, 0x01,
    0xbe, 0x82, 0xec, 0xc0, 0x0c, 0x34, 0xf3, 0x61,
    0xed, 0xa8, 0xeb, 0x30, 0xfb, 0x5a, 0x71, 0x5c,
    0x00, 0x00, 0x00, 0x01,
    0xdf, 0xaf, 0xbd, 0xf5, 0xc8, 0x1f, 0x63, 0x5c,
    0x92, 0x57, 0x82, 0x4f, 0xf2, 0x1c, 0x8e, 0x3e,
    0x6f, 0x7b, 0x63, 0x2a, 0xc3, 0x06, 0xe1, 0x14,
    0x46, 0xee, 0x54, 0x0d, 0x34, 0x71, 0x1a, 0x15,
    0x00, 0x00, 0x00, 0x01,
    0x68, 0x70, 0xb7, 0xd6, 0x6a, 0xc3, 0x25, 0x40,
    0x31, 0x13, 0x79, 0xe5, 0xb5, 0xdb, 0xad, 0x28,
    0xec, 0x7e, 0xb8, 0xdd, 0xbf, 0xc8, 0xf4, 0xd6,
    0x72, 0x99, 0xeb, 0xb4, 0x84, 0x75, 0x90, 0x7a,
    0x00, 0x00, 0x00, 0x05, 0x00, 0x00, 0x00, 0x00,
    0xee, 0x6b, 0x28, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00,
    // Node ID
    0xe9, 0x09, 0x4f, 0x73, 0x69, 0x80, 0x02, 0xfd,
    0x52, 0xc9, 0x08, 0x19, 0xb4, 0x57, 0xb9, 0xfb,
    0xc8, 0x66, 0xab, 0x80,
    // StartTime
    0x00, 0x00, 0x00, 0x00, 0x5f, 0x21, 0xf3, 0x1d,
    // EndTime
    0x00, 0x00, 0x00, 0x00, 0x5f, 0x49, 0x7d, 0xc6,
    // Weight
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xd4, 0x31,
    // SubnetID
    0x58, 0xb1, 0x09, 0x28, 0x71, 0xdb, 0x85, 0xbc,
    0x75, 0x27, 0x42, 0x05, 0x4e, 0x2e, 0x8b, 0xe0,
    0xad, 0xf8, 0x16, 0x6e, 0xc1, 0xf0, 0xf0, 0x76,
    0x9f, 0x47, 0x79, 0xf1, 0x4c, 0x71, 0xd7, 0xeb,
    // SubnetAuth
    // SubnetAuth TypeID
    0x00, 0x00, 0x00, 0x0a,
    // SigIndices length
    0x00, 0x00, 0x00, 0x01,
    // SigIndices
    0x00, 0x00, 0x00, 0x00,
]
```

## Unsigned Add Delegator TX

### What Unsigned Add Delegator TX Contains

An unsigned add delegator TX contains a `BaseTx`, `Validator`, `Stake`, and
`RewardsOwner`. The `TypeID` for this type is `0x0000000e`.

- **`BaseTx`**
- **`Validator`** Validator has a `NodeID`, `StartTime`, `EndTime`, and `Weight`
  - **`NodeID`** is 20 bytes which is the node ID of the delegatee.
  - **`StartTime`** is a long which is the Unix time when the delegator starts delegating.
  - **`EndTime`** is a long which is the Unix time when the delegator stops
    delegating (and staked AVAX is returned).
  - **`Weight`** is a long which is the amount the delegator stakes
- **`Stake`** Stake has `LockedOuts`
  - **`LockedOuts`** An array of Transferable Outputs that are locked for the
    duration of the staking period. At the end of the staking period, these
    outputs are refunded to their respective addresses.
- **`RewardsOwner`** An `SECP256K1OutputOwners`

### Gantt Unsigned Add Delegator TX Specification

```text
+---------------+-----------------------+-----------------------------------------+
| base_tx       : BaseTx                |                     size(base_tx) bytes |
+---------------+-----------------------+-----------------------------------------+
| validator     : Validator             |                                44 bytes |
+---------------+-----------------------+-----------------------------------------+
| stake         : Stake                 |                  size(LockedOuts) bytes |
+---------------+-----------------------+-----------------------------------------+
| rewards_owner : SECP256K1OutputOwners |               size(rewards_owner) bytes |
+---------------+-----------------------+-----------------------------------------+
                |    44 + size(stake) + size(rewards_owner) + size(base_tx) bytes |
                +-----------------------------------------------------------------+
```

### Proto Unsigned Add Delegator TX Specification

```text
message AddDelegatorTx {
    BaseTx base_tx = 1;                      // size(base_tx)
    Validator validator = 2;                 // 44 bytes
    Stake stake = 3;                         // size(LockedOuts)
    SECP256K1OutputOwners rewards_owner = 4; // size(rewards_owner)
}
```

### Unsigned Add Delegator TX Example

Let's make an unsigned add delegator TX that uses the inputs and outputs from the previous examples:

- **`BaseTx`**: `"Example BaseTx as defined above with ID set to 0e"`
- **`NodeID`**: `0xe9094f73698002fd52c90819b457b9fbc866ab80`
- **`StarTime`**: `0x000000005f21f31d`
- **`EndTime`**: `0x000000005f497dc6`
- **`Weight`**: `0x000000000000d431`
- **`Stake`**: `0x0000000139c33a499ce4c33a3b09cdd2cfa01ae70dbf2d18b2d7d168524440e55d55008800000007000001d1a94a2000000000000000000000000001000000013cb7d3842e8cee6a0ebd09f1fe884f6861e1b29c`
- **`RewardsOwner`**: `0x0000000b00000000000000000000000100000001da2bee01be82ecc00c34f361eda8eb30fb5a715c`

```text
[
    BaseTx       <- 0x0000000e000030390000000000000000000000000000000000000000000000000000000000000006870b7d66ac32540311379e5b5dbad28ec7eb8ddbfc8f4d67299ebb48475907a0000000700000000ee5be5c000000000000000000000000100000001da2bee01be82ecc00c34f361eda8eb30fb5a715cdfafbdf5c81f635c9257824ff21c8e3e6f7b632ac306e11446ee540d34711a15000000016870b7d66ac32540311379e5b5dbad28ec7eb8ddbfc8f4d67299ebb48475907a0000000500000000ee6b28000000000100000000
    NodeID       <- 0xe9094f73698002fd52c90819b457b9fbc866ab80
    StarTime     <- 0x000000005f21f31d
    EndTime      <- 0x000000005f497dc6
    Weight       <- 0x000000000000d431
    Stake        <- 0x0000000139c33a499ce4c33a3b09cdd2cfa01ae70dbf2d18b2d7d168524440e55d55008800000007000001d1a94a2000000000000000000000000001000000013cb7d3842e8cee6a0ebd09f1fe884f6861e1b29c
    RewardsOwner <- 0x0000000b00000000000000000000000100000001da2bee01be82ecc00c34f361eda8eb30fb5a715c
]
=
[
    // base tx:
    0x00, 0x00, 0x00, 0x0e, 0x00, 0x00, 0x30, 0x39,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x01,
    0x68, 0x70, 0xb7, 0xd6, 0x6a, 0xc3, 0x25, 0x40,
    0x31, 0x13, 0x79, 0xe5, 0xb5, 0xdb, 0xad, 0x28,
    0xec, 0x7e, 0xb8, 0xdd, 0xbf, 0xc8, 0xf4, 0xd6,
    0x72, 0x99, 0xeb, 0xb4, 0x84, 0x75, 0x90, 0x7a,
    0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00,
    0xee, 0x5b, 0xe5, 0xc0, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x01, 0xda, 0x2b, 0xee, 0x01,
    0xbe, 0x82, 0xec, 0xc0, 0x0c, 0x34, 0xf3, 0x61,
    0xed, 0xa8, 0xeb, 0x30, 0xfb, 0x5a, 0x71, 0x5c,
    0x00, 0x00, 0x00, 0x01,
    0xdf, 0xaf, 0xbd, 0xf5, 0xc8, 0x1f, 0x63, 0x5c,
    0x92, 0x57, 0x82, 0x4f, 0xf2, 0x1c, 0x8e, 0x3e,
    0x6f, 0x7b, 0x63, 0x2a, 0xc3, 0x06, 0xe1, 0x14,
    0x46, 0xee, 0x54, 0x0d, 0x34, 0x71, 0x1a, 0x15,
    0x00, 0x00, 0x00, 0x01,
    0x68, 0x70, 0xb7, 0xd6, 0x6a, 0xc3, 0x25, 0x40,
    0x31, 0x13, 0x79, 0xe5, 0xb5, 0xdb, 0xad, 0x28,
    0xec, 0x7e, 0xb8, 0xdd, 0xbf, 0xc8, 0xf4, 0xd6,
    0x72, 0x99, 0xeb, 0xb4, 0x84, 0x75, 0x90, 0x7a,
    0x00, 0x00, 0x00, 0x05, 0x00, 0x00, 0x00, 0x00,
    0xee, 0x6b, 0x28, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00,
    // Node ID
    0xe9, 0x09, 0x4f, 0x73, 0x69, 0x80, 0x02, 0xfd,
    0x52, 0xc9, 0x08, 0x19, 0xb4, 0x57, 0xb9, 0xfb,
    0xc8, 0x66, 0xab, 0x80,
    // StartTime
    0x00, 0x00, 0x00, 0x00, 0x5f, 0x21, 0xf3, 0x1d,
    // EndTime
    0x00, 0x00, 0x00, 0x00, 0x5f, 0x49, 0x7d, 0xc6,
    // Weight
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xd4, 0x31,
    // Stake
    0x00, 0x00, 0x00, 0x01, 0x39, 0xc3, 0x3a, 0x49,
    0x9c, 0xe4, 0xc3, 0x3a, 0x3b, 0x09, 0xcd, 0xd2,
    0xcf, 0xa0, 0x1a, 0xe7, 0x0d, 0xbf, 0x2d, 0x18,
    0xb2, 0xd7, 0xd1, 0x68, 0x52, 0x44, 0x40, 0xe5,
    0x5d, 0x55, 0x00, 0x88, 0x00, 0x00, 0x00, 0x07,
    0x00, 0x00, 0x01, 0xd1, 0xa9, 0x4a, 0x20, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x01,
    0x3c, 0xb7, 0xd3, 0x84, 0x2e, 0x8c, 0xee, 0x6a,
    0x0e, 0xbd, 0x09, 0xf1, 0xfe, 0x88, 0x4f, 0x68,
    0x61, 0xe1, 0xb2, 0x9c,
    // RewardsOwner
    0x00, 0x00, 0x00, 0x0b, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x01, 0xda, 0x2b, 0xee, 0x01,
    0xbe, 0x82, 0xec, 0xc0, 0x0c, 0x34, 0xf3, 0x61,
    0xed, 0xa8, 0xeb, 0x30, 0xfb, 0x5a, 0x71, 0x5c,
]
```

## Unsigned Create Chain TX

### What Unsigned Create Chain TX Contains

An unsigned create chain TX contains a `BaseTx`, `SubnetID`, `ChainName`,
`VMID`, `FxIDs`, `GenesisData` and `SubnetAuth`. The `TypeID` for this type is
`0x0000000f`.

- **`BaseTx`**
- **`SubnetID`** ID of the Avalanche L1 that validates this blockchain
- **`ChainName`** A human readable name for the chain; need not be unique
- **`VMID`** ID of the VM running on the new chain
- **`FxIDs`** IDs of the feature extensions running on the new chain
- **`GenesisData`** Byte representation of genesis state of the new chain
- **`SubnetAuth`** Authorizes this blockchain to be added to this Avalanche L1

### Gantt Unsigned Create Chain TX Specification

```text
+--------------+-------------+------------------------------------------+
| base_tx      : BaseTx      |                      size(base_tx) bytes |
+--------------+-------------+------------------------------------------+
| subnet_id    : SubnetID    |                                 32 bytes |
+--------------+-------------+------------------------------------------+
| chain_name   : ChainName   |                2 + len(chain_name) bytes |
+--------------+-------------+------------------------------------------+
| vm_id        : VMID        |                                 32 bytes |
+--------------+-------------+------------------------------------------+
| fx_ids       : FxIDs       |                   4 + size(fx_ids) bytes |
+--------------+-------------+------------------------------------------+
| genesis_data : GenesisData |             4 + size(genesis_data) bytes |
+--------------+-------------+------------------------------------------+
| subnet_auth  : SubnetAuth  |                  size(subnet_auth) bytes |
+--------------+-------------+------------------------------------------+
               | 74 + size(base_tx) + size(chain_name) + size(fx_ids) + |
               |           size(genesis_data) + size(subnet_auth) bytes |
+--------------+--------------------------------------------------------+
```

### Proto Unsigned Create Chain TX Specification

```text
message CreateChainTx {
    BaseTx base_tx = 1;               // size(base_tx)
    SubnetID subnet_id = 2;           // 32 bytes
    ChainName chain_name = 3;         // 2 + len(chain_name) bytes
    VMID vm_id = 4;                   // 32 bytes
    FxIDs fx_ids = 5;                 // 4 + size(fx_ids) bytes
    GenesisData genesis_data = 6      // 4 + size(genesis_data) bytes
    SubnetAuth subnet_auth = 7;       // size(subnet_auth) bytes
}
```

### Unsigned Create Chain TX Example

Let's make an unsigned create chain TX that uses the inputs and outputs from the previous examples:

- **`BaseTx`**: `"Example BaseTx as defined above with ID set to 0f"`
- **`SubnetID`**: `24tZhrm8j8GCJRE9PomW8FaeqbgGS4UAQjJnqqn8pq5NwYSYV1`
- **`ChainName`**: `EPIC AVM`
- **`VMID`**: `avm`
- **`FxIDs`**: [`secp256k1fx`]
- **`GenesisData`**: `11111DdZMhYXUZiFV9FNpfpTSQroysXhzWicG954YAKfkrk3bCEzLVY7gun1eAmAwMiQzVhtGpdR6dnPVcfhBE7brzkJ1r4wzi3dgA8G9Jwc4WpZ6Uh4Dr9aTdw7sFA5cpvCAVBsx6Xf3CB82jwH1gjPZ3WQnnCSKr2reoLtam6TfyYRra5xxXSkZcUm6BaJMW4fKzNP58uyExajPYKZvT5LrQ7MPJ9Fp7ebmYSzXg7YYauNARj`
- **`SubnetAuth`**: `0x0000000a0000000100000000`

```text
[
    BaseTx       <- 0x0000000f000030390000000000000000000000000000000000000000000000000000000000000006870b7d66ac32540311379e5b5dbad28ec7eb8ddbfc8f4d67299ebb48475907a0000000700000000ee5be5c000000000000000000000000100000001da2bee01be82ecc00c34f361eda8eb30fb5a715cdfafbdf5c81f635c9257824ff21c8e3e6f7b632ac306e11446ee540d34711a15000000016870b7d66ac32540311379e5b5dbad28ec7eb8ddbfc8f4d67299ebb48475907a0000000500000000ee6b28000000000100000000
    SubnetID     <- 0x8c86d07cd60218661863e0116552dccd5bd84c564bd29d7181dbddd5ec616104
    ChainName    <- 0x455049432041564d
    VMID         <- 0x61766d0000000000000000000000000000000000000000000000000000000000
    FxIDs        <- 0x736563703235366b316678000000000000000000000000000000000000000000
    GenesisData  <- 0x000000000001000e4173736574416c6961735465737400000539000000000000000000000000000000000000000000000000000000000000000000000000000000000000001b66726f6d20736e6f77666c616b6520746f206176616c616e636865000a54657374204173736574000454455354000000000100000000000000010000000700000000000001fb000000000000000000000001000000013cb7d3842e8cee6a0ebd09f1fe884f6861e1b29c
    SubnetAuth   <- 0x0000000a0000000100000000
]
=
[
  // base tx
  0x00, 0x00, 0x00, 0x0f,
  0x00, 0x00, 0x30, 0x39, 0x00, 0x00, 0x00, 0x00,
  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
  0x39, 0xc3, 0x3a, 0x49, 0x9c, 0xe4, 0xc3, 0x3a,
  0x3b, 0x09, 0xcd, 0xd2, 0xcf, 0xa0, 0x1a, 0xe7,
  0x0d, 0xbf, 0x2d, 0x18, 0xb2, 0xd7, 0xd1, 0x68,
  0x52, 0x44, 0x40, 0xe5, 0x5d, 0x55, 0x00, 0x88,
  0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x12, 0x30,
  0x9c, 0xd5, 0xfd, 0xc0, 0x00, 0x00, 0x00, 0x00,
  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
  0x00, 0x00, 0x00, 0x01, 0x3c, 0xb7, 0xd3, 0x84,
  0x2e, 0x8c, 0xee, 0x6a, 0x0e, 0xbd, 0x09, 0xf1,
  0xfe, 0x88, 0x4f, 0x68, 0x61, 0xe1, 0xb2, 0x9c,
  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
  // end base tx

  // Subnet id
  0x8c, 0x86, 0xd0, 0x7c, 0xd6, 0x02, 0x18, 0x66,
  0x18, 0x63, 0xe0, 0x11, 0x65, 0x52, 0xdc, 0xcd,
  0x5b, 0xd8, 0x4c, 0x56, 0x4b, 0xd2, 0x9d, 0x71,
  0x81, 0xdb, 0xdd, 0xd5, 0xec, 0x61, 0x61, 0x04,

  // chain name length
  0x00, 0x08,

  // chain name
  0x45, 0x50, 0x49, 0x43, 0x20, 0x41, 0x56, 0x4d,

  // vm id
  0x61, 0x76, 0x6d, 0x00, 0x00, 0x00, 0x00, 0x00,
  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,

  // fxids
  // num fxids
  0x00, 0x00, 0x00, 0x01,
  // fxid
  0x73, 0x65, 0x63, 0x70, 0x32, 0x35, 0x36, 0x6b,
  0x31, 0x66, 0x78, 0x00, 0x00, 0x00, 0x00, 0x00,
  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,

  // genesis data len
  0x00, 0x00, 0x00, 0xb0,
  // genesis data
  0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0x00, 0x0e,
  0x41, 0x73, 0x73, 0x65, 0x74, 0x41, 0x6c, 0x69,
  0x61, 0x73, 0x54, 0x65, 0x73, 0x74, 0x00, 0x00,
  0x05, 0x39, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
  0x00, 0x00, 0x00, 0x00, 0x00, 0x1b, 0x66, 0x72,
  0x6f, 0x6d, 0x20, 0x73, 0x6e, 0x6f, 0x77, 0x66,
  0x6c, 0x61, 0x6b, 0x65, 0x20, 0x74, 0x6f, 0x20,
  0x61, 0x76, 0x61, 0x6c, 0x61, 0x6e, 0x63, 0x68,
  0x65, 0x00, 0x0a, 0x54, 0x65, 0x73, 0x74, 0x20,
  0x41, 0x73, 0x73, 0x65, 0x74, 0x00, 0x04, 0x54,
  0x45, 0x53, 0x54, 0x00, 0x00, 0x00, 0x00, 0x01,
  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
  0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00,
  0x00, 0x00, 0x01, 0xfb, 0x00, 0x00, 0x00, 0x00,
  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
  0x00, 0x00, 0x00, 0x01, 0x3c, 0xb7, 0xd3, 0x84,
  0x2e, 0x8c, 0xee, 0x6a, 0x0e, 0xbd, 0x09, 0xf1,
  0xfe, 0x88, 0x4f, 0x68, 0x61, 0xe1, 0xb2, 0x9c,

  // type id (Subnet Auth)
  0x00, 0x00, 0x00, 0x0a,
  // num address indices
  0x00, 0x00, 0x00, 0x01,
  // address index
  0x00, 0x00, 0x00, 0x00,
]
```

## Unsigned Create Avalanche L1 TX

### What Unsigned Create Avalanche L1 TX Contains

An unsigned create Avalanche L1 TX contains a `BaseTx`, and `RewardsOwner`. The `TypeID` for this type is `0x00000010`.

- **`BaseTx`**
- **`RewardsOwner`** A `SECP256K1OutputOwners`

### Gantt Unsigned Create Avalanche L1 TX Specification

```text
+-----------------+-----------------------|---------------------------------+
| base_tx         : BaseTx                |             size(base_tx) bytes |
+-----------------+-----------------------+--------------------------------+
| rewards_owner   : SECP256K1OutputOwners |       size(rewards_owner) bytes |
+-----------------+-----------------------+---------------------------------+
                                | size(rewards_owner) + size(base_tx) bytes |
                                +-------------------------------------------+
```

### Proto Unsigned Create Avalanche L1 TX Specification

```text
message CreateSubnetTx {
    BaseTx base_tx = 1;                      // size(base_tx)
    SECP256K1OutputOwners rewards_owner = 2; // size(rewards_owner)
}
```

### Unsigned Create Avalanche L1 TX Example

Let's make an unsigned create Avalanche L1 TX that uses the inputs from the previous examples:

- **`BaseTx`**: "Example BaseTx as defined above but with TypeID set to 16"
- **`RewardsOwner`**:
  - **`TypeId`**: 11
  - **`Locktime`**: 0
  - **`Threshold`**: 1
  - **`Addresses`**: \[ 0xda2bee01be82ecc00c34f361eda8eb30fb5a715c \]

```text
[
    BaseTx        <- 0x00000010000030390000000000000000000000000000000000000000000000000000000000000006870b7d66ac32540311379e5b5dbad28ec7eb8ddbfc8f4d67299ebb48475907a0000000700000000ee5be5c000000000000000000000000100000001da2bee01be82ecc00c34f361eda8eb30fb5a715cdfafbdf5c81f635c9257824ff21c8e3e6f7b632ac306e11446ee540d34711a15000000016870b7d66ac32540311379e5b5dbad28ec7eb8ddbfc8f4d67299ebb48475907a0000000500000000ee6b28000000000100000000
    RewardsOwner <-
        TypeID    <- 0x0000000b
        Locktime  <- 0x0000000000000000
        Threshold <- 0x00000001
        Addresses <- [
            0xda2bee01be82ecc00c34f361eda8eb30fb5a715c,
        ]
]
=
[
    // base tx:
    0x00, 0x00, 0x00, 0x10,
    0x00, 0x00, 0x30, 0x39, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x39, 0xc3, 0x3a, 0x49, 0x9c, 0xe4, 0xc3, 0x3a,
    0x3b, 0x09, 0xcd, 0xd2, 0xcf, 0xa0, 0x1a, 0xe7,
    0x0d, 0xbf, 0x2d, 0x18, 0xb2, 0xd7, 0xd1, 0x68,
    0x52, 0x44, 0x40, 0xe5, 0x5d, 0x55, 0x00, 0x88,
    0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x12, 0x30,
    0x9c, 0xd5, 0xfd, 0xc0, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x01, 0x3c, 0xb7, 0xd3, 0x84,
    0x2e, 0x8c, 0xee, 0x6a, 0x0e, 0xbd, 0x09, 0xf1,
    0xfe, 0x88, 0x4f, 0x68, 0x61, 0xe1, 0xb2, 0x9c,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    // RewardsOwner type id
    0x00, 0x00, 0x00, 0x0b,
    // locktime:
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    // threshold:
    0x00, 0x00, 0x00, 0x01,
    // number of addresses:
    0x00, 0x00, 0x00, 0x01,
    // addrs[0]:
    0xda, 0x2b, 0xee, 0x01,
    0xbe, 0x82, 0xec, 0xc0, 0x0c, 0x34, 0xf3, 0x61,
    0xed, 0xa8, 0xeb, 0x30, 0xfb, 0x5a, 0x71, 0x5c
]
```

## Unsigned Import TX

### What Unsigned Import TX Contains

An unsigned import TX contains a `BaseTx`, `SourceChain`, and `Ins`. The `TypeID` for this type is `0x00000011`.

- **`BaseTx`**
- **`SourceChain`** is a 32-byte source blockchain ID.
- **`Ins`** is a variable length array of Transferable Inputs.

### Gantt Unsigned Import TX Specification

```text
+-----------------+--------------|---------------------------------+
| base_tx         : BaseTx       |             size(base_tx) bytes |
+-----------------+--------------+---------------------------------+
| source_chain    : [32]byte     |                        32 bytes |
+-----------------+--------------+---------------------------------+
| ins             : []TransferIn |             4 + size(ins) bytes |
+-----------------+--------------+---------------------------------+
                            | 36 + size(ins) + size(base_tx) bytes |
                            +--------------------------------------+
```

### Proto Unsigned Import TX Specification

```text
message ImportTx {
    BaseTx base_tx = 1;          // size(base_tx)
    bytes source_chain = 2;      // 32 bytes
    repeated TransferIn ins = 3; // 4 bytes + size(ins)
}
```

### Unsigned Import TX Example

Let's make an unsigned import TX that uses the inputs from the previous examples:

- **`BaseTx`**: "Example BaseTx as defined above with TypeID set to 17"
- **`SourceChain`**:
- **`Ins`**: "Example SECP256K1 Transfer Input as defined above"

```text
[
    BaseTx        <- 0x00000011000030390000000000000000000000000000000000000000000000000000000000000006870b7d66ac32540311379e5b5dbad28ec7eb8ddbfc8f4d67299ebb48475907a0000000700000000ee5be5c000000000000000000000000100000001da2bee01be82ecc00c34f361eda8eb30fb5a715cdfafbdf5c81f635c9257824ff21c8e3e6f7b632ac306e11446ee540d34711a15000000016870b7d66ac32540311379e5b5dbad28ec7eb8ddbfc8f4d67299ebb48475907a0000000500000000ee6b28000000000100000000
    SourceChain   <- 0x787cd3243c002e9bf5bbbaea8a42a16c1a19cc105047c66996807cbf16acee10
    Ins <- [
            // input:
    ]
]
=
[
    // base tx:
    0x00, 0x00, 0x00, 0x11,
    0x00, 0x00, 0x30, 0x39, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x39, 0xc3, 0x3a, 0x49, 0x9c, 0xe4, 0xc3, 0x3a,
    0x3b, 0x09, 0xcd, 0xd2, 0xcf, 0xa0, 0x1a, 0xe7,
    0x0d, 0xbf, 0x2d, 0x18, 0xb2, 0xd7, 0xd1, 0x68,
    0x52, 0x44, 0x40, 0xe5, 0x5d, 0x55, 0x00, 0x88,
    0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x12, 0x30,
    0x9c, 0xd5, 0xfd, 0xc0, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x01, 0x3c, 0xb7, 0xd3, 0x84,
    0x2e, 0x8c, 0xee, 0x6a, 0x0e, 0xbd, 0x09, 0xf1,
    0xfe, 0x88, 0x4f, 0x68, 0x61, 0xe1, 0xb2, 0x9c,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    // sourceChain
    0x78, 0x7c, 0xd3, 0x24, 0x3c, 0x00, 0x2e, 0x9b,
    0xf5, 0xbb, 0xba, 0xea, 0x8a, 0x42, 0xa1, 0x6c,
    0x1a, 0x19, 0xcc, 0x10, 0x50, 0x47, 0xc6, 0x69,
    0x96, 0x80, 0x7c, 0xbf, 0x16, 0xac, 0xee, 0x10,
    // input count:
    0x00, 0x00, 0x00, 0x01,
    // txID:
    0xf1, 0xe1, 0xd1, 0xc1, 0xb1, 0xa1, 0x91, 0x81,
    0x71, 0x61, 0x51, 0x41, 0x31, 0x21, 0x11, 0x01,
    0xf0, 0xe0, 0xd0, 0xc0, 0xb0, 0xa0, 0x90, 0x80,
    0x70, 0x60, 0x50, 0x40, 0x30, 0x20, 0x10, 0x00,
    // utxoIndex:
    0x00, 0x00, 0x00, 0x05,
    // assetID:
    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
    0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
    0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
    0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
    // input:
    0x00, 0x00, 0x00, 0x05, 0x00, 0x00, 0x00, 0x00,
    0xee, 0x6b, 0x28, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x00,
]
```

## Unsigned Export TX

### What Unsigned Export TX Contains

An unsigned export TX contains a `BaseTx`, `DestinationChain`, and `Outs`. The
`TypeID` for this type is `0x00000012`.

- **`DestinationChain`** is the 32 byte ID of the chain where the funds are being exported to.
- **`Outs`** is a variable length array of Transferable Outputs.

### Gantt Unsigned Export TX Specification

```text
+-------------------+---------------+--------------------------------------+
| base_tx           : BaseTx        |                  size(base_tx) bytes |
+-------------------+---------------+--------------------------------------+
| destination_chain : [32]byte      |                             32 bytes |
+-------------------+---------------+--------------------------------------+
| outs              : []TransferOut |                 4 + size(outs) bytes |
+-------------------+---------------+--------------------------------------+
                          | 36 + size(outs) + size(base_tx) bytes |
                          +---------------------------------------+
```

### Proto Unsigned Export TX Specification

```text
message ExportTx {
    BaseTx base_tx = 1;            // size(base_tx)
    bytes destination_chain = 2;   // 32 bytes
    repeated TransferOut outs = 3; // 4 bytes + size(outs)
}
```

### Unsigned Export TX Example

Let's make an unsigned export TX that uses the outputs from the previous examples:

- `BaseTx`: "Example BaseTx as defined above" with `TypeID` set to 18
- `DestinationChain`: `0x0000000000000000000000000000000000000000000000000000000000000000`
- `Outs`: "Example SECP256K1 Transfer Output as defined above"

```text
[
    BaseTx           <- 0x00000012000030390000000000000000000000000000000000000000000000000000000000000006870b7d66ac32540311379e5b5dbad28ec7eb8ddbfc8f4d67299ebb48475907a0000000700000000ee5be5c000000000000000000000000100000001da2bee01be82ecc00c34f361eda8eb30fb5a715cdfafbdf5c81f635c9257824ff21c8e3e6f7b632ac306e11446ee540d34711a15000000016870b7d66ac32540311379e5b5dbad28ec7eb8ddbfc8f4d67299ebb48475907a0000000500000000ee6b28000000000100000000
    DestinationChain <- 0x0000000000000000000000000000000000000000000000000000000000000000
    Outs <- [
        000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f000000070000000000003039000000000000d431000000010000000251025c61fbcfc078f69334f834be6dd26d55a955c3344128e060128ede3523a24a461c8943ab0859,
    ]
]
=
[
    // base tx:
    0x00, 0x00, 0x00, 0x12
    0x00, 0x00, 0x00, 0x04, 0xff, 0xff, 0xff, 0xff,
    0xee, 0xee, 0xee, 0xee, 0xdd, 0xdd, 0xdd, 0xdd,
    0xcc, 0xcc, 0xcc, 0xcc, 0xbb, 0xbb, 0xbb, 0xbb,
    0xaa, 0xaa, 0xaa, 0xaa, 0x99, 0x99, 0x99, 0x99,
    0x88, 0x88, 0x88, 0x88, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
    0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
    0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
    0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
    0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x30, 0x39, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0xd4, 0x31, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x02, 0x51, 0x02, 0x5c, 0x61,
    0xfb, 0xcf, 0xc0, 0x78, 0xf6, 0x93, 0x34, 0xf8,
    0x34, 0xbe, 0x6d, 0xd2, 0x6d, 0x55, 0xa9, 0x55,
    0xc3, 0x34, 0x41, 0x28, 0xe0, 0x60, 0x12, 0x8e,
    0xde, 0x35, 0x23, 0xa2, 0x4a, 0x46, 0x1c, 0x89,
    0x43, 0xab, 0x08, 0x59, 0x00, 0x00, 0x00, 0x01,
    0xf1, 0xe1, 0xd1, 0xc1, 0xb1, 0xa1, 0x91, 0x81,
    0x71, 0x61, 0x51, 0x41, 0x31, 0x21, 0x11, 0x01,
    0xf0, 0xe0, 0xd0, 0xc0, 0xb0, 0xa0, 0x90, 0x80,
    0x70, 0x60, 0x50, 0x40, 0x30, 0x20, 0x10, 0x00,
    0x00, 0x00, 0x00, 0x05, 0x00, 0x01, 0x02, 0x03,
    0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b,
    0x0c, 0x0d, 0x0e, 0x0f, 0x10, 0x11, 0x12, 0x13,
    0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1a, 0x1b,
    0x1c, 0x1d, 0x1e, 0x1f, 0x00, 0x00, 0x00, 0x05,
    0x00, 0x00, 0x00, 0x00, 0x07, 0x5b, 0xcd, 0x15,
    0x00, 0x00, 0x00, 0x02, 0x00, 0x00, 0x00, 0x07,
    0x00, 0x00, 0x00, 0x03, 0x00, 0x00, 0x00, 0x04,
    0x00, 0x01, 0x02, 0x03
    // destination_chain:
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    // outs[] count:
    0x00, 0x00, 0x00, 0x01,
    // assetID:
    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
    0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
    0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
    0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
    // output:
    0x00, 0x00, 0x00, 0x07,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x30, 0x39,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xd4, 0x31,
    0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x02,
    0x51, 0x02, 0x5c, 0x61, 0xfb, 0xcf, 0xc0, 0x78,
    0xf6, 0x93, 0x34, 0xf8, 0x34, 0xbe, 0x6d, 0xd2,
    0x6d, 0x55, 0xa9, 0x55, 0xc3, 0x34, 0x41, 0x28,
    0xe0, 0x60, 0x12, 0x8e, 0xde, 0x35, 0x23, 0xa2,
    0x4a, 0x46, 0x1c, 0x89, 0x43, 0xab, 0x08, 0x59,
]
```

## Credentials

Credentials have one possible types: `SECP256K1Credential`. Each credential is
paired with an Input or Operation. The order of the credentials match the order
of the inputs or operations.

## SECP256K1 Credential

A [secp256k1](/docs/api-reference/standards/cryptographic-primitives#secp256k1-addresses) credential
contains a list of 65-byte recoverable signatures.

### What SECP256K1 Credential Contains

- **`TypeID`** is the ID for this type. It is `0x00000009`.
- **`Signatures`** is an array of 65-byte recoverable signatures. The order of
  the signatures must match the input's signature indices.

### Gantt SECP256K1 Credential Specification

```text
+------------------------------+---------------------------------+
| type_id         : int        |                         4 bytes |
+-----------------+------------+---------------------------------+
| signatures      : [][65]byte |  4 + 65 * len(signatures) bytes |
+-----------------+------------+---------------------------------+
                               |  8 + 65 * len(signatures) bytes |
                               +---------------------------------+
```

### Proto SECP256K1 Credential Specification

```text
message SECP256K1Credential {
    uint32 TypeID = 1;             // 4 bytes
    repeated bytes signatures = 2; // 4 bytes + 65 bytes * len(signatures)
}
```

### SECP256K1 Credential Example

Let's make a payment input with:

- **`signatures`**:
- `0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1e1d1f202122232425262728292a2b2c2e2d2f303132333435363738393a3b3c3d3e3f00`
- `0x404142434445464748494a4b4c4d4e4f505152535455565758595a5b5c5e5d5f606162636465666768696a6b6c6e6d6f707172737475767778797a7b7c7d7e7f00`

```text
[
    Signatures <- [
        0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1e1d1f202122232425262728292a2b2c2e2d2f303132333435363738393a3b3c3d3e3f00,
        0x404142434445464748494a4b4c4d4e4f505152535455565758595a5b5c5e5d5f606162636465666768696a6b6c6e6d6f707172737475767778797a7b7c7d7e7f00,
    ]
]
=
[
    // Type ID
    0x00, 0x00, 0x00, 0x09,
    // length:
    0x00, 0x00, 0x00, 0x02,
    // sig[0]
    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
    0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
    0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
    0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1e, 0x1d, 0x1f,
    0x20, 0x21, 0x22, 0x23, 0x24, 0x25, 0x26, 0x27,
    0x28, 0x29, 0x2a, 0x2b, 0x2c, 0x2e, 0x2d, 0x2f,
    0x30, 0x31, 0x32, 0x33, 0x34, 0x35, 0x36, 0x37,
    0x38, 0x39, 0x3a, 0x3b, 0x3c, 0x3d, 0x3e, 0x3f,
    0x00,
    // sig[1]
    0x40, 0x41, 0x42, 0x43, 0x44, 0x45, 0x46, 0x47,
    0x48, 0x49, 0x4a, 0x4b, 0x4c, 0x4d, 0x4e, 0x4f,
    0x50, 0x51, 0x52, 0x53, 0x54, 0x55, 0x56, 0x57,
    0x58, 0x59, 0x5a, 0x5b, 0x5c, 0x5e, 0x5d, 0x5f,
    0x60, 0x61, 0x62, 0x63, 0x64, 0x65, 0x66, 0x67,
    0x68, 0x69, 0x6a, 0x6b, 0x6c, 0x6e, 0x6d, 0x6f,
    0x70, 0x71, 0x72, 0x73, 0x74, 0x75, 0x76, 0x77,
    0x78, 0x79, 0x7a, 0x7b, 0x7c, 0x7d, 0x7e, 0x7f,
    0x00,
]
```

## Signed Transaction

A signed transaction is an unsigned transaction with the addition of an array of credentials.

### What Signed Transaction Contains

A signed transaction contains a `CodecID`, `UnsignedTx`, and `Credentials`.

- **`CodecID`** The only current valid codec id is `00 00`.
- **`UnsignedTx`** is an unsigned transaction, as described above.
- **`Credentials`** is an array of credentials. Each credential will be paired
  with the input in the same index at this credential.

### Gantt Signed Transaction Specification

```text
+---------------------+--------------+------------------------------------------------+
| codec_id            : uint16       |                                        2 bytes |
+---------------------+--------------+------------------------------------------------+
| unsigned_tx         : UnsignedTx   |                        size(unsigned_tx) bytes |
+---------------------+--------------+------------------------------------------------+
| credentials         : []Credential |                    4 + size(credentials) bytes |
+---------------------+--------------+------------------------------------------------+
                                     | 6 + size(unsigned_tx) + len(credentials) bytes |
                                     +------------------------------------------------+
```

### Proto Signed Transaction Specification

```text
message Tx {
    uint32 codec_id = 1;                 // 2 bytes
    UnsignedTx unsigned_tx = 2;          // size(unsigned_tx)
    repeated Credential credentials = 3; // 4 bytes + size(credentials)
}
```

### Signed Transaction Example

Let's make a signed transaction that uses the unsigned transaction and credential from the previous examples.

- **`CodecID`**: `0`
- **`UnsignedTx`**: `0x0000000100000003ffffffffeeeeeeeeddddddddccccccccbbbbbbbbaaaaaaaa999999998888888800000001000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f000000070000000000003039000000000000d431000000010000000251025c61fbcfc078f69334f834be6dd26d55a955c3344128e060128ede3523a24a461c8943ab085900000001f1e1d1c1b1a191817161514131211101f0e0d0c0b0a09080706050403020100000000005000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f0000000500000000075bcd150000000200000003000000070000000400010203`
- **`Credentials`** `0x0000000900000002000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1e1d1f202122232425262728292a2b2c2e2d2f303132333435363738393a3b3c3d3e3f00404142434445464748494a4b4c4d4e4f505152535455565758595a5b5c5e5d5f606162636465666768696a6b6c6e6d6f707172737475767778797a7b7c7d7e7f00`

```text
[
    CodecID     <- 0x0000
    UnsignedTx  <- 0x0000000100000003ffffffffeeeeeeeeddddddddccccccccbbbbbbbbaaaaaaaa999999998888888800000001000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f000000070000000000003039000000000000d431000000010000000251025c61fbcfc078f69334f834be6dd26d55a955c3344128e060128ede3523a24a461c8943ab085900000001f1e1d1c1b1a191817161514131211101f0e0d0c0b0a09080706050403020100000000005000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f0000000500000000075bcd150000000200000003000000070000000400010203
    Credentials <- [
        0x0000000900000002000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1e1d1f202122232425262728292a2b2c2e2d2f303132333435363738393a3b3c3d3e3f00404142434445464748494a4b4c4d4e4f505152535455565758595a5b5c5e5d5f606162636465666768696a6b6c6e6d6f707172737475767778797a7b7c7d7e7f00,
    ]
]
=
[
    // Codec ID
    0x00, 0x00,
    // unsigned transaction:
    0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x03,
    0xff, 0xff, 0xff, 0xff, 0xee, 0xee, 0xee, 0xee,
    0xdd, 0xdd, 0xdd, 0xdd, 0xcc, 0xcc, 0xcc, 0xcc,
    0xbb, 0xbb, 0xbb, 0xbb, 0xaa, 0xaa, 0xaa, 0xaa,
    0x99, 0x99, 0x99, 0x99, 0x88, 0x88, 0x88, 0x88,
    0x00, 0x00, 0x00, 0x01, 0x00, 0x01, 0x02, 0x03,
    0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b,
    0x0c, 0x0d, 0x0e, 0x0f, 0x10, 0x11, 0x12, 0x13,
    0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1a, 0x1b,
    0x1c, 0x1d, 0x1e, 0x1f, 0x00, 0x00, 0x00, 0x07,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x30, 0x39,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xd4, 0x31,
    0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x02,
    0x51, 0x02, 0x5c, 0x61, 0xfb, 0xcf, 0xc0, 0x78,
    0xf6, 0x93, 0x34, 0xf8, 0x34, 0xbe, 0x6d, 0xd2,
    0x6d, 0x55, 0xa9, 0x55, 0xc3, 0x34, 0x41, 0x28,
    0xe0, 0x60, 0x12, 0x8e, 0xde, 0x35, 0x23, 0xa2,
    0x4a, 0x46, 0x1c, 0x89, 0x43, 0xab, 0x08, 0x59,
    0x00, 0x00, 0x00, 0x01, 0xf1, 0xe1, 0xd1, 0xc1,
    0xb1, 0xa1, 0x91, 0x81, 0x71, 0x61, 0x51, 0x41,
    0x31, 0x21, 0x11, 0x01, 0xf0, 0xe0, 0xd0, 0xc0,
    0xb0, 0xa0, 0x90, 0x80, 0x70, 0x60, 0x50, 0x40,
    0x30, 0x20, 0x10, 0x00, 0x00, 0x00, 0x00, 0x05,
    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
    0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
    0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
    0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
    0x00, 0x00, 0x00, 0x05, 0x00, 0x00, 0x00, 0x00,
    0x07, 0x5b, 0xcd, 0x15, 0x00, 0x00, 0x00, 0x02,
    0x00, 0x00, 0x00, 0x03, 0x00, 0x00, 0x00, 0x07,
    0x00, 0x00, 0x00, 0x04, 0x00, 0x01, 0x02, 0x03
    // number of credentials:
    0x00, 0x00, 0x00, 0x01,
    // credential[0]:
    0x00, 0x00, 0x00, 0x09, 0x00, 0x00, 0x00, 0x02,
    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
    0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
    0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
    0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1e, 0x1d, 0x1f,
    0x20, 0x21, 0x22, 0x23, 0x24, 0x25, 0x26, 0x27,
    0x28, 0x29, 0x2a, 0x2b, 0x2c, 0x2e, 0x2d, 0x2f,
    0x30, 0x31, 0x32, 0x33, 0x34, 0x35, 0x36, 0x37,
    0x38, 0x39, 0x3a, 0x3b, 0x3c, 0x3d, 0x3e, 0x3f,
    0x00, 0x40, 0x41, 0x42, 0x43, 0x44, 0x45, 0x46,
    0x47, 0x48, 0x49, 0x4a, 0x4b, 0x4c, 0x4d, 0x4e,
    0x4f, 0x50, 0x51, 0x52, 0x53, 0x54, 0x55, 0x56,
    0x57, 0x58, 0x59, 0x5a, 0x5b, 0x5c, 0x5e, 0x5d,
    0x5f, 0x60, 0x61, 0x62, 0x63, 0x64, 0x65, 0x66,
    0x67, 0x68, 0x69, 0x6a, 0x6b, 0x6c, 0x6e, 0x6d,
    0x6f, 0x70, 0x71, 0x72, 0x73, 0x74, 0x75, 0x76,
    0x77, 0x78, 0x79, 0x7a, 0x7b, 0x7c, 0x7d, 0x7e,
    0x7f, 0x00,
]
```

## UTXO

A UTXO is a standalone representation of a transaction output.

### What UTXO Contains

A UTXO contains a `CodecID`, `TxID`, `UTXOIndex`, and `Output`.

- **`CodecID`** The only current valid codec id is `00 00`.
- **`TxID`** is a 32-byte transaction ID. Transaction IDs are calculated by
  taking sha256 of the bytes of the signed transaction.
- **`UTXOIndex`** is an int that specifies which output in the transaction
  specified by **`TxID`** that this utxo was created by.
- **`AssetID`** is a 32-byte array that defines which asset this utxo
  references.
- **`Output`** is the output object that created this utxo. The serialization of
  Outputs was defined above.

#### Gantt UTXO Specification

```text
+--------------+----------+-------------------------+
| codec_id     : uint16   |                 2 bytes |
+--------------+----------+-------------------------+
| tx_id        : [32]byte |                32 bytes |
+--------------+----------+-------------------------+
| output_index : int      |                 4 bytes |
+--------------+----------+-------------------------+
| asset_id     : [32]byte |                32 bytes |
+--------------+----------+-------------------------+
| output       : Output   |      size(output) bytes |
+--------------+----------+-------------------------+
                          | 70 + size(output) bytes |
                          +-------------------------+
```

### Proto UTXO Specification

```text
message Utxo {
    uint32 codec_id = 1;     // 02 bytes
    bytes tx_id = 2;         // 32 bytes
    uint32 output_index = 3; // 04 bytes
    bytes asset_id = 4;      // 32 bytes
    Output output = 5;       // size(output)
}
```

### UTXO Example

Let's make a UTXO from the signed transaction created above:

- **`CodecID`**: `0`
- **`TxID`**: `0xf966750f438867c3c9828ddcdbe660e21ccdbb36a9276958f011ba472f75d4e7`
- **`UTXOIndex`**: 0x00000000
- **`AssetID`**: `0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f`
- **`Output`**: `"Example SECP256K1 Transferable Output as defined above"`

```text
[
    CodecID   <- 0x0000
    TxID      <- 0xf966750f438867c3c9828ddcdbe660e21ccdbb36a9276958f011ba472f75d4e7
    UTXOIndex <- 0x00000000
    AssetID   <- 0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f
    Output    <- 0x000000070000000000003039000000000000d431000000010000000251025c61fbcfc078f69334f834be6dd26d55a955c3344128e060128ede3523a24a461c8943ab0859
]
=
[
    // Codec ID:
    0x00, 0x00,
    // txID:
    0xf9, 0x66, 0x75, 0x0f, 0x43, 0x88, 0x67, 0xc3,
    0xc9, 0x82, 0x8d, 0xdc, 0xdb, 0xe6, 0x60, 0xe2,
    0x1c, 0xcd, 0xbb, 0x36, 0xa9, 0x27, 0x69, 0x58,
    0xf0, 0x11, 0xba, 0x47, 0x2f, 0x75, 0xd4, 0xe7,
    // utxo index:
    0x00, 0x00, 0x00, 0x00,
    // assetID:
    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
    0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
    0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
    0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
    // output:
    0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x30, 0x39, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0xd4, 0x31, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x02, 0x00, 0x01, 0x02, 0x03,
    0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b,
    0x0c, 0x0d, 0x0e, 0x0f, 0x10, 0x11, 0x12, 0x13,
    0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1a, 0x1b,
    0x1c, 0x1d, 0x1e, 0x1f, 0x20, 0x21, 0x22, 0x23,
    0x24, 0x25, 0x26, 0x27,
]
```

## StakeableLockIn

A StakeableLockIn is a staked and locked input. The StakeableLockIn can only
fund StakeableLockOuts with the same address until its lock time has passed.

### What StakeableLockIn Contains

A StakeableLockIn contains a `TypeID`, `Locktime` and `TransferableIn`.

- **`TypeID`** is the ID for this output type. It is `0x00000015`.
- **`Locktime`** is a long that contains the Unix timestamp before which the
  input can be consumed only to stake. The Unix timestamp is specific to the
  second.
- **`TransferableIn`** is a transferable input object.

### Gantt StakeableLockIn Specification

```text
+-----------------+-------------------+--------------------------------+
| type_id         : int               |                        4 bytes |
+-----------------+-------------------+--------------------------------+
| locktime        : long              |                        8 bytes |
+-----------------+-------------------+--------------------------------+
| transferable_in : TransferableInput |          size(transferable_in) |
+-----------------+-------------------+--------------------------------+
                                    | 12 + size(transferable_in) bytes |
                                    +----------------------------------+
```

### Proto StakeableLockIn Specification

```text
message StakeableLockIn {
    uint32 type_id = 1;                    // 04 bytes
    uint64 locktime = 2;                   // 08 bytes
    TransferableInput transferable_in = 3; // size(transferable_in)
}
```

### StakeableLockIn Example

Let's make a StakeableLockIn with:

- **`TypeID`**: 21
- **`Locktime`**: 54321
- **`TransferableIn`**: "Example SECP256K1 Transfer Input as defined above"

```text
[
    TypeID    <- 0x00000015
    Locktime  <- 0x000000000000d431
    TransferableIn <- [
        f1e1d1c1b1a191817161514131211101f0e0d0c0b0a09080706050403020100000000005000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f0000000500000000075bcd150000000100000000,
    ]
]
=
[
    // type_id:
    0x00, 0x00, 0x00, 0x15,
    // locktime:
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xd4, 0x31,
    // transferable_in
    0xf1, 0xe1, 0xd1, 0xc1, 0xb1, 0xa1, 0x91, 0x81,
    0x71, 0x61, 0x51, 0x41, 0x31, 0x21, 0x11, 0x01,
    0xf0, 0xe0, 0xd0, 0xc0, 0xb0, 0xa0, 0x90, 0x80,
    0x70, 0x60, 0x50, 0x40, 0x30, 0x20, 0x10, 0x00,
    0x00, 0x00, 0x00, 0x05,
    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
    0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
    0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
    0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
    0x00, 0x00, 0x00, 0x05, 0x00, 0x00, 0x00, 0x00,
    0x07, 0x5b, 0xcd, 0x15, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x00,
]
```

## StakeableLockOut

A StakeableLockOut is an output that is locked until its lock time, but can be staked in the meantime.

### What StakeableLockOut Contains

A StakeableLockOut contains a `TypeID`, `Locktime` and `TransferableOut`.

- **`TypeID`** is the ID for this output type. It is `0x00000016`.
- **`Locktime`** is a long that contains the Unix timestamp before which the
  output can be consumed only to stake. The Unix timestamp is specific to the
  second.
- **`transferableout`**: "Example SECP256K1 Transfer Output as defined above"

### Gantt StakeableLockOut Specification

```text
+------------------+--------------------+--------------------------------+
| type_id          : int                |                        4 bytes |
+------------------+--------------------+--------------------------------+
| locktime         : long               |                        8 bytes |
+------------------+--------------------+--------------------------------+
| transferable_out : TransferableOutput |         size(transferable_out) |
+------------------+--------------------+--------------------------------+
                                     | 12 + size(transferable_out) bytes |
                                     +-----------------------------------+
```

### Proto StakeableLockOut Specification

```text
message StakeableLockOut {
    uint32 type_id = 1;                      // 04 bytes
    uint64 locktime = 2;                     // 08 bytes
    TransferableOutput transferable_out = 3; // size(transferable_out)
}
```

### StakeableLockOut Example

Let's make a stakeablelockout with:

- **`TypeID`**: 22
- **`Locktime`**: 54321
- **`TransferableOutput`**: `"Example SECP256K1 Transfer Output from above"`

```text
[
    TypeID              <- 0x00000016
    Locktime            <- 0x000000000000d431
    TransferableOutput  <- 0x000000070000000000003039000000000000d431000000010000000251025c61fbcfc078f69334f834be6dd26d55a955c3344128e060128ede3523a24a461c8943ab0859,
]
=
[
    // type_id:
    0x00, 0x00, 0x00, 0x16,
    // locktime:
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xd4, 0x31,
    // transferable_out
    0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x30, 0x39, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0xd4, 0x31, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x02, 0x51, 0x02, 0x5c, 0x61,
    0xfb, 0xcf, 0xc0, 0x78, 0xf6, 0x93, 0x34, 0xf8,
    0x34, 0xbe, 0x6d, 0xd2, 0x6d, 0x55, 0xa9, 0x55,
    0xc3, 0x34, 0x41, 0x28, 0xe0, 0x60, 0x12, 0x8e,
    0xde, 0x35, 0x23, 0xa2, 0x4a, 0x46, 0x1c, 0x89,
    0x43, 0xab, 0x08, 0x59,
]
```

## Avalanche L1 Auth

### What Avalanche L1 Auth Contains

Specifies the addresses whose signatures will be provided to demonstrate that
the owners of an Avalanche L1 approve something.

- **`TypeID`** is the ID for this type. It is `0x0000000a`.
- **`AddressIndices`** defines which addresses' signatures will be attached to
  this transaction. AddressIndices[i] is the index in an Avalanche L1 owner list that
  corresponds to the signature at index i in the signature list. Must be sorted
  low to high and not have duplicates.

### Gantt Avalanche L1 Auth Specification

```text
+-----------------+------------------+-------------------------------------+
| type_id         : int              |                             4 bytes |
+-----------------+------------------+-------------------------------------+
| address_indices : []int            |    4 + 4*len(address_indices) bytes |
+-----------------+------------------+-------------------------------------+
                  |                       8 + 4*len(address_indices) bytes |
+-----------------+--------------------------------------------------------+
```

### Proto Avalanche L1 Auth Specification

```text
message SubnetAuth {
    uint32 type_id = 1;                          // 04 bytes
    repeated AddressIndex address_indices = 2;   // 04 + 4*len(address_indices) bytes
}
```

### Avalanche L1 Auth Example

Let's make an Avalanche L1 auth:

- **`TypeID`**: `10`
- **`AddressIndices`**: [`0`]

```text
[
    TypeID                <- 0x0000000a
    AddressIndices        <-  [
       0x00000000
    ]
]

=
[
  // type id
  0x00, 0x00, 00x0, 0x0a,

  // num address indices
  0x00, 0x00, 0x00, 0x01,

  // address index 1
  0x00, 0x00, 0x00, 0x00
]
```

## Validator

A validator verifies transactions on a blockchain.

### What Validator Contains

A validator contains `NodeID`, `Start`, `End`, and `Wght`

- **`NodeID`** is the ID of the validator
- **`Start`** Unix time this validator starts validating
- **`End`** Unix time this validator stops validating
- **`Wght`** Weight of this validator used when sampling

### Gantt Validator Specification

```text
+------------------+----------+
| node_id : string | 20 bytes |
+------------------+----------+
| start   : uint64 | 8 bytes  |
+------------------+----------+
| end     : uint64 | 8 bytes  |
+------------------+----------+
| wght    : uint64 | 8 bytes  |
+------------------+----------+
|                  | 44 bytes |
+------------------+----------+
```

### Proto Validator Specification

```text
message Validator {
    string node_id = 1;        // 20 bytes
    uint64 start = 2;          // 08 bytes
    uint64 end = 3;            // 08 bytes
    uint64 wght = 4;           // 08 bytes
}
```

### Validator Example

Let's make a validator:

- **`NodeID`**: `"NodeID-GWPcbFJZFfZreETSoWjPimr846mXEKCtu"`
- **`Start`**: `1643068824`
- **`End`**: `1644364767`
- **`Wght`**: `20`

```text
[
    NodeID  <- 0xaa18d3991cf637aa6c162f5e95cf163f69cd8291
    Start   <- 0x61ef3d98
    End     <- 0x620303df
    Wght    <- 0x14
]

=
[
  // node id
  0xaa, 0x18, 0xd3, 0x99, 0x1c, 0xf6, 0x37,
  0xaa, 0x6c, 0x16, 0x2f, 0x5e, 0x95, 0xcf,
  0x16, 0x3f, 0x69, 0xcd, 0x82, 0x91,
  // start
  0x61, 0xef, 0x3d, 0x98,
  // end
  0x62, 0x03, 0x03, 0xdf,
  // wght
  0x14,
]
```

## Rewards Owner

Where to send staking rewards when done validating

### What Rewards Owner Contains

A rewards owner contains a `TypeID`, `Locktime`, `Threshold`, and `Addresses`.

- **`TypeID`** is the ID for this validator. It is `0x0000000b`.
- **`Locktime`** is a long that contains the Unix timestamp that this output can
  be spent after. The Unix timestamp is specific to the second.
- **`Threshold`** is an int that names the number of unique signatures required
  to spend the output. Must be less than or equal to the length of
  **`Addresses`**. If **`Addresses`** is empty, must be 0.
- **`Addresses`** is a list of unique addresses that correspond to the private
  keys that can be used to spend this output. Addresses must be sorted
  lexicographically.

### Gantt Rewards Owner Specification

```text
+------------------------+-------------------------------+
| type_id   : int        | 4 bytes                       |
+------------------------+-------------------------------+
| locktime  : long       | 8 bytes                       |
+------------------------+-------------------------------+
| threshold : int        | 4 bytes                       |
+------------------------+-------------------------------+
| addresses : [][20]byte | 4 + 20 * len(addresses) bytes |
+------------------------+-------------------------------+
|                        | 40 bytes                      |
+------------------------+-------------------------------+
```

### Proto Rewards Owner Specification

```text
message RewardsOwner {
    string type_id = 1;           // 4 bytes
    uint64 locktime = 2;          // 08 bytes
    uint32 threshold = 3;         // 04 bytes
    repeated bytes addresses = 4; // 04 bytes + 20 bytes * len(addresses)
}
```

### Rewards Owner Example

Let's make a rewards owner:

- **`TypeID`**: `11`
- **`Locktime`**: `54321`
- **`Threshold`**: `1`
- **`Addresses`**:
- `0x51025c61fbcfc078f69334f834be6dd26d55a955`
- `0xc3344128e060128ede3523a24a461c8943ab0859`

```text
[
    TypeID  <- 0x0000000b
    Locktime  <- 0x000000000000d431
    Threshold <- 0x00000001
    Addresses <- [
        0x51025c61fbcfc078f69334f834be6dd26d55a955,
        0xc3344128e060128ede3523a24a461c8943ab0859,
    ]
]

=
[
  // type id
  0x00, 0x00, 0x00, 0x0b,
  // locktime
  0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xd4, 0x31,
  // threshold:
  0x00, 0x00, 0x00, 0x01,
  // number of addresses:
  0x00, 0x00, 0x00, 0x02,
  // addrs[0]:
  0x51, 0x02, 0x5c, 0x61, 0xfb, 0xcf, 0xc0, 0x78,
  0xf6, 0x93, 0x34, 0xf8, 0x34, 0xbe, 0x6d, 0xd2,
  0x6d, 0x55, 0xa9, 0x55,
  // addrs[1]:
  0xc3, 0x34, 0x41, 0x28, 0xe0, 0x60, 0x12, 0x8e,
  0xde, 0x35, 0x23, 0xa2, 0x4a, 0x46, 0x1c, 0x89,
  0x43, 0xab, 0x08, 0x59,
]
```

## Unsigned Convert Subnet To L1 TX

### What Unsigned Convert Subnet To L1 TX Contains

An unsigned convert subnet to L1 TX contains a `BaseTx`, `Subnet`, `ChainID`, `Address`, `Validators`, and `SubnetAuth`. The `TypeID` for this type is `0x00000030`.

- **`BaseTx`**
- **`Subnet`** ID of the Subnet to transform into an L1. Must not be the Primary Network ID.
- **`ChainID`** BlockchainID where the validator manager lives.
- **`Address`** Address of the validator manager.
- **`Validators`** Initial continuous-fee-paying validators for the L1.
- **`SubnetAuth`** Authorizes this conversion. Must be signed by the Subnet's owner.

### Gantt Unsigned Convert Subnet To L1 TX Specification

```text
+------------+------------------+----------------------------------+
| base_tx    : BaseTx           |              size(base_tx) bytes |
+------------+------------------+----------------------------------+
| subnet     : [32]byte         |                         32 bytes |
+------------+------------------+----------------------------------+
| chain_id   : [32]byte         |                         32 bytes |
+------------+------------------+----------------------------------+
| address    : []byte           |             4 + len(address) bytes |
+------------+------------------+----------------------------------+
| validators : []L1Validator    |         4 + size(validators) bytes |
+------------+------------------+----------------------------------+
| subnet_auth: SubnetAuth       | 4 bytes + len(sig_indices) bytes |
+------------+------------------+----------------------------------+
| 76 + size(base_tx) + len(address) + size(validators) + len(sig_indices) bytes |
+----------------------------------------------------------------------------+
```

### Proto Unsigned Convert Subnet To L1 TX Specification

```text
message ConvertSubnetToL1Tx {
    BaseTx base_tx = 1;              // size(base_tx)
    SubnetID subnet = 2;             // 32 bytes
    ChainID chain_id = 3;            // 32 bytes
    bytes address = 4;               // 4 + len(address) bytes
    repeated L1Validator validators = 5; // 4 + size(validators) bytes
    SubnetAuth subnet_auth = 6;      // 4 bytes + len(sig_indices)
}
```

## Unsigned Register L1 Validator TX

### What Unsigned Register L1 Validator TX Contains

An unsigned register L1 validator TX contains a `BaseTx`, `Balance`, `Signer` and `Message`. The `TypeID` for this type is `0x00000031`.

- **`BaseTx`**
- **`Balance`** is the amount of AVAX being provided for fees, where `Balance <= sum($AVAX inputs) - sum($AVAX outputs) - TxFee`.
- **`Signer`** is a BLS signature proving ownership of the BLS public key specified in the Message for this validator.
- **`Message`** is a RegisterL1ValidatorMessage payload delivered as a Warp Message.

### Gantt Unsigned Register L1 Validator TX Specification

```text
+------------+------------------+----------------------------------+
| base_tx    : BaseTx           |              size(base_tx) bytes |
+------------+------------------+----------------------------------+
| balance    : uint64           |                          8 bytes |
+------------+------------------+----------------------------------+
| signer     : [96]byte         |                         96 bytes |
+------------+------------------+----------------------------------+
| message    : WarpMessage      |             size(message) bytes |
+------------+------------------+----------------------------------+
| 104 + size(base_tx) + size(message) bytes                       |
+------------------------------------------------------------------+
```

### Proto Unsigned Register L1 Validator TX Specification

```text
message RegisterL1ValidatorTx {
    BaseTx base_tx = 1;        // size(base_tx)
    uint64 balance = 2;        // 8 bytes
    bytes signer = 3;          // 96 bytes
    WarpMessage message = 4;   // size(message) bytes
}
```

## Unsigned Set L1 Validator Weight TX

### What Unsigned Set L1 Validator Weight TX Contains

An unsigned set L1 validator weight TX contains a `BaseTx` and `Message`. The `TypeID` for this type is `0x00000032`.

- **`BaseTx`**
- **`Message`** An L1ValidatorWeightMessage payload delivered as a Warp Message. Contains the validationID, nonce, and new weight for a validator.

### Gantt Unsigned Set L1 Validator Weight TX Specification

```text
+------------+------------------+----------------------------------+
| base_tx    : BaseTx           |              size(base_tx) bytes |
+------------+------------------+----------------------------------+
| message    : WarpMessage      |             size(message) bytes |
+------------+------------------+----------------------------------+
| size(base_tx) + size(message) bytes                             |
+------------------------------------------------------------------+
```

### Proto Unsigned Set L1 Validator Weight TX Specification

```text
message SetL1ValidatorWeightTx {
    BaseTx base_tx = 1;        // size(base_tx)
    WarpMessage message = 2;   // size(message) bytes
}
```

## Unsigned Disable L1 Validator TX

### What Unsigned Disable L1 Validator TX Contains

An unsigned disable L1 validator TX contains a `BaseTx`, `ValidationID` and `DisableAuth`. The `TypeID` for this type is `0x00000033`.

- **`BaseTx`**
- **`ValidationID`** ID corresponding to the validator to be disabled.
- **`DisableAuth`** Authorizes this validator to be disabled. Must be signed by the DisableOwner specified when the validator was added.

### Gantt Unsigned Disable L1 Validator TX Specification

```text
+----------------+------------------+----------------------------------+
| base_tx        : BaseTx           |              size(base_tx) bytes |
+----------------+------------------+----------------------------------+
| validation_id  : [32]byte         |                         32 bytes |
+----------------+------------------+----------------------------------+
| disable_auth   : Verifiable       |        size(disable_auth) bytes  |
+----------------+------------------+----------------------------------+
| 32 + size(base_tx) + size(disable_auth) bytes                       |
+----------------------------------------------------------------------+
```

### Proto Unsigned Disable L1 Validator TX Specification

```text
message DisableL1ValidatorTx {
    BaseTx base_tx = 1;            // size(base_tx)
    bytes validation_id = 2;       // 32 bytes
    Verifiable disable_auth = 3;   // size(disable_auth) bytes
}
```

## Unsigned Increase L1 Validator Balance TX

### What Unsigned Increase L1 Validator Balance TX Contains

An unsigned increase L1 validator balance TX contains a `BaseTx`, `ValidationID` and `Balance`. The `TypeID` for this type is `0x00000034`.

- **`BaseTx`**
- **`ValidationID`** ID corresponding to the validator.
- **`Balance`** Additional AVAX amount to add to the validator's balance where `Balance <= sum($AVAX inputs) - sum($AVAX outputs) - TxFee`.

### Gantt Unsigned Increase L1 Validator Balance TX Specification

```text
+----------------+------------------+----------------------------------+
| base_tx        : BaseTx           |              size(base_tx) bytes |
+----------------+------------------+----------------------------------+
| validation_id  : [32]byte         |                         32 bytes |
+----------------+------------------+----------------------------------+
| balance        : uint64           |                          8 bytes |
+----------------+------------------+----------------------------------+
| 40 + size(base_tx) bytes                                            |
+----------------------------------------------------------------------+
```

### Proto Unsigned Increase L1 Validator Balance TX Specification

```text
message IncreaseL1ValidatorBalanceTx {
    BaseTx base_tx = 1;       // size(base_tx)
    bytes validation_id = 2;  // 32 bytes
    uint64 balance = 3;       // 8 bytes
}
```

# Subnet-EVM RPC (/docs/rpcs/subnet-evm)

---
title: "Subnet-EVM RPC"
description: "This page describes the RPC endpoints available for Subnet-EVM based blockchains."
edit_url: https://github.com/ava-labs/subnet-evm/edit/master/plugin/evm/service.md
---

[Subnet-EVM](https://github.com/ava-labs/subnet-evm) APIs are identical to
[Coreth](https://build.avax.network/docs/api-reference/c-chain/api) C-Chain APIs, except Avalanche Specific APIs
starting with `avax`. Subnet-EVM also supports standard Ethereum APIs as well. For more
information about Coreth APIs see [GitHub](https://github.com/ava-labs/coreth).

Subnet-EVM has some additional APIs that are not available in Coreth.

## `eth_feeConfig`

Subnet-EVM comes with an API request for getting fee config at a specific block. You can use this
API to check your activated fee config.

**Signature:**

```bash
eth_feeConfig([blk BlkNrOrHash]) -> {feeConfig: json}
```

- `blk` is the block number or hash at which to retrieve the fee config. Defaults to the latest block if omitted.

**Example Call:**

```bash
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "eth_feeConfig",
    "params": [
        "latest"
    ],
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/2ebCneCbwthjQ1rYT41nhd7M76Hc6YmosMAQrTFhBq8qeqh6tt/rpc
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "feeConfig": {
      "gasLimit": 15000000,
      "targetBlockRate": 2,
      "minBaseFee": 33000000000,
      "targetGas": 15000000,
      "baseFeeChangeDenominator": 36,
      "minBlockGasCost": 0,
      "maxBlockGasCost": 1000000,
      "blockGasCostStep": 200000
    },
    "lastChangedAt": 0
  }
}
```

## `eth_getChainConfig`

`eth_getChainConfig` returns the Chain Config of the blockchain. This API is enabled by default with
`internal-blockchain` namespace.

This API exists on the C-Chain as well, but in addition to the normal Chain Config returned by the
C-Chain `eth_getChainConfig` on `subnet-evm` additionally returns the upgrade config, which specifies
network upgrades activated after the genesis. **Signature:**

```bash
eth_getChainConfig({}) -> {chainConfig: json}
```

**Example Call:**

```bash
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"eth_getChainConfig",
    "params" :[]
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/Nvqcm33CX2XABS62iZsAcVUkavfnzp1Sc5k413wn5Nrf7Qjt7/rpc
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "chainId": 43214,
    "feeConfig": {
      "gasLimit": 8000000,
      "targetBlockRate": 2,
      "minBaseFee": 33000000000,
      "targetGas": 15000000,
      "baseFeeChangeDenominator": 36,
      "minBlockGasCost": 0,
      "maxBlockGasCost": 1000000,
      "blockGasCostStep": 200000
    },
    "allowFeeRecipients": true,
    "homesteadBlock": 0,
    "eip150Block": 0,
    "eip150Hash": "0x2086799aeebeae135c246c65021c82b4e15a2c451340993aacfd2751886514f0",
    "eip155Block": 0,
    "eip158Block": 0,
    "byzantiumBlock": 0,
    "constantinopleBlock": 0,
    "petersburgBlock": 0,
    "istanbulBlock": 0,
    "muirGlacierBlock": 0,
    "subnetEVMTimestamp": 0,
    "contractDeployerAllowListConfig": {
      "adminAddresses": ["0x8db97c7cece249c2b98bdc0226cc4c2a57bf52fc"],
      "blockTimestamp": 0
    },
    "contractNativeMinterConfig": {
      "adminAddresses": ["0x8db97c7cece249c2b98bdc0226cc4c2a57bf52fc"],
      "blockTimestamp": 0
    },
    "feeManagerConfig": {
      "adminAddresses": ["0x8db97c7cece249c2b98bdc0226cc4c2a57bf52fc"],
      "blockTimestamp": 0
    },
    "upgrades": {
      "precompileUpgrades": [
        {
          "feeManagerConfig": {
            "adminAddresses": null,
            "blockTimestamp": 1661541259,
            "disable": true
          }
        },
        {
          "feeManagerConfig": {
            "adminAddresses": null,
            "blockTimestamp": 1661541269
          }
        }
      ]
    }
  }
}
```

## `eth_getActivePrecompilesAt`

**DEPRECATED—instead use** [`eth_getActiveRulesAt`](#eth_getactiveprecompilesat).

`eth_getActivePrecompilesAt` returns activated precompiles at a specific timestamp. If no
timestamp is provided it returns the latest block timestamp. This API is enabled by default with
`internal-blockchain` namespace.

**Signature:**

```bash
eth_getActivePrecompilesAt([timestamp uint]) -> {precompiles: []Precompile}
```

- `timestamp` specifies the timestamp to show the precompiles active at this time. If omitted it shows precompiles activated at the latest block timestamp.

**Example Call:**

```bash
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "eth_getActivePrecompilesAt",
    "params": [],
    "id": 1
}'  -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/Nvqcm33CX2XABS62iZsAcVUkavfnzp1Sc5k413wn5Nrf7Qjt7/rpc
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "contractDeployerAllowListConfig": {
      "adminAddresses": ["0x8db97c7cece249c2b98bdc0226cc4c2a57bf52fc"],
      "blockTimestamp": 0
    },
    "contractNativeMinterConfig": {
      "adminAddresses": ["0x8db97c7cece249c2b98bdc0226cc4c2a57bf52fc"],
      "blockTimestamp": 0
    },
    "feeManagerConfig": {
      "adminAddresses": ["0x8db97c7cece249c2b98bdc0226cc4c2a57bf52fc"],
      "blockTimestamp": 0
    }
  }
}
```

## `eth_getActiveRulesAt`

`eth_getActiveRulesAt` returns activated rules (precompiles, upgrades) at a specific timestamp. If no
timestamp is provided it returns the latest block timestamp. This API is enabled by default with
`internal-blockchain` namespace.

**Signature:**

```bash
eth_getActiveRulesAt([timestamp uint]) -> {rules: json}
```

- `timestamp` specifies the timestamp to show the rules active at this time. If omitted it shows rules activated at the latest block timestamp.

**Example Call:**

```bash
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "eth_getActiveRulesAt",
    "params": [],
    "id": 1
}'  -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/Nvqcm33CX2XABS62iZsAcVUkavfnzp1Sc5k413wn5Nrf7Qjt7/rpc
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "ethRules": {
      "IsHomestead": true,
      "IsEIP150": true,
      "IsEIP155": true,
      "IsEIP158": true,
      "IsByzantium": true,
      "IsConstantinople": true,
      "IsPetersburg": true,
      "IsIstanbul": true,
      "IsCancun": true
    },
    "avalancheRules": {
      "IsSubnetEVM": true,
      "IsDurango": true,
      "IsEtna": true
    },
    "precompiles": {
      "contractNativeMinterConfig": {
        "timestamp": 0
      },
      "rewardManagerConfig": {
        "timestamp": 1712918700
      },
      "warpConfig": {
        "timestamp": 1714158045
      }
    }
  }
}
```

## `validators.getCurrentValidators`

This API retrieves the list of current validators for the Subnet/L1. It provides detailed information about each validator, including their ID, status, weight, connection, and uptime.

URL: `http://<server-uri>/ext/bc/<blockchainID>/validators`

**Signature:**

```bash
validators.getCurrentValidators({nodeIDs: []string}) -> {validators: []Validator}
```

- `nodeIDs` is an optional parameter that specifies the node IDs of the validators to retrieve. If omitted, all validators are returned.

**Example Call:**

```bash
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "validators.getCurrentValidators",
    "params": {
        "nodeIDs": []
    },
    "id": 1
}'  -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/C49rHzk3vLr1w9Z8sY7scrZ69TU4WcD2pRS6ZyzaSn9xA2U9F/validators
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "validators": [
      {
        "validationID": "nESqWkcNXihfdZESS2idWbFETMzatmkoTCktjxG1qryaQXfS6",
        "nodeID": "NodeID-P7oB2McjBGgW2NXXWVYjV8JEDFoW9xDE5",
        "weight": 20,
        "startTimestamp": 1732025492,
        "isActive": true,
        "isL1Validator": false,
        "isConnected": true,
        "uptimeSeconds": 36,
        "uptimePercentage": 100
      }
    ]
  },
  "id": 1
}
```

**Response Fields:**

- `validationID`: (string) Unique identifier for the validation. This returns validation ID for L1s, AddSubnetValidator txID for Subnets.
- `nodeID`: (string) Node identifier for the validator.
- `weight`: (integer) The weight of the validator, often representing stake.
- `startTimestamp`: (integer) UNIX timestamp for when validation started.
- `isActive`: (boolean) Indicates if the validator is active. This returns true if this is L1 validator and has enough continuous subnet staking fees in P-Chain. It always returns true for subnet validators.
- `isL1Validator`: (boolean) Indicates if the validator is a L1 validator or a subnet validator.
- `isConnected`: (boolean) Indicates if the validator node is currently connected to the callee node.
- `uptimeSeconds`: (integer) The number of seconds the validator has been online.
- `uptimePercentage`: (float) The percentage of time the validator has been online.

# X-Chain API (/docs/rpcs/x-chain/api)

---
title: "X-Chain API"
description: "This page is an overview of the X-Chain API associated with AvalancheGo."
edit_url: https://github.com/ava-labs/avalanchego/edit/master/vms/avm/service.md
---

The [X-Chain](https://build.avax.network/docs/quick-start/primary-network#x-chain),
Avalanche's native platform for creating and trading assets, is an instance of the Avalanche Virtual
Machine (AVM). This API allows clients to create and trade assets on the X-Chain and other instances
of the AVM.

## Format

This API uses the `json 2.0` RPC format. For more information on making JSON RPC calls, see
[here](https://build.avax.network/docs/api-reference/guides/issuing-api-calls).

## Endpoints

`/ext/bc/X` to interact with the X-Chain.

`/ext/bc/blockchainID` to interact with other AVM instances, where `blockchainID` is the ID of a
blockchain running the AVM.

## Methods

### `avm.getAllBalances`

<Callout type="warn">
Deprecated as of [**v1.9.12**](https://github.com/ava-labs/avalanchego/releases/tag/v1.9.12).
</Callout>

Get the balances of all assets controlled by a given address.

**Signature:**

```sh
avm.getAllBalances({address:string}) -> {
    balances: []{
        asset: string,
        balance: int
    }
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     : 1,
    "method" :"avm.getAllBalances",
    "params" :{
        "address":"X-avax1c79e0dd0susp7dc8udq34jgk2yvve7hapvdyht"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "balances": [
      {
        "asset": "AVAX",
        "balance": "102"
      },
      {
        "asset": "2sdnziCz37Jov3QSNMXcFRGFJ1tgauaj6L7qfk7yUcRPfQMC79",
        "balance": "10000"
      }
    ]
  },
  "id": 1
}
```

### `avm.getAssetDescription`

Get information about an asset.

**Signature:**

```sh
avm.getAssetDescription({assetID: string}) -> {
    assetId: string,
    name: string,
    symbol: string,
    denomination: int
}
```

- `assetID` is the id of the asset for which the information is requested.
- `name` is the asset’s human-readable, not necessarily unique name.
- `symbol` is the asset’s symbol.
- `denomination` determines how balances of this asset are displayed by user interfaces. If
  denomination is 0, 100 units of this asset are displayed as 100. If denomination is 1, 100 units
  of this asset are displayed as 10.0. If denomination is 2, 100 units of this asset are displays as
  .100, etc.

<Callout type="note">
The AssetID for AVAX differs depending on the network you are on.

Mainnet: FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z

Testnet: U8iRqJoiJm8xZHAacmvYyZVwqQx6uDNtQeP3CQ6fcgQk3JqnK

For finding the `assetID` of other assets, this [info] might be useful.
Also, `avm.getUTXOs` returns the `assetID` in its output.
</Callout>

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"avm.getAssetDescription",
    "params" :{
        "assetID" :"FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
    "jsonrpc": "2.0",
    "result": {
        "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z",
        "name": "Avalanche",
        "symbol": "AVAX",
        "denomination": "9"
    },
    "id": 1
}`
```

### `avm.getBalance`

<Callout type="warn">
Deprecated as of [**v1.9.12**](https://github.com/ava-labs/avalanchego/releases/tag/v1.9.12).
</Callout>

Get the balance of an asset controlled by a given address.

**Signature:**

```sh
avm.getBalance({
    address: string,
    assetID: string
}) -> {balance: int}
```

- `address` owner of the asset
- `assetID` id of the asset for which the balance is requested

**Example Call:**

```sh
curl -X POST --data '{
  "jsonrpc":"2.0",
  "id"     : 1,
  "method" :"avm.getBalance",
  "params" :{
      "address":"X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5",
      "assetID": "2pYGetDWyKdHxpFxh2LHeoLNCH6H5vxxCxHQtFnnFaYxLsqtHC"
  }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "balance": "299999999999900",
    "utxoIDs": [
      {
        "txID": "WPQdyLNqHfiEKp4zcCpayRHYDVYuh1hqs9c1RqgZXS4VPgdvo",
        "outputIndex": 1
      }
    ]
  }
}
```

### `avm.getBlock`

Returns the block with the given id.

**Signature:**

```sh
avm.getBlock({
    blockID: string
    encoding: string // optional
}) -> {
    block: string,
    encoding: string
}
```

**Request:**

- `blockID` is the block ID. It should be in cb58 format.
- `encoding` is the encoding format to use. Can be either `hex` or `json`. Defaults to `hex`.

**Response:**

- `block` is the transaction encoded to `encoding`.
- `encoding` is the `encoding`.

#### Hex Example

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "avm.getBlock",
    "params": {
        "blockID": "tXJ4xwmR8soHE6DzRNMQPtiwQvuYsHn6eLLBzo2moDqBquqy6",
        "encoding": "hex"
    },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "block": "0x00000000002000000000641ad33ede17f652512193721df87994f783ec806bb5640c39ee73676caffcc3215e0651000000000049a80a000000010000000e0000000100000000000000000000000000000000000000000000000000000000000000000000000121e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff000000070000002e1a2a3910000000000000000000000001000000015cf998275803a7277926912defdf177b2e97b0b400000001e0d825c5069a7336671dd27eaa5c7851d2cf449e7e1cdc469c5c9e5a953955950000000021e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff000000050000008908223b680000000100000000000000005e45d02fcc9e585544008f1df7ae5c94bf7f0f2600000000641ad3b600000000642d48b60000005aedf802580000000121e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff000000070000005aedf80258000000000000000000000001000000015cf998275803a7277926912defdf177b2e97b0b40000000b000000000000000000000001000000012892441ba9a160bcdc596dcd2cc3ad83c3493589000000010000000900000001adf2237a5fe2dfd906265e8e14274aa7a7b2ee60c66213110598ba34fb4824d74f7760321c0c8fb1e8d3c5e86909248e48a7ae02e641da5559351693a8a1939800286d4fa2",
    "encoding": "hex"
  },
  "id": 1
}
```

### `avm.getBlockByHeight`

Returns block at the given height.

**Signature:**

```sh
avm.getBlockByHeight({
    height: string
    encoding: string // optional
}) -> {
    block: string,
    encoding: string
}
```

**Request:**

- `blockHeight` is the block height. It should be in `string` format.
- `encoding` is the encoding format to use. Can be either `hex` or `json`. Defaults to `hex`.

**Response:**

- `block` is the transaction encoded to `encoding`.
- `encoding` is the `encoding`.

#### Hex Example

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "avm.getBlockByHeight",
    "params": {
        "height": "275686313486",
        "encoding": "hex"
    },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "block": "0x00000000002000000000642f6739d4efcdd07e4d4919a7fc2020b8a0f081dd64c262aaace5a6dad22be0b55fec0700000000004db9e100000001000000110000000100000000000000000000000000000000000000000000000000000000000000000000000121e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff000000070000005c6ece390000000000000000000000000100000001930ab7bf5018bfc6f9435c8b15ba2fe1e619c0230000000000000000ed5f38341e436e5d46e2bb00b45d62ae97d1b050c64bc634ae10626739e35c4b00000001c6dda861341665c3b555b46227fb5e56dc0a870c5482809349f04b00348af2a80000000021e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff000000050000005c6edd7b40000000010000000000000001000000090000000178688f4d5055bd8733801f9b52793da885bef424c90526c18e4dd97f7514bf6f0c3d2a0e9a5ea8b761bc41902eb4902c34ef034c4d18c3db7c83c64ffeadd93600731676de",
    "encoding": "hex"
  },
  "id": 1
}
```

### `avm.getHeight`

Returns the height of the last accepted block.

**Signature:**

```sh
avm.getHeight() ->
{
    height: uint64,
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "avm.getHeight",
    "params": {},
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "height": "5094088"
  },
  "id": 1
}
```

### `avm.getTx`

Returns the specified transaction. The `encoding` parameter sets the format of the returned
transaction. Can be either `"hex"` or `"json"`. Defaults to `"hex"`.

**Signature:**

```sh
avm.getTx({
    txID: string,
    encoding: string, //optional
}) -> {
    tx: string,
    encoding: string,
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"avm.getTx",
    "params" :{
        "txID":"2oJCbb8pfdxEHAf9A8CdN4Afj9VSR3xzyzNkf8tDv7aM1sfNFL",
        "encoding": "json"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "tx": {
      "unsignedTx": {
        "networkID": 1,
        "blockchainID": "2oYMBNV4eNHyqk2fjjV5nVQLDbtmNJzq5s3qs3Lo6ftnC6FByM",
        "outputs": [],
        "inputs": [
          {
            "txID": "2jbZUvi6nHy3Pgmk8xcMpSg5cW6epkPqdKkHSCweb4eRXtq4k9",
            "outputIndex": 1,
            "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z",
            "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ",
            "input": {
              "amount": 2570382395,
              "signatureIndices": [0]
            }
          }
        ],
        "memo": "0x",
        "destinationChain": "11111111111111111111111111111111LpoYY",
        "exportedOutputs": [
          {
            "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z",
            "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ",
            "output": {
              "addresses": ["X-avax1tnuesf6cqwnjw7fxjyk7lhch0vhf0v95wj5jvy"],
              "amount": 2569382395,
              "locktime": 0,
              "threshold": 1
            }
          }
        ]
      },
      "credentials": [
        {
          "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ",
          "credential": {
            "signatures": [
              "0x46ebcbcfbee3ece1fd15015204045cf3cb77f42c48d0201fc150341f91f086f177cfca8894ca9b4a0c55d6950218e4ea8c01d5c4aefb85cd7264b47bd57d224400"
            ]
          }
        }
      ],
      "id": "2oJCbb8pfdxEHAf9A8CdN4Afj9VSR3xzyzNkf8tDv7aM1sfNFL"
    },
    "encoding": "json"
  },
  "id": 1
}
```

Where:

- `credentials` is a list of this transaction's credentials. Each credential proves that this
  transaction's creator is allowed to consume one of this transaction's inputs. Each credential is a
  list of signatures.
- `unsignedTx` is the non-signature portion of the transaction.
- `networkID` is the ID of the network this transaction happened on. (Avalanche Mainnet is `1`.)
- `blockchainID` is the ID of the blockchain this transaction happened on. (Avalanche Mainnet
  X-Chain is `2oYMBNV4eNHyqk2fjjV5nVQLDbtmNJzq5s3qs3Lo6ftnC6FByM`.)
- Each element of `outputs` is an output (UTXO) of this transaction that is not being exported to
  another chain.
- Each element of `inputs` is an input of this transaction which has not been imported from another
  chain.
- Import Transactions have additional fields `sourceChain` and `importedInputs`, which specify the
  blockchain ID that assets are being imported from, and the inputs that are being imported.
- Export Transactions have additional fields `destinationChain` and `exportedOutputs`, which specify
  the blockchain ID that assets are being exported to, and the UTXOs that are being exported.

An output contains:

- `assetID`: The ID of the asset being transferred. (The Mainnet Avax ID is
  `FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z`.)
- `fxID`: The ID of the FX this output uses.
- `output`: The FX-specific contents of this output.

Most outputs use the secp256k1 FX, look like this:

```json
{
  "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z",
  "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ",
  "output": {
    "addresses": ["X-avax126rd3w35xwkmj8670zvf7y5r8k36qa9z9803wm"],
    "amount": 1530084210,
    "locktime": 0,
    "threshold": 1
  }
}
```

The above output can be consumed after Unix time `locktime` by a transaction that has signatures
from `threshold` of the addresses in `addresses`.

### `avm.getTxFee`

Get the fees of the network.

**Signature**:

```
avm.getTxFee() ->
{
  txFee: uint64,
  createAssetTxFee: uint64,
}
```

- `txFee` is the default fee for making transactions.
- `createAssetTxFee` is the fee for creating a new asset.

All fees are denominated in nAVAX.

**Example Call**:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     : 1,
    "method" :"avm.getTxFee",
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response**:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "txFee": "1000000",
    "createAssetTxFee": "10000000"
  }
}
```

### `avm.getTxStatus`

<Callout type="warn">
Deprecated as of **v1.10.0**.
</Callout>

Get the status of a transaction sent to the network.

**Signature:**

```sh
avm.getTxStatus({txID: string}) -> {status: string}
```

`status` is one of:

- `Accepted`: The transaction is (or will be) accepted by every node
- `Processing`: The transaction is being voted on by this node
- `Rejected`: The transaction will never be accepted by any node in the network
- `Unknown`: The transaction hasn’t been seen by this node

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"avm.getTxStatus",
    "params" :{
        "txID":"2QouvFWUbjuySRxeX5xMbNCuAaKWfbk5FeEa2JmoF85RKLk2dD"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "status": "Accepted"
  }
}
```

### `avm.getUTXOs`

Gets the UTXOs that reference a given address. If `sourceChain` is specified, then it will retrieve
the atomic UTXOs exported from that chain to the X Chain.

**Signature:**

```sh
avm.getUTXOs({
    addresses: []string,
    limit: int, //optional
    startIndex: { //optional
        address: string,
        utxo: string
    },
    sourceChain: string, //optional
    encoding: string //optional
}) -> {
    numFetched: int,
    utxos: []string,
    endIndex: {
        address: string,
        utxo: string
    },
    sourceChain: string, //optional
    encoding: string
}
```

- `utxos` is a list of UTXOs such that each UTXO references at least one address in `addresses`.
- At most `limit` UTXOs are returned. If `limit` is omitted or greater than 1024, it is set to 1024.
- This method supports pagination. `endIndex` denotes the last UTXO returned. To get the next set of
  UTXOs, use the value of `endIndex` as `startIndex` in the next call.
- If `startIndex` is omitted, will fetch all UTXOs up to `limit`.
- When using pagination (when `startIndex` is provided), UTXOs are not guaranteed to be unique
  across multiple calls. That is, a UTXO may appear in the result of the first call, and then again
  in the second call.
- When using pagination, consistency is not guaranteed across multiple calls. That is, the UTXO set
  of the addresses may have changed between calls.
- `encoding` sets the format for the returned UTXOs. Can only be `hex` when a value is provided.

#### **Example**

Suppose we want all UTXOs that reference at least one of
`X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5` and `X-avax1d09qn852zcy03sfc9hay2llmn9hsgnw4tp3dv6`.

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"avm.getUTXOs",
    "params" :{
        "addresses":["X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5", "X-avax1d09qn852zcy03sfc9hay2llmn9hsgnw4tp3dv6"],
        "limit":5,
        "encoding": "hex"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

This gives response:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "numFetched": "5",
    "utxos": [
      "0x0000a195046108a85e60f7a864bb567745a37f50c6af282103e47cc62f036cee404700000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216c1f01765",
      "0x0000ae8b1b94444eed8de9a81b1222f00f1b4133330add23d8ac288bffa98b85271100000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216473d042a",
      "0x0000731ce04b1feefa9f4291d869adc30a33463f315491e164d89be7d6d2d7890cfc00000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f21600dd3047",
      "0x0000b462030cc4734f24c0bc224cf0d16ee452ea6b67615517caffead123ab4fbf1500000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216c71b387e",
      "0x000054f6826c39bc957c0c6d44b70f961a994898999179cc32d21eb09c1908d7167b00000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f2166290e79d"
    ],
    "endIndex": {
      "address": "X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5",
      "utxo": "kbUThAUfmBXUmRgTpgD6r3nLj7rJUGho6xyht5nouNNypH45j"
    },
    "encoding": "hex"
  },
  "id": 1
}
```

Since `numFetched` is the same as `limit`, we can tell that there may be more UTXOs that were not
fetched. We call the method again, this time with `startIndex`:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :2,
    "method" :"avm.getUTXOs",
    "params" :{
        "addresses":["X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5"],
        "limit":5,
        "startIndex": {
            "address": "X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5",
            "utxo": "kbUThAUfmBXUmRgTpgD6r3nLj7rJUGho6xyht5nouNNypH45j"
        },
        "encoding": "hex"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

This gives response:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "numFetched": "4",
    "utxos": [
      "0x000020e182dd51ee4dcd31909fddd75bb3438d9431f8e4efce86a88a684f5c7fa09300000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f21662861d59",
      "0x0000a71ba36c475c18eb65dc90f6e85c4fd4a462d51c5de3ac2cbddf47db4d99284e00000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f21665f6f83f",
      "0x0000925424f61cb13e0fbdecc66e1270de68de9667b85baa3fdc84741d048daa69fa00000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216afecf76a",
      "0x000082f30327514f819da6009fad92b5dba24d27db01e29ad7541aa8e6b6b554615c00000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216779c2d59"
    ],
    "endIndex": {
      "address": "X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5",
      "utxo": "21jG2RfqyHUUgkTLe2tUp6ETGLriSDTW3th8JXFbPRNiSZ11jK"
    },
    "encoding": "hex"
  },
  "id": 1
}
```

Since `numFetched` is less than `limit`, we know that we are done fetching UTXOs and don’t need to
call this method again.

Suppose we want to fetch the UTXOs exported from the P Chain to the X Chain in order to build an
ImportTx. Then we need to call GetUTXOs with the `sourceChain` argument in order to retrieve the
atomic UTXOs:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"avm.getUTXOs",
    "params" :{
        "addresses":["X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5", "X-avax1d09qn852zcy03sfc9hay2llmn9hsgnw4tp3dv6"],
        "limit":5,
        "sourceChain": "P",
        "encoding": "hex"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

This gives response:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "numFetched": "1",
    "utxos": [
      "0x00001f989ffaf18a18a59bdfbf209342aa61c6a62a67e8639d02bb3c8ddab315c6fa0000000039c33a499ce4c33a3b09cdd2cfa01ae70dbf2d18b2d7d168524440e55d550088000000070011c304cd7eb5c0000000000000000000000001000000013cb7d3842e8cee6a0ebd09f1fe884f6861e1b29c83497819"
    ],
    "endIndex": {
      "address": "X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5",
      "utxo": "2Sz2XwRYqUHwPeiKoRnZ6ht88YqzAF1SQjMYZQQaB5wBFkAqST"
    },
    "encoding": "hex"
  },
  "id": 1
}
```

### `avm.issueTx`

Send a signed transaction to the network. `encoding` specifies the format of the signed transaction.
Can only be `hex` when a value is provided.

**Signature:**

```sh
avm.issueTx({
    tx: string,
    encoding: string, //optional
}) -> {
    txID: string
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     : 1,
    "method" :"avm.issueTx",
    "params" :{
        "tx":"0x00000009de31b4d8b22991d51aa6aa1fc733f23a851a8c9400000000000186a0000000005f041280000000005f9ca900000030390000000000000001fceda8f90fcb5d30614b99d79fc4baa29307762668f16eb0259a57c2d3b78c875c86ec2045792d4df2d926c40f829196e0bb97ee697af71f5b0a966dabff749634c8b729855e937715b0e44303fd1014daedc752006011b730",
        "encoding": "hex"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "txID": "NUPLwbt2hsYxpQg4H2o451hmTWQ4JZx2zMzM4SinwtHgAdX1JLPHXvWSXEnpecStLj"
  }
}
```

### `wallet.issueTx`

Send a signed transaction to the network and assume the TX will be accepted. `encoding` specifies
the format of the signed transaction. Can only be `hex` when a value is provided.

This call is made to the wallet API endpoint:

`/ext/bc/X/wallet`

:::caution
Endpoint deprecated as of [**v1.9.12**](https://github.com/ava-labs/avalanchego/releases/tag/v1.9.12).

:::

**Signature:**

```sh
wallet.issueTx({
    tx: string,
    encoding: string, //optional
}) -> {
    txID: string
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     : 1,
    "method" :"wallet.issueTx",
    "params" :{
        "tx":"0x00000009de31b4d8b22991d51aa6aa1fc733f23a851a8c9400000000000186a0000000005f041280000000005f9ca900000030390000000000000001fceda8f90fcb5d30614b99d79fc4baa29307762668f16eb0259a57c2d3b78c875c86ec2045792d4df2d926c40f829196e0bb97ee697af71f5b0a966dabff749634c8b729855e937715b0e44303fd1014daedc752006011b730",
        "encoding": "hex"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X/wallet
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "txID": "NUPLwbt2hsYxpQg4H2o451hmTWQ4JZx2zMzM4SinwtHgAdX1JLPHXvWSXEnpecStLj"
  }
}
```

# AvalancheGo X-Chain RPC (/docs/rpcs/x-chain)

---
title: "AvalancheGo X-Chain RPC"
description: "This page is an overview of the X-Chain RPC associated with AvalancheGo."
edit_url: https://github.com/ava-labs/avalanchego/edit/master/vms/avm/service.md
---

The [X-Chain](https://build.avax.network/docs/quick-start/primary-network#x-chain),
Avalanche's native platform for creating and trading assets, is an instance of the Avalanche Virtual
Machine (AVM). This API allows clients to create and trade assets on the X-Chain and other instances
of the AVM.

## Format

This API uses the `json 2.0` RPC format. For more information on making JSON RPC calls, see
[here](https://build.avax.network/docs/api-reference/guides/issuing-api-calls).

## Endpoints

`/ext/bc/X` to interact with the X-Chain.

`/ext/bc/blockchainID` to interact with other AVM instances, where `blockchainID` is the ID of a
blockchain running the AVM.

## Methods

### `avm.getAllBalances`

<Callout type="warn">
Deprecated as of [**v1.9.12**](https://github.com/ava-labs/avalanchego/releases/tag/v1.9.12).
</Callout>

Get the balances of all assets controlled by a given address.

**Signature:**

```sh
avm.getAllBalances({address:string}) -> {
    balances: []{
        asset: string,
        balance: int
    }
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     : 1,
    "method" :"avm.getAllBalances",
    "params" :{
        "address":"X-avax1c79e0dd0susp7dc8udq34jgk2yvve7hapvdyht"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "balances": [
      {
        "asset": "AVAX",
        "balance": "102"
      },
      {
        "asset": "2sdnziCz37Jov3QSNMXcFRGFJ1tgauaj6L7qfk7yUcRPfQMC79",
        "balance": "10000"
      }
    ]
  },
  "id": 1
}
```

### `avm.getAssetDescription`

Get information about an asset.

**Signature:**

```sh
avm.getAssetDescription({assetID: string}) -> {
    assetId: string,
    name: string,
    symbol: string,
    denomination: int
}
```

- `assetID` is the id of the asset for which the information is requested.
- `name` is the asset’s human-readable, not necessarily unique name.
- `symbol` is the asset’s symbol.
- `denomination` determines how balances of this asset are displayed by user interfaces. If
  denomination is 0, 100 units of this asset are displayed as 100. If denomination is 1, 100 units
  of this asset are displayed as 10.0. If denomination is 2, 100 units of this asset are displays as
  .100, etc.

<Callout type="note">
The AssetID for AVAX differs depending on the network you are on.

Mainnet: FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z

Testnet: U8iRqJoiJm8xZHAacmvYyZVwqQx6uDNtQeP3CQ6fcgQk3JqnK

For finding the `assetID` of other assets, this [info] might be useful.
Also, `avm.getUTXOs` returns the `assetID` in its output.
</Callout>

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"avm.getAssetDescription",
    "params" :{
        "assetID" :"FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
    "jsonrpc": "2.0",
    "result": {
        "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z",
        "name": "Avalanche",
        "symbol": "AVAX",
        "denomination": "9"
    },
    "id": 1
}`
```

### `avm.getBalance`

<Callout type="warn">
Deprecated as of [**v1.9.12**](https://github.com/ava-labs/avalanchego/releases/tag/v1.9.12).
</Callout>

Get the balance of an asset controlled by a given address.

**Signature:**

```sh
avm.getBalance({
    address: string,
    assetID: string
}) -> {balance: int}
```

- `address` owner of the asset
- `assetID` id of the asset for which the balance is requested

**Example Call:**

```sh
curl -X POST --data '{
  "jsonrpc":"2.0",
  "id"     : 1,
  "method" :"avm.getBalance",
  "params" :{
      "address":"X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5",
      "assetID": "2pYGetDWyKdHxpFxh2LHeoLNCH6H5vxxCxHQtFnnFaYxLsqtHC"
  }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "balance": "299999999999900",
    "utxoIDs": [
      {
        "txID": "WPQdyLNqHfiEKp4zcCpayRHYDVYuh1hqs9c1RqgZXS4VPgdvo",
        "outputIndex": 1
      }
    ]
  }
}
```

### `avm.getBlock`

Returns the block with the given id.

**Signature:**

```sh
avm.getBlock({
    blockID: string
    encoding: string // optional
}) -> {
    block: string,
    encoding: string
}
```

**Request:**

- `blockID` is the block ID. It should be in cb58 format.
- `encoding` is the encoding format to use. Can be either `hex` or `json`. Defaults to `hex`.

**Response:**

- `block` is the transaction encoded to `encoding`.
- `encoding` is the `encoding`.

#### Hex Example

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "avm.getBlock",
    "params": {
        "blockID": "tXJ4xwmR8soHE6DzRNMQPtiwQvuYsHn6eLLBzo2moDqBquqy6",
        "encoding": "hex"
    },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "block": "0x00000000002000000000641ad33ede17f652512193721df87994f783ec806bb5640c39ee73676caffcc3215e0651000000000049a80a000000010000000e0000000100000000000000000000000000000000000000000000000000000000000000000000000121e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff000000070000002e1a2a3910000000000000000000000001000000015cf998275803a7277926912defdf177b2e97b0b400000001e0d825c5069a7336671dd27eaa5c7851d2cf449e7e1cdc469c5c9e5a953955950000000021e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff000000050000008908223b680000000100000000000000005e45d02fcc9e585544008f1df7ae5c94bf7f0f2600000000641ad3b600000000642d48b60000005aedf802580000000121e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff000000070000005aedf80258000000000000000000000001000000015cf998275803a7277926912defdf177b2e97b0b40000000b000000000000000000000001000000012892441ba9a160bcdc596dcd2cc3ad83c3493589000000010000000900000001adf2237a5fe2dfd906265e8e14274aa7a7b2ee60c66213110598ba34fb4824d74f7760321c0c8fb1e8d3c5e86909248e48a7ae02e641da5559351693a8a1939800286d4fa2",
    "encoding": "hex"
  },
  "id": 1
}
```

### `avm.getBlockByHeight`

Returns block at the given height.

**Signature:**

```sh
avm.getBlockByHeight({
    height: string
    encoding: string // optional
}) -> {
    block: string,
    encoding: string
}
```

**Request:**

- `blockHeight` is the block height. It should be in `string` format.
- `encoding` is the encoding format to use. Can be either `hex` or `json`. Defaults to `hex`.

**Response:**

- `block` is the transaction encoded to `encoding`.
- `encoding` is the `encoding`.

#### Hex Example

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "avm.getBlockByHeight",
    "params": {
        "height": "275686313486",
        "encoding": "hex"
    },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "block": "0x00000000002000000000642f6739d4efcdd07e4d4919a7fc2020b8a0f081dd64c262aaace5a6dad22be0b55fec0700000000004db9e100000001000000110000000100000000000000000000000000000000000000000000000000000000000000000000000121e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff000000070000005c6ece390000000000000000000000000100000001930ab7bf5018bfc6f9435c8b15ba2fe1e619c0230000000000000000ed5f38341e436e5d46e2bb00b45d62ae97d1b050c64bc634ae10626739e35c4b00000001c6dda861341665c3b555b46227fb5e56dc0a870c5482809349f04b00348af2a80000000021e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff000000050000005c6edd7b40000000010000000000000001000000090000000178688f4d5055bd8733801f9b52793da885bef424c90526c18e4dd97f7514bf6f0c3d2a0e9a5ea8b761bc41902eb4902c34ef034c4d18c3db7c83c64ffeadd93600731676de",
    "encoding": "hex"
  },
  "id": 1
}
```

### `avm.getHeight`

Returns the height of the last accepted block.

**Signature:**

```sh
avm.getHeight() ->
{
    height: uint64,
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "avm.getHeight",
    "params": {},
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "height": "5094088"
  },
  "id": 1
}
```

### `avm.getTx`

Returns the specified transaction. The `encoding` parameter sets the format of the returned
transaction. Can be either `"hex"` or `"json"`. Defaults to `"hex"`.

**Signature:**

```sh
avm.getTx({
    txID: string,
    encoding: string, //optional
}) -> {
    tx: string,
    encoding: string,
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"avm.getTx",
    "params" :{
        "txID":"2oJCbb8pfdxEHAf9A8CdN4Afj9VSR3xzyzNkf8tDv7aM1sfNFL",
        "encoding": "json"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "tx": {
      "unsignedTx": {
        "networkID": 1,
        "blockchainID": "2oYMBNV4eNHyqk2fjjV5nVQLDbtmNJzq5s3qs3Lo6ftnC6FByM",
        "outputs": [],
        "inputs": [
          {
            "txID": "2jbZUvi6nHy3Pgmk8xcMpSg5cW6epkPqdKkHSCweb4eRXtq4k9",
            "outputIndex": 1,
            "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z",
            "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ",
            "input": {
              "amount": 2570382395,
              "signatureIndices": [0]
            }
          }
        ],
        "memo": "0x",
        "destinationChain": "11111111111111111111111111111111LpoYY",
        "exportedOutputs": [
          {
            "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z",
            "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ",
            "output": {
              "addresses": ["X-avax1tnuesf6cqwnjw7fxjyk7lhch0vhf0v95wj5jvy"],
              "amount": 2569382395,
              "locktime": 0,
              "threshold": 1
            }
          }
        ]
      },
      "credentials": [
        {
          "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ",
          "credential": {
            "signatures": [
              "0x46ebcbcfbee3ece1fd15015204045cf3cb77f42c48d0201fc150341f91f086f177cfca8894ca9b4a0c55d6950218e4ea8c01d5c4aefb85cd7264b47bd57d224400"
            ]
          }
        }
      ],
      "id": "2oJCbb8pfdxEHAf9A8CdN4Afj9VSR3xzyzNkf8tDv7aM1sfNFL"
    },
    "encoding": "json"
  },
  "id": 1
}
```

Where:

- `credentials` is a list of this transaction's credentials. Each credential proves that this
  transaction's creator is allowed to consume one of this transaction's inputs. Each credential is a
  list of signatures.
- `unsignedTx` is the non-signature portion of the transaction.
- `networkID` is the ID of the network this transaction happened on. (Avalanche Mainnet is `1`.)
- `blockchainID` is the ID of the blockchain this transaction happened on. (Avalanche Mainnet
  X-Chain is `2oYMBNV4eNHyqk2fjjV5nVQLDbtmNJzq5s3qs3Lo6ftnC6FByM`.)
- Each element of `outputs` is an output (UTXO) of this transaction that is not being exported to
  another chain.
- Each element of `inputs` is an input of this transaction which has not been imported from another
  chain.
- Import Transactions have additional fields `sourceChain` and `importedInputs`, which specify the
  blockchain ID that assets are being imported from, and the inputs that are being imported.
- Export Transactions have additional fields `destinationChain` and `exportedOutputs`, which specify
  the blockchain ID that assets are being exported to, and the UTXOs that are being exported.

An output contains:

- `assetID`: The ID of the asset being transferred. (The Mainnet Avax ID is
  `FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z`.)
- `fxID`: The ID of the FX this output uses.
- `output`: The FX-specific contents of this output.

Most outputs use the secp256k1 FX, look like this:

```json
{
  "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z",
  "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ",
  "output": {
    "addresses": ["X-avax126rd3w35xwkmj8670zvf7y5r8k36qa9z9803wm"],
    "amount": 1530084210,
    "locktime": 0,
    "threshold": 1
  }
}
```

The above output can be consumed after Unix time `locktime` by a transaction that has signatures
from `threshold` of the addresses in `addresses`.

### `avm.getTxFee`

Get the fees of the network.

**Signature**:

```
avm.getTxFee() ->
{
  txFee: uint64,
  createAssetTxFee: uint64,
}
```

- `txFee` is the default fee for making transactions.
- `createAssetTxFee` is the fee for creating a new asset.

All fees are denominated in nAVAX.

**Example Call**:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     : 1,
    "method" :"avm.getTxFee",
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response**:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "txFee": "1000000",
    "createAssetTxFee": "10000000"
  }
}
```

### `avm.getTxStatus`

<Callout type="warn">
Deprecated as of **v1.10.0**.
</Callout>

Get the status of a transaction sent to the network.

**Signature:**

```sh
avm.getTxStatus({txID: string}) -> {status: string}
```

`status` is one of:

- `Accepted`: The transaction is (or will be) accepted by every node
- `Processing`: The transaction is being voted on by this node
- `Rejected`: The transaction will never be accepted by any node in the network
- `Unknown`: The transaction hasn’t been seen by this node

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"avm.getTxStatus",
    "params" :{
        "txID":"2QouvFWUbjuySRxeX5xMbNCuAaKWfbk5FeEa2JmoF85RKLk2dD"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "status": "Accepted"
  }
}
```

### `avm.getUTXOs`

Gets the UTXOs that reference a given address. If `sourceChain` is specified, then it will retrieve
the atomic UTXOs exported from that chain to the X Chain.

**Signature:**

```sh
avm.getUTXOs({
    addresses: []string,
    limit: int, //optional
    startIndex: { //optional
        address: string,
        utxo: string
    },
    sourceChain: string, //optional
    encoding: string //optional
}) -> {
    numFetched: int,
    utxos: []string,
    endIndex: {
        address: string,
        utxo: string
    },
    sourceChain: string, //optional
    encoding: string
}
```

- `utxos` is a list of UTXOs such that each UTXO references at least one address in `addresses`.
- At most `limit` UTXOs are returned. If `limit` is omitted or greater than 1024, it is set to 1024.
- This method supports pagination. `endIndex` denotes the last UTXO returned. To get the next set of
  UTXOs, use the value of `endIndex` as `startIndex` in the next call.
- If `startIndex` is omitted, will fetch all UTXOs up to `limit`.
- When using pagination (when `startIndex` is provided), UTXOs are not guaranteed to be unique
  across multiple calls. That is, a UTXO may appear in the result of the first call, and then again
  in the second call.
- When using pagination, consistency is not guaranteed across multiple calls. That is, the UTXO set
  of the addresses may have changed between calls.
- `encoding` sets the format for the returned UTXOs. Can only be `hex` when a value is provided.

#### **Example**

Suppose we want all UTXOs that reference at least one of
`X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5` and `X-avax1d09qn852zcy03sfc9hay2llmn9hsgnw4tp3dv6`.

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"avm.getUTXOs",
    "params" :{
        "addresses":["X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5", "X-avax1d09qn852zcy03sfc9hay2llmn9hsgnw4tp3dv6"],
        "limit":5,
        "encoding": "hex"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

This gives response:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "numFetched": "5",
    "utxos": [
      "0x0000a195046108a85e60f7a864bb567745a37f50c6af282103e47cc62f036cee404700000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216c1f01765",
      "0x0000ae8b1b94444eed8de9a81b1222f00f1b4133330add23d8ac288bffa98b85271100000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216473d042a",
      "0x0000731ce04b1feefa9f4291d869adc30a33463f315491e164d89be7d6d2d7890cfc00000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f21600dd3047",
      "0x0000b462030cc4734f24c0bc224cf0d16ee452ea6b67615517caffead123ab4fbf1500000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216c71b387e",
      "0x000054f6826c39bc957c0c6d44b70f961a994898999179cc32d21eb09c1908d7167b00000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f2166290e79d"
    ],
    "endIndex": {
      "address": "X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5",
      "utxo": "kbUThAUfmBXUmRgTpgD6r3nLj7rJUGho6xyht5nouNNypH45j"
    },
    "encoding": "hex"
  },
  "id": 1
}
```

Since `numFetched` is the same as `limit`, we can tell that there may be more UTXOs that were not
fetched. We call the method again, this time with `startIndex`:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :2,
    "method" :"avm.getUTXOs",
    "params" :{
        "addresses":["X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5"],
        "limit":5,
        "startIndex": {
            "address": "X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5",
            "utxo": "kbUThAUfmBXUmRgTpgD6r3nLj7rJUGho6xyht5nouNNypH45j"
        },
        "encoding": "hex"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

This gives response:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "numFetched": "4",
    "utxos": [
      "0x000020e182dd51ee4dcd31909fddd75bb3438d9431f8e4efce86a88a684f5c7fa09300000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f21662861d59",
      "0x0000a71ba36c475c18eb65dc90f6e85c4fd4a462d51c5de3ac2cbddf47db4d99284e00000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f21665f6f83f",
      "0x0000925424f61cb13e0fbdecc66e1270de68de9667b85baa3fdc84741d048daa69fa00000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216afecf76a",
      "0x000082f30327514f819da6009fad92b5dba24d27db01e29ad7541aa8e6b6b554615c00000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216779c2d59"
    ],
    "endIndex": {
      "address": "X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5",
      "utxo": "21jG2RfqyHUUgkTLe2tUp6ETGLriSDTW3th8JXFbPRNiSZ11jK"
    },
    "encoding": "hex"
  },
  "id": 1
}
```

Since `numFetched` is less than `limit`, we know that we are done fetching UTXOs and don’t need to
call this method again.

Suppose we want to fetch the UTXOs exported from the P Chain to the X Chain in order to build an
ImportTx. Then we need to call GetUTXOs with the `sourceChain` argument in order to retrieve the
atomic UTXOs:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"avm.getUTXOs",
    "params" :{
        "addresses":["X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5", "X-avax1d09qn852zcy03sfc9hay2llmn9hsgnw4tp3dv6"],
        "limit":5,
        "sourceChain": "P",
        "encoding": "hex"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

This gives response:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "numFetched": "1",
    "utxos": [
      "0x00001f989ffaf18a18a59bdfbf209342aa61c6a62a67e8639d02bb3c8ddab315c6fa0000000039c33a499ce4c33a3b09cdd2cfa01ae70dbf2d18b2d7d168524440e55d550088000000070011c304cd7eb5c0000000000000000000000001000000013cb7d3842e8cee6a0ebd09f1fe884f6861e1b29c83497819"
    ],
    "endIndex": {
      "address": "X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5",
      "utxo": "2Sz2XwRYqUHwPeiKoRnZ6ht88YqzAF1SQjMYZQQaB5wBFkAqST"
    },
    "encoding": "hex"
  },
  "id": 1
}
```

### `avm.issueTx`

Send a signed transaction to the network. `encoding` specifies the format of the signed transaction.
Can only be `hex` when a value is provided.

**Signature:**

```sh
avm.issueTx({
    tx: string,
    encoding: string, //optional
}) -> {
    txID: string
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     : 1,
    "method" :"avm.issueTx",
    "params" :{
        "tx":"0x00000009de31b4d8b22991d51aa6aa1fc733f23a851a8c9400000000000186a0000000005f041280000000005f9ca900000030390000000000000001fceda8f90fcb5d30614b99d79fc4baa29307762668f16eb0259a57c2d3b78c875c86ec2045792d4df2d926c40f829196e0bb97ee697af71f5b0a966dabff749634c8b729855e937715b0e44303fd1014daedc752006011b730",
        "encoding": "hex"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "txID": "NUPLwbt2hsYxpQg4H2o451hmTWQ4JZx2zMzM4SinwtHgAdX1JLPHXvWSXEnpecStLj"
  }
}
```

### `wallet.issueTx`

Send a signed transaction to the network and assume the TX will be accepted. `encoding` specifies
the format of the signed transaction. Can only be `hex` when a value is provided.

This call is made to the wallet API endpoint:

`/ext/bc/X/wallet`

:::caution
Endpoint deprecated as of [**v1.9.12**](https://github.com/ava-labs/avalanchego/releases/tag/v1.9.12).

:::

**Signature:**

```sh
wallet.issueTx({
    tx: string,
    encoding: string, //optional
}) -> {
    txID: string
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     : 1,
    "method" :"wallet.issueTx",
    "params" :{
        "tx":"0x00000009de31b4d8b22991d51aa6aa1fc733f23a851a8c9400000000000186a0000000005f041280000000005f9ca900000030390000000000000001fceda8f90fcb5d30614b99d79fc4baa29307762668f16eb0259a57c2d3b78c875c86ec2045792d4df2d926c40f829196e0bb97ee697af71f5b0a966dabff749634c8b729855e937715b0e44303fd1014daedc752006011b730",
        "encoding": "hex"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X/wallet
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "txID": "NUPLwbt2hsYxpQg4H2o451hmTWQ4JZx2zMzM4SinwtHgAdX1JLPHXvWSXEnpecStLj"
  }
}
```

# X-Chain RPC (/docs/rpcs/x-chain/rpc)

---
title: "X-Chain RPC"
description: "This page is an overview of the X-Chain RPC associated with AvalancheGo."
edit_url: https://github.com/ava-labs/avalanchego/edit/master/vms/avm/service.md
---

The [X-Chain](https://build.avax.network/docs/quick-start/primary-network#x-chain),
Avalanche's native platform for creating and trading assets, is an instance of the Avalanche Virtual
Machine (AVM). This API allows clients to create and trade assets on the X-Chain and other instances
of the AVM.

## Format

This API uses the `json 2.0` RPC format. For more information on making JSON RPC calls, see
[here](https://build.avax.network/docs/api-reference/guides/issuing-api-calls).

## Endpoints

`/ext/bc/X` to interact with the X-Chain.

`/ext/bc/blockchainID` to interact with other AVM instances, where `blockchainID` is the ID of a
blockchain running the AVM.

## Methods

### `avm.getAllBalances`

<Callout type="warn">
Deprecated as of [**v1.9.12**](https://github.com/ava-labs/avalanchego/releases/tag/v1.9.12).
</Callout>

Get the balances of all assets controlled by a given address.

**Signature:**

```sh
avm.getAllBalances({address:string}) -> {
    balances: []{
        asset: string,
        balance: int
    }
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     : 1,
    "method" :"avm.getAllBalances",
    "params" :{
        "address":"X-avax1c79e0dd0susp7dc8udq34jgk2yvve7hapvdyht"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "balances": [
      {
        "asset": "AVAX",
        "balance": "102"
      },
      {
        "asset": "2sdnziCz37Jov3QSNMXcFRGFJ1tgauaj6L7qfk7yUcRPfQMC79",
        "balance": "10000"
      }
    ]
  },
  "id": 1
}
```

### `avm.getAssetDescription`

Get information about an asset.

**Signature:**

```sh
avm.getAssetDescription({assetID: string}) -> {
    assetId: string,
    name: string,
    symbol: string,
    denomination: int
}
```

- `assetID` is the id of the asset for which the information is requested.
- `name` is the asset’s human-readable, not necessarily unique name.
- `symbol` is the asset’s symbol.
- `denomination` determines how balances of this asset are displayed by user interfaces. If
  denomination is 0, 100 units of this asset are displayed as 100. If denomination is 1, 100 units
  of this asset are displayed as 10.0. If denomination is 2, 100 units of this asset are displays as
  .100, etc.

<Callout type="note">
The AssetID for AVAX differs depending on the network you are on.

Mainnet: FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z

Testnet: U8iRqJoiJm8xZHAacmvYyZVwqQx6uDNtQeP3CQ6fcgQk3JqnK

For finding the `assetID` of other assets, this [info] might be useful.
Also, `avm.getUTXOs` returns the `assetID` in its output.
</Callout>

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"avm.getAssetDescription",
    "params" :{
        "assetID" :"FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
    "jsonrpc": "2.0",
    "result": {
        "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z",
        "name": "Avalanche",
        "symbol": "AVAX",
        "denomination": "9"
    },
    "id": 1
}`
```

### `avm.getBalance`

<Callout type="warn">
Deprecated as of [**v1.9.12**](https://github.com/ava-labs/avalanchego/releases/tag/v1.9.12).
</Callout>

Get the balance of an asset controlled by a given address.

**Signature:**

```sh
avm.getBalance({
    address: string,
    assetID: string
}) -> {balance: int}
```

- `address` owner of the asset
- `assetID` id of the asset for which the balance is requested

**Example Call:**

```sh
curl -X POST --data '{
  "jsonrpc":"2.0",
  "id"     : 1,
  "method" :"avm.getBalance",
  "params" :{
      "address":"X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5",
      "assetID": "2pYGetDWyKdHxpFxh2LHeoLNCH6H5vxxCxHQtFnnFaYxLsqtHC"
  }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "balance": "299999999999900",
    "utxoIDs": [
      {
        "txID": "WPQdyLNqHfiEKp4zcCpayRHYDVYuh1hqs9c1RqgZXS4VPgdvo",
        "outputIndex": 1
      }
    ]
  }
}
```

### `avm.getBlock`

Returns the block with the given id.

**Signature:**

```sh
avm.getBlock({
    blockID: string
    encoding: string // optional
}) -> {
    block: string,
    encoding: string
}
```

**Request:**

- `blockID` is the block ID. It should be in cb58 format.
- `encoding` is the encoding format to use. Can be either `hex` or `json`. Defaults to `hex`.

**Response:**

- `block` is the transaction encoded to `encoding`.
- `encoding` is the `encoding`.

#### Hex Example

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "avm.getBlock",
    "params": {
        "blockID": "tXJ4xwmR8soHE6DzRNMQPtiwQvuYsHn6eLLBzo2moDqBquqy6",
        "encoding": "hex"
    },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "block": "0x00000000002000000000641ad33ede17f652512193721df87994f783ec806bb5640c39ee73676caffcc3215e0651000000000049a80a000000010000000e0000000100000000000000000000000000000000000000000000000000000000000000000000000121e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff000000070000002e1a2a3910000000000000000000000001000000015cf998275803a7277926912defdf177b2e97b0b400000001e0d825c5069a7336671dd27eaa5c7851d2cf449e7e1cdc469c5c9e5a953955950000000021e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff000000050000008908223b680000000100000000000000005e45d02fcc9e585544008f1df7ae5c94bf7f0f2600000000641ad3b600000000642d48b60000005aedf802580000000121e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff000000070000005aedf80258000000000000000000000001000000015cf998275803a7277926912defdf177b2e97b0b40000000b000000000000000000000001000000012892441ba9a160bcdc596dcd2cc3ad83c3493589000000010000000900000001adf2237a5fe2dfd906265e8e14274aa7a7b2ee60c66213110598ba34fb4824d74f7760321c0c8fb1e8d3c5e86909248e48a7ae02e641da5559351693a8a1939800286d4fa2",
    "encoding": "hex"
  },
  "id": 1
}
```

### `avm.getBlockByHeight`

Returns block at the given height.

**Signature:**

```sh
avm.getBlockByHeight({
    height: string
    encoding: string // optional
}) -> {
    block: string,
    encoding: string
}
```

**Request:**

- `blockHeight` is the block height. It should be in `string` format.
- `encoding` is the encoding format to use. Can be either `hex` or `json`. Defaults to `hex`.

**Response:**

- `block` is the transaction encoded to `encoding`.
- `encoding` is the `encoding`.

#### Hex Example

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "avm.getBlockByHeight",
    "params": {
        "height": "275686313486",
        "encoding": "hex"
    },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "block": "0x00000000002000000000642f6739d4efcdd07e4d4919a7fc2020b8a0f081dd64c262aaace5a6dad22be0b55fec0700000000004db9e100000001000000110000000100000000000000000000000000000000000000000000000000000000000000000000000121e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff000000070000005c6ece390000000000000000000000000100000001930ab7bf5018bfc6f9435c8b15ba2fe1e619c0230000000000000000ed5f38341e436e5d46e2bb00b45d62ae97d1b050c64bc634ae10626739e35c4b00000001c6dda861341665c3b555b46227fb5e56dc0a870c5482809349f04b00348af2a80000000021e67317cbc4be2aeb00677ad6462778a8f52274b9d605df2591b23027a87dff000000050000005c6edd7b40000000010000000000000001000000090000000178688f4d5055bd8733801f9b52793da885bef424c90526c18e4dd97f7514bf6f0c3d2a0e9a5ea8b761bc41902eb4902c34ef034c4d18c3db7c83c64ffeadd93600731676de",
    "encoding": "hex"
  },
  "id": 1
}
```

### `avm.getHeight`

Returns the height of the last accepted block.

**Signature:**

```sh
avm.getHeight() ->
{
    height: uint64,
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "avm.getHeight",
    "params": {},
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "height": "5094088"
  },
  "id": 1
}
```

### `avm.getTx`

Returns the specified transaction. The `encoding` parameter sets the format of the returned
transaction. Can be either `"hex"` or `"json"`. Defaults to `"hex"`.

**Signature:**

```sh
avm.getTx({
    txID: string,
    encoding: string, //optional
}) -> {
    tx: string,
    encoding: string,
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"avm.getTx",
    "params" :{
        "txID":"2oJCbb8pfdxEHAf9A8CdN4Afj9VSR3xzyzNkf8tDv7aM1sfNFL",
        "encoding": "json"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "result": {
    "tx": {
      "unsignedTx": {
        "networkID": 1,
        "blockchainID": "2oYMBNV4eNHyqk2fjjV5nVQLDbtmNJzq5s3qs3Lo6ftnC6FByM",
        "outputs": [],
        "inputs": [
          {
            "txID": "2jbZUvi6nHy3Pgmk8xcMpSg5cW6epkPqdKkHSCweb4eRXtq4k9",
            "outputIndex": 1,
            "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z",
            "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ",
            "input": {
              "amount": 2570382395,
              "signatureIndices": [0]
            }
          }
        ],
        "memo": "0x",
        "destinationChain": "11111111111111111111111111111111LpoYY",
        "exportedOutputs": [
          {
            "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z",
            "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ",
            "output": {
              "addresses": ["X-avax1tnuesf6cqwnjw7fxjyk7lhch0vhf0v95wj5jvy"],
              "amount": 2569382395,
              "locktime": 0,
              "threshold": 1
            }
          }
        ]
      },
      "credentials": [
        {
          "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ",
          "credential": {
            "signatures": [
              "0x46ebcbcfbee3ece1fd15015204045cf3cb77f42c48d0201fc150341f91f086f177cfca8894ca9b4a0c55d6950218e4ea8c01d5c4aefb85cd7264b47bd57d224400"
            ]
          }
        }
      ],
      "id": "2oJCbb8pfdxEHAf9A8CdN4Afj9VSR3xzyzNkf8tDv7aM1sfNFL"
    },
    "encoding": "json"
  },
  "id": 1
}
```

Where:

- `credentials` is a list of this transaction's credentials. Each credential proves that this
  transaction's creator is allowed to consume one of this transaction's inputs. Each credential is a
  list of signatures.
- `unsignedTx` is the non-signature portion of the transaction.
- `networkID` is the ID of the network this transaction happened on. (Avalanche Mainnet is `1`.)
- `blockchainID` is the ID of the blockchain this transaction happened on. (Avalanche Mainnet
  X-Chain is `2oYMBNV4eNHyqk2fjjV5nVQLDbtmNJzq5s3qs3Lo6ftnC6FByM`.)
- Each element of `outputs` is an output (UTXO) of this transaction that is not being exported to
  another chain.
- Each element of `inputs` is an input of this transaction which has not been imported from another
  chain.
- Import Transactions have additional fields `sourceChain` and `importedInputs`, which specify the
  blockchain ID that assets are being imported from, and the inputs that are being imported.
- Export Transactions have additional fields `destinationChain` and `exportedOutputs`, which specify
  the blockchain ID that assets are being exported to, and the UTXOs that are being exported.

An output contains:

- `assetID`: The ID of the asset being transferred. (The Mainnet Avax ID is
  `FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z`.)
- `fxID`: The ID of the FX this output uses.
- `output`: The FX-specific contents of this output.

Most outputs use the secp256k1 FX, look like this:

```json
{
  "assetID": "FvwEAhmxKfeiG8SnEvq42hc6whRyY3EFYAvebMqDNDGCgxN5Z",
  "fxID": "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ",
  "output": {
    "addresses": ["X-avax126rd3w35xwkmj8670zvf7y5r8k36qa9z9803wm"],
    "amount": 1530084210,
    "locktime": 0,
    "threshold": 1
  }
}
```

The above output can be consumed after Unix time `locktime` by a transaction that has signatures
from `threshold` of the addresses in `addresses`.

### `avm.getTxFee`

Get the fees of the network.

**Signature**:

```
avm.getTxFee() ->
{
  txFee: uint64,
  createAssetTxFee: uint64,
}
```

- `txFee` is the default fee for making transactions.
- `createAssetTxFee` is the fee for creating a new asset.

All fees are denominated in nAVAX.

**Example Call**:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     : 1,
    "method" :"avm.getTxFee",
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response**:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "txFee": "1000000",
    "createAssetTxFee": "10000000"
  }
}
```

### `avm.getTxStatus`

<Callout type="warn">
Deprecated as of **v1.10.0**.
</Callout>

Get the status of a transaction sent to the network.

**Signature:**

```sh
avm.getTxStatus({txID: string}) -> {status: string}
```

`status` is one of:

- `Accepted`: The transaction is (or will be) accepted by every node
- `Processing`: The transaction is being voted on by this node
- `Rejected`: The transaction will never be accepted by any node in the network
- `Unknown`: The transaction hasn’t been seen by this node

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"avm.getTxStatus",
    "params" :{
        "txID":"2QouvFWUbjuySRxeX5xMbNCuAaKWfbk5FeEa2JmoF85RKLk2dD"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "status": "Accepted"
  }
}
```

### `avm.getUTXOs`

Gets the UTXOs that reference a given address. If `sourceChain` is specified, then it will retrieve
the atomic UTXOs exported from that chain to the X Chain.

**Signature:**

```sh
avm.getUTXOs({
    addresses: []string,
    limit: int, //optional
    startIndex: { //optional
        address: string,
        utxo: string
    },
    sourceChain: string, //optional
    encoding: string //optional
}) -> {
    numFetched: int,
    utxos: []string,
    endIndex: {
        address: string,
        utxo: string
    },
    sourceChain: string, //optional
    encoding: string
}
```

- `utxos` is a list of UTXOs such that each UTXO references at least one address in `addresses`.
- At most `limit` UTXOs are returned. If `limit` is omitted or greater than 1024, it is set to 1024.
- This method supports pagination. `endIndex` denotes the last UTXO returned. To get the next set of
  UTXOs, use the value of `endIndex` as `startIndex` in the next call.
- If `startIndex` is omitted, will fetch all UTXOs up to `limit`.
- When using pagination (when `startIndex` is provided), UTXOs are not guaranteed to be unique
  across multiple calls. That is, a UTXO may appear in the result of the first call, and then again
  in the second call.
- When using pagination, consistency is not guaranteed across multiple calls. That is, the UTXO set
  of the addresses may have changed between calls.
- `encoding` sets the format for the returned UTXOs. Can only be `hex` when a value is provided.

#### **Example**

Suppose we want all UTXOs that reference at least one of
`X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5` and `X-avax1d09qn852zcy03sfc9hay2llmn9hsgnw4tp3dv6`.

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"avm.getUTXOs",
    "params" :{
        "addresses":["X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5", "X-avax1d09qn852zcy03sfc9hay2llmn9hsgnw4tp3dv6"],
        "limit":5,
        "encoding": "hex"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

This gives response:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "numFetched": "5",
    "utxos": [
      "0x0000a195046108a85e60f7a864bb567745a37f50c6af282103e47cc62f036cee404700000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216c1f01765",
      "0x0000ae8b1b94444eed8de9a81b1222f00f1b4133330add23d8ac288bffa98b85271100000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216473d042a",
      "0x0000731ce04b1feefa9f4291d869adc30a33463f315491e164d89be7d6d2d7890cfc00000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f21600dd3047",
      "0x0000b462030cc4734f24c0bc224cf0d16ee452ea6b67615517caffead123ab4fbf1500000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216c71b387e",
      "0x000054f6826c39bc957c0c6d44b70f961a994898999179cc32d21eb09c1908d7167b00000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f2166290e79d"
    ],
    "endIndex": {
      "address": "X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5",
      "utxo": "kbUThAUfmBXUmRgTpgD6r3nLj7rJUGho6xyht5nouNNypH45j"
    },
    "encoding": "hex"
  },
  "id": 1
}
```

Since `numFetched` is the same as `limit`, we can tell that there may be more UTXOs that were not
fetched. We call the method again, this time with `startIndex`:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :2,
    "method" :"avm.getUTXOs",
    "params" :{
        "addresses":["X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5"],
        "limit":5,
        "startIndex": {
            "address": "X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5",
            "utxo": "kbUThAUfmBXUmRgTpgD6r3nLj7rJUGho6xyht5nouNNypH45j"
        },
        "encoding": "hex"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

This gives response:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "numFetched": "4",
    "utxos": [
      "0x000020e182dd51ee4dcd31909fddd75bb3438d9431f8e4efce86a88a684f5c7fa09300000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f21662861d59",
      "0x0000a71ba36c475c18eb65dc90f6e85c4fd4a462d51c5de3ac2cbddf47db4d99284e00000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f21665f6f83f",
      "0x0000925424f61cb13e0fbdecc66e1270de68de9667b85baa3fdc84741d048daa69fa00000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216afecf76a",
      "0x000082f30327514f819da6009fad92b5dba24d27db01e29ad7541aa8e6b6b554615c00000000345aa98e8a990f4101e2268fab4c4e1f731c8dfbcffa3a77978686e6390d624f000000070000000000000001000000000000000000000001000000018ba98dabaebcd83056799841cfbc567d8b10f216779c2d59"
    ],
    "endIndex": {
      "address": "X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5",
      "utxo": "21jG2RfqyHUUgkTLe2tUp6ETGLriSDTW3th8JXFbPRNiSZ11jK"
    },
    "encoding": "hex"
  },
  "id": 1
}
```

Since `numFetched` is less than `limit`, we know that we are done fetching UTXOs and don’t need to
call this method again.

Suppose we want to fetch the UTXOs exported from the P Chain to the X Chain in order to build an
ImportTx. Then we need to call GetUTXOs with the `sourceChain` argument in order to retrieve the
atomic UTXOs:

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"avm.getUTXOs",
    "params" :{
        "addresses":["X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5", "X-avax1d09qn852zcy03sfc9hay2llmn9hsgnw4tp3dv6"],
        "limit":5,
        "sourceChain": "P",
        "encoding": "hex"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

This gives response:

```json
{
  "jsonrpc": "2.0",
  "result": {
    "numFetched": "1",
    "utxos": [
      "0x00001f989ffaf18a18a59bdfbf209342aa61c6a62a67e8639d02bb3c8ddab315c6fa0000000039c33a499ce4c33a3b09cdd2cfa01ae70dbf2d18b2d7d168524440e55d550088000000070011c304cd7eb5c0000000000000000000000001000000013cb7d3842e8cee6a0ebd09f1fe884f6861e1b29c83497819"
    ],
    "endIndex": {
      "address": "X-avax18jma8ppw3nhx5r4ap8clazz0dps7rv5ukulre5",
      "utxo": "2Sz2XwRYqUHwPeiKoRnZ6ht88YqzAF1SQjMYZQQaB5wBFkAqST"
    },
    "encoding": "hex"
  },
  "id": 1
}
```

### `avm.issueTx`

Send a signed transaction to the network. `encoding` specifies the format of the signed transaction.
Can only be `hex` when a value is provided.

**Signature:**

```sh
avm.issueTx({
    tx: string,
    encoding: string, //optional
}) -> {
    txID: string
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     : 1,
    "method" :"avm.issueTx",
    "params" :{
        "tx":"0x00000009de31b4d8b22991d51aa6aa1fc733f23a851a8c9400000000000186a0000000005f041280000000005f9ca900000030390000000000000001fceda8f90fcb5d30614b99d79fc4baa29307762668f16eb0259a57c2d3b78c875c86ec2045792d4df2d926c40f829196e0bb97ee697af71f5b0a966dabff749634c8b729855e937715b0e44303fd1014daedc752006011b730",
        "encoding": "hex"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "txID": "NUPLwbt2hsYxpQg4H2o451hmTWQ4JZx2zMzM4SinwtHgAdX1JLPHXvWSXEnpecStLj"
  }
}
```

### `wallet.issueTx`

Send a signed transaction to the network and assume the TX will be accepted. `encoding` specifies
the format of the signed transaction. Can only be `hex` when a value is provided.

This call is made to the wallet API endpoint:

`/ext/bc/X/wallet`

:::caution
Endpoint deprecated as of [**v1.9.12**](https://github.com/ava-labs/avalanchego/releases/tag/v1.9.12).

:::

**Signature:**

```sh
wallet.issueTx({
    tx: string,
    encoding: string, //optional
}) -> {
    txID: string
}
```

**Example Call:**

```sh
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     : 1,
    "method" :"wallet.issueTx",
    "params" :{
        "tx":"0x00000009de31b4d8b22991d51aa6aa1fc733f23a851a8c9400000000000186a0000000005f041280000000005f9ca900000030390000000000000001fceda8f90fcb5d30614b99d79fc4baa29307762668f16eb0259a57c2d3b78c875c86ec2045792d4df2d926c40f829196e0bb97ee697af71f5b0a966dabff749634c8b729855e937715b0e44303fd1014daedc752006011b730",
        "encoding": "hex"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X/wallet
```

**Example Response:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "txID": "NUPLwbt2hsYxpQg4H2o451hmTWQ4JZx2zMzM4SinwtHgAdX1JLPHXvWSXEnpecStLj"
  }
}
```

# Transaction Format (/docs/rpcs/x-chain/txn-format)

---
title: Transaction Format
---

This file is meant to be the single source of truth for how we serialize
transactions in the Avalanche Virtual Machine (AVM). This document uses the
[primitive serialization](/docs/api-reference/standards/serialization-primitives) format for packing and
[secp256k1](/docs/api-reference/standards/cryptographic-primitives#secp256k1-addresses) for cryptographic
user identification.

## Codec ID

Some data is prepended with a codec ID (unt16) that denotes how the data should
be deserialized. Right now, the only valid codec ID is 0 (`0x00 0x00`).

## Transferable Output

Transferable outputs wrap an output with an asset ID.

### What Transferable Output Contains

A transferable output contains an `AssetID` and an [`Output`](/docs/api-reference/x-chain/txn-format#outputs).

- **`AssetID`** is a 32-byte array that defines which asset this output references.
- **`Output`** is an output, as defined
  [below](/docs/api-reference/x-chain/txn-format#outputs). Outputs have four possible types:
  [`SECP256K1TransferOutput`](/docs/api-reference/x-chain/txn-format#secp256k1-transfer-output),
  [`SECP256K1MintOutput`](/docs/api-reference/x-chain/txn-format#secp256k1-mint-output),
  [`NFTTransferOutput`](/docs/api-reference/x-chain/txn-format#nft-transfer-output)
  and [`NFTMintOutput`](/docs/api-reference/x-chain/txn-format#nft-mint-output).

### Gantt Transferable Output Specification

```text
+----------+----------+-------------------------+
| asset_id : [32]byte |                32 bytes |
+----------+----------+-------------------------+
| output   : Output   |      size(output) bytes |
+----------+----------+-------------------------+
                      | 32 + size(output) bytes |
                      +-------------------------+
```

### Proto Transferable Output Specification

```text
message TransferableOutput {
    bytes asset_id = 1; // 32 bytes
    Output output = 2;  // size(output)
}
```

### Transferable Output Example

Let's make a transferable output:

- `AssetID`: `0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f`
- `Output`: `"Example SECP256K1 Transfer Output from below"`

```text
[
    AssetID <- 0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f
    Output  <- 0x000000070000000000003039000000000000d431000000010000000251025c61fbcfc078f69334f834be6dd26d55a955c3344128e060128ede3523a24a461c8943ab0859,
]
=
[
    // assetID:
    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
    0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
    0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
    0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
    // output:
    0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x30, 0x39, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0xd4, 0x31, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x02, 0x51, 0x02, 0x5c, 0x61,
    0xfb, 0xcf, 0xc0, 0x78, 0xf6, 0x93, 0x34, 0xf8,
    0x34, 0xbe, 0x6d, 0xd2, 0x6d, 0x55, 0xa9, 0x55,
    0xc3, 0x34, 0x41, 0x28, 0xe0, 0x60, 0x12, 0x8e,
    0xde, 0x35, 0x23, 0xa2, 0x4a, 0x46, 0x1c, 0x89,
    0x43, 0xab, 0x08, 0x59,
]
```

## Transferable Input

Transferable inputs describe a specific UTXO with a provided transfer input.

### What Transferable Input Contains

A transferable input contains a `TxID`, `UTXOIndex` `AssetID` and an `Input`.

- **`TxID`** is a 32-byte array that defines which transaction this input is
  consuming an output from. Transaction IDs are calculated by taking sha256 of
  the bytes of the signed transaction.
- **`UTXOIndex`** is an int that defines which UTXO this input is consuming in the specified transaction.
- **`AssetID`** is a 32-byte array that defines which asset this input references.
- **`Input`** is an input, as defined below. This can currently only be a [SECP256K1 transfer input](/docs/api-reference/x-chain/txn-format#secp256k1-transfer-input)

### Gantt Transferable Input Specification

```text
+------------+----------+------------------------+
| tx_id      : [32]byte |               32 bytes |
+------------+----------+------------------------+
| utxo_index : int      |               04 bytes |
+------------+----------+------------------------+
| asset_id   : [32]byte |               32 bytes |
+------------+----------+------------------------+
| input      : Input    |      size(input) bytes |
+------------+----------+------------------------+
                        | 68 + size(input) bytes |
                        +------------------------+
```

### Proto Transferable Input Specification

```text
message TransferableInput {
    bytes tx_id = 1;       // 32 bytes
    uint32 utxo_index = 2; // 04 bytes
    bytes asset_id = 3;    // 32 bytes
    Input input = 4;       // size(input)
}
```

### Transferable Input Example

Let's make a transferable input:

- `TxID`: `0xf1e1d1c1b1a191817161514131211101f0e0d0c0b0a090807060504030201000`
- `UTXOIndex`: `5`
- `AssetID`: `0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f`
- `Input`: `"Example SECP256K1 Transfer Input from below"`

```text
[
    TxID      <- 0xf1e1d1c1b1a191817161514131211101f0e0d0c0b0a090807060504030201000
    UTXOIndex <- 0x00000005
    AssetID   <- 0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f
    Input     <- 0x0000000500000000075bcd15000000020000000700000003
]
=
[
    // txID:
    0xf1, 0xe1, 0xd1, 0xc1, 0xb1, 0xa1, 0x91, 0x81,
    0x71, 0x61, 0x51, 0x41, 0x31, 0x21, 0x11, 0x01,
    0xf0, 0xe0, 0xd0, 0xc0, 0xb0, 0xa0, 0x90, 0x80,
    0x70, 0x60, 0x50, 0x40, 0x30, 0x20, 0x10, 0x00,
    // utxoIndex:
    0x00, 0x00, 0x00, 0x05,
    // assetID:
    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
    0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
    0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
    0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
    // input:
    0x00, 0x00, 0x00, 0x05, 0x00, 0x00, 0x00, 0x00,
    0x07, 0x5b, 0xcd, 0x15, 0x00, 0x00, 0x00, 0x02,
    0x00, 0x00, 0x00, 0x03, 0x00, 0x00, 0x00, 0x07
]
```

## Transferable Op

Transferable operations describe a set of UTXOs with a provided transfer
operation. Only one Asset ID is able to be referenced per operation.

### What Transferable Op Contains

A transferable operation contains an `AssetID`, `UTXOIDs`, and a `TransferOp`.

- **`AssetID`** is a 32-byte array that defines which asset this operation changes.
- **`UTXOIDs`** is an array of TxID-OutputIndex tuples. This array must be
  sorted in lexicographical order.
- **`TransferOp`** is a [transferable operation object](/docs/api-reference/x-chain/txn-format#operations).

### Gantt Transferable Op Specification

```text
+-------------+------------+------------------------------+
| asset_id    : [32]byte   |                     32 bytes |
+-------------+------------+------------------------------+
| utxo_ids    : []UTXOID   | 4 + 36 * len(utxo_ids) bytes |
+-------------+------------+------------------------------+
| transfer_op : TransferOp |      size(transfer_op) bytes |
+-------------+------------+------------------------------+
                           |   36 + 36 * len(utxo_ids)    |
                           |    + size(transfer_op) bytes |
                           +------------------------------+
```

### Proto Transferable Op Specification

```text
message UTXOID {
    bytes tx_id = 1;       // 32 bytes
    uint32 utxo_index = 2; // 04 bytes
}
message TransferableOp {
    bytes asset_id = 1;           // 32 bytes
    repeated UTXOID utxo_ids = 2; // 4 + 36 * len(utxo_ids) bytes
    TransferOp transfer_op = 3;   // size(transfer_op)
}
```

### Transferable Op Example

Let's make a transferable operation:

- `AssetID`: `0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f`
- `UTXOIDs`:
  - `UTXOID`:
    - `TxID`: `0xf1e1d1c1b1a191817161514131211101f0e0d0c0b0a090807060504030201000`
    - `UTXOIndex`: `5`
- `Op`: `"Example Transfer Op from below"`

```text
[
    AssetID   <- 0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f
    UTXOIDs   <- [
        {
            TxID:0xf1e1d1c1b1a191817161514131211101f0e0d0c0b0a090807060504030201000
            UTXOIndex:5
        }
    ]
    Op     <- 0x0000000d0000000200000003000000070000303900000003431100000000010000000251025c61fbcfc078f69334f834be6dd26d55a955c3344128e060128ede3523a24a461c8943ab0859
]
=
[
    // assetID:
    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
    0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
    0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
    0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
    // number of utxoIDs:
    0x00, 0x00, 0x00, 0x01,
    // txID:
    0xf1, 0xe1, 0xd1, 0xc1, 0xb1, 0xa1, 0x91, 0x81,
    0x71, 0x61, 0x51, 0x41, 0x31, 0x21, 0x11, 0x01,
    0xf0, 0xe0, 0xd0, 0xc0, 0xb0, 0xa0, 0x90, 0x80,
    0x70, 0x60, 0x50, 0x40, 0x30, 0x20, 0x10, 0x00,
    // utxoIndex:
    0x00, 0x00, 0x00, 0x05,
    // op:
    0x00, 0x00, 0x00, 0x0d, 0x00, 0x00, 0x00, 0x02,
    0x00, 0x00, 0x00, 0x03, 0x00, 0x00, 0x00, 0x07,
    0x00, 0x00, 0x30, 0x39, 0x00, 0x00, 0x00, 0x03,
    0x43, 0x11, 0x00, 0x00, 0x00, 0x00, 0x01, 0x00,
    0x00, 0x00, 0x02, 0x51, 0x02, 0x5c, 0x61, 0xfb,
    0xcf, 0xc0, 0x78, 0xf6, 0x93, 0x34, 0xf8, 0x34,
    0xbe, 0x6d, 0xd2, 0x6d, 0x55, 0xa9, 0x55, 0xc3,
    0x34, 0x41, 0x28, 0xe0, 0x60, 0x12, 0x8e, 0xde,
    0x35, 0x23, 0xa2, 0x4a, 0x46, 0x1c, 0x89, 0x43,
    0xab, 0x08, 0x59,
]
```

## Outputs

Outputs have four possible types:
[`SECP256K1TransferOutput`](/docs/api-reference/x-chain/txn-format#secp256k1-transfer-output),
[`SECP256K1MintOutput`](/docs/api-reference/x-chain/txn-format#secp256k1-mint-output),
[`NFTTransferOutput`](/docs/api-reference/x-chain/txn-format#nft-transfer-output) and
[`NFTMintOutput`](/docs/api-reference/x-chain/txn-format#nft-mint-output).

## SECP256K1 Mint Output

A [secp256k1](/docs/api-reference/standards/cryptographic-primitives#secp256k1-addresses) mint output is
an output that is owned by a collection of addresses.

### What SECP256K1 Mint Output Contains

A secp256k1 Mint output contains a `TypeID`, `Locktime`, `Threshold`, and `Addresses`.

- **`TypeID`** is the ID for this output type. It is `0x00000006`.
- **`Locktime`** is a long that contains the Unix timestamp that this output can
  be spent after. The Unix timestamp is specific to the second.
- **`Threshold`** is an int that names the number of unique signatures required
  to spend the output. Must be less than or equal to the length of
  **`Addresses`**. If **`Addresses`** is empty, must be 0.
- **`Addresses`** is a list of unique addresses that correspond to the private
  keys that can be used to spend this output. Addresses must be sorted
  lexicographically.

### Gantt SECP256K1 Mint Output Specification

```text
+-----------+------------+--------------------------------+
| type_id   : int        |                       4 bytes  |
+-----------+------------+--------------------------------+
| locktime  : long       |                       8 bytes  |
+-----------+------------+--------------------------------+
| threshold : int        |                       4 bytes  |
+-----------+------------+--------------------------------+
| addresses : [][20]byte |  4 + 20 * len(addresses) bytes |
+-----------+------------+--------------------------------+
                         | 20 + 20 * len(addresses) bytes |
                         +--------------------------------+
```

### Proto SECP256K1 Mint Output Specification

```text
message SECP256K1MintOutput {
    uint32 typeID = 1;            // 04 bytes
    uint64 locktime = 2;          // 08 bytes
    uint32 threshold = 3;         // 04 bytes
    repeated bytes addresses = 4; // 04 bytes + 20 bytes * len(addresses)
}
```

### SECP256K1 Mint Output Example

Let's make a SECP256K1 mint output with:

- **`TypeID`**: `6`
- **`Locktime`**: `54321`
- **`Threshold`**: `1`
- **`Addresses`**:
- `0x51025c61fbcfc078f69334f834be6dd26d55a955`
- `0xc3344128e060128ede3523a24a461c8943ab0859`

```text
[
    TypeID    <- 0x00000006
    Locktime  <- 0x000000000000d431
    Threshold <- 0x00000001
    Addresses <- [
        0x51025c61fbcfc078f69334f834be6dd26d55a955,
        0xc3344128e060128ede3523a24a461c8943ab0859,
    ]
]
=
[
    // typeID:
    0x00, 0x00, 0x00, 0x06,
    // locktime:
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xd4, 0x31,
    // threshold:
    0x00, 0x00, 0x00, 0x01,
    // number of addresses:
    0x00, 0x00, 0x00, 0x02,
    // addrs[0]:
    0x51, 0x02, 0x5c, 0x61, 0xfb, 0xcf, 0xc0, 0x78,
    0xf6, 0x93, 0x34, 0xf8, 0x34, 0xbe, 0x6d, 0xd2,
    0x6d, 0x55, 0xa9, 0x55,
    // addrs[1]:
    0xc3, 0x34, 0x41, 0x28, 0xe0, 0x60, 0x12, 0x8e,
    0xde, 0x35, 0x23, 0xa2, 0x4a, 0x46, 0x1c, 0x89,
    0x43, 0xab, 0x08, 0x59,
]
```

## SECP256K1 Transfer Output

A [secp256k1](/docs/api-reference/standards/cryptographic-primitives#secp256k1-addresses) transfer output
allows for sending a quantity of an asset to a collection of addresses after a
specified Unix time.

### What SECP256K1 Transfer Output Contains

A secp256k1 transfer output contains a `TypeID`, `Amount`, `Locktime`, `Threshold`, and `Addresses`.

- **`TypeID`** is the ID for this output type. It is `0x00000007`.
- **`Amount`** is a long that specifies the quantity of the asset that this output owns. Must be positive.
- **`Locktime`** is a long that contains the Unix timestamp that this output can
  be spent after. The Unix timestamp is specific to the second.
- **`Threshold`** is an int that names the number of unique signatures required
  to spend the output. Must be less than or equal to the length of
  **`Addresses`**. If **`Addresses`** is empty, must be 0.
- **`Addresses`** is a list of unique addresses that correspond to the private
  keys that can be used to spend this output. Addresses must be sorted
  lexicographically.

### Gantt SECP256K1 Transfer Output Specification

```text
+-----------+------------+--------------------------------+
| type_id   : int        |                        4 bytes |
+-----------+------------+--------------------------------+
| amount    : long       |                        8 bytes |
+-----------+------------+--------------------------------+
| locktime  : long       |                        8 bytes |
+-----------+------------+--------------------------------+
| threshold : int        |                        4 bytes |
+-----------+------------+--------------------------------+
| addresses : [][20]byte |  4 + 20 * len(addresses) bytes |
+-----------+------------+--------------------------------+
                         | 28 + 20 * len(addresses) bytes |
                         +--------------------------------+
```

### Proto SECP256K1 Transfer Output Specification

```text
message SECP256K1TransferOutput {
    uint32 typeID = 1;            // 04 bytes
    uint64 amount = 2;            // 08 bytes
    uint64 locktime = 3;          // 08 bytes
    uint32 threshold = 4;         // 04 bytes
    repeated bytes addresses = 5; // 04 bytes + 20 bytes * len(addresses)
}
```

### SECP256K1 Transfer Output Example

Let's make a secp256k1 transfer output with:

- **`TypeID`**: `7`
- **`Amount`**: `12345`
- **`Locktime`**: `54321`
- **`Threshold`**: `1`
- **`Addresses`**:
- `0x51025c61fbcfc078f69334f834be6dd26d55a955`
- `0xc3344128e060128ede3523a24a461c8943ab0859`

```text
[
    TypeID    <- 0x00000007
    Amount    <- 0x0000000000003039
    Locktime  <- 0x000000000000d431
    Threshold <- 0x00000001
    Addresses <- [
        0x51025c61fbcfc078f69334f834be6dd26d55a955,
        0xc3344128e060128ede3523a24a461c8943ab0859,
    ]
]
=
[
    // typeID:
    0x00, 0x00, 0x00, 0x07,
    // amount:
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x30, 0x39,
    // locktime:
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xd4, 0x31,
    // threshold:
    0x00, 0x00, 0x00, 0x01,
    // number of addresses:
    0x00, 0x00, 0x00, 0x02,
    // addrs[0]:
    0x51, 0x02, 0x5c, 0x61, 0xfb, 0xcf, 0xc0, 0x78,
    0xf6, 0x93, 0x34, 0xf8, 0x34, 0xbe, 0x6d, 0xd2,
    0x6d, 0x55, 0xa9, 0x55,
    // addrs[1]:
    0xc3, 0x34, 0x41, 0x28, 0xe0, 0x60, 0x12, 0x8e,
    0xde, 0x35, 0x23, 0xa2, 0x4a, 0x46, 0x1c, 0x89,
    0x43, 0xab, 0x08, 0x59,
]
```

## NFT Mint Output

An NFT mint output is an NFT that is owned by a collection of addresses.

### What NFT Mint Output Contains

An NFT Mint output contains a `TypeID`, `GroupID`, `Locktime`, `Threshold`, and `Addresses`.

- **`TypeID`** is the ID for this output type. It is `0x0000000a`.
- **`GroupID`** is an int that specifies the group this NFT is issued to.
- **`Locktime`** is a long that contains the Unix timestamp that this output can
  be spent after. The Unix timestamp is specific to the second.
- **`Threshold`** is an int that names the number of unique signatures required
  to spend the output. Must be less than or equal to the length of
  **`Addresses`**. If **`Addresses`** is empty, must be 0.
- **`Addresses`** is a list of unique addresses that correspond to the private
  keys that can be used to spend this output. Addresses must be sorted
  lexicographically.

### Gantt NFT Mint Output Specification

```text
+-----------+------------+--------------------------------+
| type_id   : int        |                        4 bytes |
+-----------+------------+--------------------------------+
| group_id  : int        |                        4 bytes |
+-----------+------------+--------------------------------+
| locktime  : long       |                        8 bytes |
+-----------+------------+--------------------------------+
| threshold : int        |                        4 bytes |
+-----------+------------+--------------------------------+
| addresses : [][20]byte |  4 + 20 * len(addresses) bytes |
+-----------+------------+--------------------------------+
                         | 24 + 20 * len(addresses) bytes |
                         +--------------------------------+
```

### Proto NFT Mint Output Specification

```text
message NFTMintOutput {
    uint32 typeID = 1;            // 04 bytes
    uint32 group_id = 2;          // 04 bytes
    uint64 locktime = 3;          // 08 bytes
    uint32 threshold = 4;         // 04 bytes
    repeated bytes addresses = 5; // 04 bytes + 20 bytes * len(addresses)
}
```

### NFT Mint Output Example

Let's make an NFT mint output with:

- **`TypeID`**: `10`
- **`GroupID`**: `12345`
- **`Locktime`**: `54321`
- **`Threshold`**: `1`
- **`Addresses`**:
- `0x51025c61fbcfc078f69334f834be6dd26d55a955`
- `0xc3344128e060128ede3523a24a461c8943ab0859`

```text
[
    TypeID    <- 0x0000000a
    GroupID   <- 0x00003039
    Locktime  <- 0x000000000000d431
    Threshold <- 0x00000001
    Addresses <- [
        0x51025c61fbcfc078f69334f834be6dd26d55a955,
        0xc3344128e060128ede3523a24a461c8943ab0859,
    ]
]
=
[
    // TypeID
    0x00, 0x00, 0x00, 0x0a,
    // groupID:
    0x00, 0x00, 0x30, 0x39,
    // locktime:
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xd4, 0x31,
    // threshold:
    0x00, 0x00, 0x00, 0x01,
    // number of addresses:
    0x00, 0x00, 0x00, 0x02,
    // addrs[0]:
    0x51, 0x02, 0x5c, 0x61, 0xfb, 0xcf, 0xc0, 0x78,
    0xf6, 0x93, 0x34, 0xf8, 0x34, 0xbe, 0x6d, 0xd2,
    0x6d, 0x55, 0xa9, 0x55,
    // addrs[1]:
    0xc3, 0x34, 0x41, 0x28, 0xe0, 0x60, 0x12, 0x8e,
    0xde, 0x35, 0x23, 0xa2, 0x4a, 0x46, 0x1c, 0x89,
    0x43, 0xab, 0x08, 0x59,
]
```

## NFT Transfer Output

An NFT transfer output is an NFT that is owned by a collection of addresses.

### What NFT Transfer Output Contains

An NFT transfer output contains a `TypeID`, `GroupID`, `Payload`, `Locktime`, `Threshold`, and `Addresses`.

- **`TypeID`** is the ID for this output type. It is `0x0000000b`.
- **`GroupID`** is an int that specifies the group this NFT was issued with.
- **`Payload`** is an arbitrary string of bytes no long longer than 1024 bytes.
- **`Locktime`** is a long that contains the Unix timestamp that this output can
  be spent after. The Unix timestamp is specific to the second.
- **`Threshold`** is an int that names the number of unique signatures required
  to spend the output. Must be less than or equal to the length of
  **`Addresses`**. If **`Addresses`** is empty, must be 0.
- **`Addresses`** is a list of unique addresses that correspond to the private
  keys that can be used to spend this output. Addresses must be sorted
  lexicographically.

### Gantt NFT Transfer Output Specification

```text
+-----------+------------+-------------------------------+
| type_id   : int        |                       4 bytes |
+-----------+------------+-------------------------------+
| group_id  : int        |                       4 bytes |
+-----------+------------+-------------------------------+
| payload   : []byte     |        4 + len(payload) bytes |
+-----------+------------+-------------------------------+
| locktime  : long       |                       8 bytes |
+-----------+------------+-------------------------------+
| threshold : int        |                       4 bytes |
+-----------+------------+-------------------------------+
| addresses : [][20]byte | 4 + 20 * len(addresses) bytes |
+-----------+------------+-------------------------------+
                         |             28 + len(payload) |
                         |  + 20 * len(addresses) bytes  |
                         +-------------------------------+
```

### Proto NFT Transfer Output Specification

```text
message NFTTransferOutput {
    uint32 typeID = 1;            // 04 bytes
    uint32 group_id = 2;          // 04 bytes
    bytes payload = 3;            // 04 bytes + len(payload)
    uint64 locktime = 4           // 08 bytes
    uint32 threshold = 5;         // 04 bytes
    repeated bytes addresses = 6; // 04 bytes + 20 bytes * len(addresses)
}
```

### NFT Transfer Output Example

Let's make an NFT transfer output with:

- **`TypeID`**: `11`
- **`GroupID`**: `12345`
- **`Payload`**: `NFT Payload`
- **`Locktime`**: `54321`
- **`Threshold`**: `1`
- **`Addresses`**:
- `0x51025c61fbcfc078f69334f834be6dd26d55a955`
- `0xc3344128e060128ede3523a24a461c8943ab0859`

```text
[
    TypeID    <- 0x0000000b
    GroupID   <- 0x00003039
    Payload   <- 0x4e4654205061796c6f6164
    Locktime  <- 0x000000000000d431
    Threshold <- 0x00000001
    Addresses <- [
        0x51025c61fbcfc078f69334f834be6dd26d55a955,
        0xc3344128e060128ede3523a24a461c8943ab0859,
    ]
]
=
[
    // TypeID:
    0x00, 0x00, 0x00, 0x0b,
    // groupID:
    0x00, 0x00, 0x30, 0x39,
    // length of payload:
    0x00, 0x00, 0x00, 0x0b,
    // payload:
    0x4e, 0x46, 0x54, 0x20, 0x50, 0x61, 0x79, 0x6c,
    0x6f, 0x61, 0x64,
    // locktime:
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xd4, 0x31,
    // threshold:
    0x00, 0x00, 0x00, 0x01,
    // number of addresses:
    0x00, 0x00, 0x00, 0x02,
    // addrs[0]:
    0x51, 0x02, 0x5c, 0x61, 0xfb, 0xcf, 0xc0, 0x78,
    0xf6, 0x93, 0x34, 0xf8, 0x34, 0xbe, 0x6d, 0xd2,
    0x6d, 0x55, 0xa9, 0x55,
    // addrs[1]:
    0xc3, 0x34, 0x41, 0x28, 0xe0, 0x60, 0x12, 0x8e,
    0xde, 0x35, 0x23, 0xa2, 0x4a, 0x46, 0x1c, 0x89,
    0x43, 0xab, 0x08, 0x59,
]
```

## Inputs

Inputs have one possible type: `SECP256K1TransferInput`.

## SECP256K1 Transfer Input

A [secp256k1](/docs/api-reference/standards/cryptographic-primitives#secp256k1-addresses) transfer input
allows for spending an unspent secp256k1 transfer output.

### What SECP256K1 Transfer Input Contains

A secp256k1 transfer input contains an `Amount` and `AddressIndices`.

- **`TypeID`** is the ID for this input type. It is `0x00000005`.
- **`Amount`** is a long that specifies the quantity that this input should be
  consuming from the UTXO. Must be positive. Must be equal to the amount
  specified in the UTXO.
- **`AddressIndices`** is a list of unique ints that define the private keys
  that are being used to spend the UTXO. Each UTXO has an array of addresses
  that can spend the UTXO. Each int represents the index in this address array
  that will sign this transaction. The array must be sorted low to high.

### Gantt SECP256K1 Transfer Input Specification

```text
+-------------------------+-------------------------------------+
| type_id         : int   |                             4 bytes |
+-----------------+-------+-------------------------------------+
| amount          : long  |                             8 bytes |
+-----------------+-------+-------------------------------------+
| address_indices : []int |  4 + 4 * len(address_indices) bytes |
+-----------------+-------+-------------------------------------+
                          | 16 + 4 * len(address_indices) bytes |
                          +-------------------------------------+
```

### Proto SECP256K1 Transfer Input Specification

```text
message SECP256K1TransferInput {
    uint32 typeID = 1;                   // 04 bytes
    uint64 amount = 2;                   // 08 bytes
    repeated uint32 address_indices = 3; // 04 bytes + 04 bytes * len(address_indices)
}
```

### SECP256K1 Transfer Input Example

Let's make a payment input with:

- **`TypeId`**: `5`
- **`Amount`**: `123456789`
- **`AddressIndices`**: \[`3`,`7`\]

```text
[
    TypeID         <- 0x00000005
    Amount         <- 123456789 = 0x00000000075bcd15,
    AddressIndices <- [0x00000003, 0x00000007]
]
=
[
    // type id:
    0x00, 0x00, 0x00, 0x05,
    // amount:
    0x00, 0x00, 0x00, 0x00, 0x07, 0x5b, 0xcd, 0x15,
    // length:
    0x00, 0x00, 0x00, 0x02,
    // sig[0]
    0x00, 0x00, 0x00, 0x03,
    // sig[1]
    0x00, 0x00, 0x00, 0x07,
]
```

## Operations

Operations have three possible types: `SECP256K1MintOperation`, `NFTMintOp`, and `NFTTransferOp`.

## SECP256K1 Mint Operation

A [secp256k1](/docs/api-reference/standards/cryptographic-primitives#secp256k1-addresses) mint operation
consumes a SECP256K1 mint output, creates a new mint output and sends a transfer
output to a new set of owners.

### What SECP256K1 Mint Operation Contains

A secp256k1 Mint operation contains a `TypeID`, `AddressIndices`, `MintOutput`, and `TransferOutput`.

- **`TypeID`** is the ID for this output type. It is `0x00000008`.
- **`AddressIndices`** is a list of unique ints that define the private keys
  that are being used to spend the
  [UTXO](/docs/api-reference/x-chain/txn-format#utxo). Each UTXO has an array of
  addresses that can spend the UTXO. Each int represents the index in this
  address array that will sign this transaction. The array must be sorted low to
  high.
- **`MintOutput`** is a [SECP256K1 Mint output](/docs/api-reference/x-chain/txn-format#secp256k1-mint-output).
- **`TransferOutput`** is a [SECP256K1 Transfer output](/docs/api-reference/x-chain/txn-format#secp256k1-transfer-output).

### Gantt SECP256K1 Mint Operation Specification

```text
+----------------------------------+------------------------------------+
| type_id         : int            |                            4 bytes |
+----------------------------------+------------------------------------+
| address_indices : []int          | 4 + 4 * len(address_indices) bytes |
+----------------------------------+------------------------------------+
| mint_output     : MintOutput     |            size(mint_output) bytes |
+----------------------------------+------------------------------------+
| transfer_output : TransferOutput |        size(transfer_output) bytes |
+----------------------------------+------------------------------------+
                                   |       8 + 4 * len(address_indices) |
                                   |                + size(mint_output) |
                                   |      + size(transfer_output) bytes |
                                   +------------------------------------+
```

### Proto SECP256K1 Mint Operation Specification

```text
message SECP256K1MintOperation {
    uint32 typeID = 1;                   // 4 bytes
    repeated uint32 address_indices = 2; // 04 bytes + 04 bytes * len(address_indices)
    MintOutput mint_output = 3;          // size(mint_output
    TransferOutput transfer_output = 4;  // size(transfer_output)
}
```

### SECP256K1 Mint Operation Example

Let's make a [secp256k1](/docs/api-reference/standards/cryptographic-primitives#secp256k1-addresses) mint
operation with:

- **`TypeId`**: `8`
- **`AddressIndices`**:
- `0x00000003`
- `0x00000007`
- **`MintOutput`**: `"Example SECP256K1 Mint Output from above"`
- **`TransferOutput`**: `"Example SECP256K1 Transfer Output from above"`

```text
[
    TypeID <- 0x00000008
    AddressIndices <- [0x00000003, 0x00000007]
    MintOutput <- 0x00000006000000000000d431000000010000000251025c61fbcfc078f69334f834be6dd26d55a955c3344128e060128ede3523a24a461c89
    TransferOutput <- 0x000000070000000000003039000000000000d431000000010000000251025c61fbcfc078f69334f834be6dd26d55a955c3344128e060128ede3523a24a461c8943ab0859
]
=
[
    // typeID
    0x00, 0x00, 0x00, 0x08,
    // number of address_indices:
    0x00, 0x00, 0x00, 0x02,
    // address_indices[0]:
    0x00, 0x00, 0x00, 0x03,
    // address_indices[1]:
    0x00, 0x00, 0x00, 0x07,
    // mint output
    0x00, 0x00, 0x00, 0x06, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0xd4, 0x31, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x02, 0x51, 0x02, 0x5c, 0x61,
    0xfb, 0xcf, 0xc0, 0x78, 0xf6, 0x93, 0x34, 0xf8,
    0x34, 0xbe, 0x6d, 0xd2, 0x6d, 0x55, 0xa9, 0x55,
    0xc3, 0x34, 0x41, 0x28, 0xe0, 0x60, 0x12, 0x8e,
    0xde, 0x35, 0x23, 0xa2, 0x4a, 0x46, 0x1c, 0x89,
    0x43, 0xab, 0x08, 0x59,
    // transfer output
    0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x30, 0x39, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0xd4, 0x31, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x02, 0x51, 0x02, 0x5c, 0x61,
    0xfb, 0xcf, 0xc0, 0x78, 0xf6, 0x93, 0x34, 0xf8,
    0x34, 0xbe, 0x6d, 0xd2, 0x6d, 0x55, 0xa9, 0x55,
    0xc3, 0x34, 0x41, 0x28, 0xe0, 0x60, 0x12, 0x8e,
    0xde, 0x35, 0x23, 0xa2, 0x4a, 0x46, 0x1c, 0x89,
    0x43, 0xab, 0x08, 0x59,
]
```

## NFT Mint Op

An NFT mint operation consumes an NFT mint output and sends an unspent output to a new set of owners.

### What NFT Mint Op Contains

An NFT mint operation contains a `TypeID`, `AddressIndices`, `GroupID`, `Payload`, and `Output` of addresses.

- **`TypeID`** is the ID for this operation type. It is `0x0000000c`.
- **`AddressIndices`** is a list of unique ints that define the private keys
  that are being used to spend the UTXO. Each UTXO has an array of addresses
  that can spend the UTXO. Each int represents the index in this address array
  that will sign this transaction. The array must be sorted low to high.
- **`GroupID`** is an int that specifies the group this NFT is issued to.
- **`Payload`** is an arbitrary string of bytes no longer than 1024 bytes.
- **`Output`** is not a `TransferableOutput`, but rather is a lock time,
  threshold, and an array of unique addresses that correspond to the private
  keys that can be used to spend this output. Addresses must be sorted
  lexicographically.

### Gantt NFT Mint Op Specification

```text
+------------------------------+------------------------------------+
| type_id         : int        |                            4 bytes |
+-----------------+------------+------------------------------------+
| address_indices : []int      | 4 + 4 * len(address_indices) bytes |
+-----------------+------------+------------------------------------+
| group_id        : int        |                            4 bytes |
+-----------------+------------+------------------------------------+
| payload         : []byte     |             4 + len(payload) bytes |
+-----------------+------------+------------------------------------+
| outputs         : []Output   |            4 + size(outputs) bytes |
+-----------------+------------+------------------------------------+
                               |                               20 + |
                               |         4 * len(address_indices) + |
                               |                     len(payload) + |
                               |                size(outputs) bytes |
                               +------------------------------------+
```

### Proto NFT Mint Op Specification

```text
message NFTMintOp {
    uint32 typeID = 1;                   // 04 bytes
    repeated uint32 address_indices = 2; // 04 bytes + 04 bytes * len(address_indices)
    uint32 group_id = 3;                 // 04 bytes
    bytes payload = 4;                   // 04 bytes + len(payload)
    repeated bytes outputs = 5;          // 04 bytes + size(outputs)
}
```

### NFT Mint Op Example

Let's make an NFT mint operation with:

- **`TypeId`**: `12`
- **`AddressIndices`**:
  - `0x00000003`
  - `0x00000007`
- **`GroupID`**: `12345`
- **`Payload`**: `0x431100`
- **`Locktime`**: `54321`
- **`Threshold`**: `1`
- **`Addresses`**:
- `0xc3344128e060128ede3523a24a461c8943ab0859`

```text
[
    TypeID         <- 0x0000000c
    AddressIndices <- [
        0x00000003,
        0x00000007,
    ]
    GroupID        <- 0x00003039
    Payload        <- 0x431100
    Locktime       <- 0x000000000000d431
    Threshold      <- 0x00000001
    Addresses      <- [
        0xc3344128e060128ede3523a24a461c8943ab0859
    ]
]
=
[
    // Type ID
    0x00, 0x00, 0x00, 0x0c,
    // number of address indices:
    0x00, 0x00, 0x00, 0x02,
    // address index 0:
    0x00, 0x00, 0x00, 0x03,
    // address index 1:
    0x00, 0x00, 0x00, 0x07,
    // groupID:
    0x00, 0x00, 0x30, 0x39,
    // length of payload:
    0x00, 0x00, 0x00, 0x03,
    // payload:
    0x43, 0x11, 0x00,
    // number of outputs:
    0x00, 0x00, 0x00, 0x01,
    // outputs[0]
    // locktime:
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xd4, 0x31,
    // threshold:
    0x00, 0x00, 0x00, 0x01,
    // number of addresses:
    0x00, 0x00, 0x00, 0x01,
    // addrs[0]:
    0xc3, 0x34, 0x41, 0x28, 0xe0, 0x60, 0x12, 0x8e,
    0xde, 0x35, 0x23, 0xa2, 0x4a, 0x46, 0x1c, 0x89,
    0x43, 0xab, 0x08, 0x59,
]
```

## NFT Transfer Op

An NFT transfer operation sends an unspent NFT transfer output to a new set of owners.

### What NFT Transfer Op Contains

An NFT transfer operation contains a `TypeID`, `AddressIndices` and an untyped `NFTTransferOutput`.

- **`TypeID`** is the ID for this output type. It is `0x0000000d`.
- **`AddressIndices`** is a list of unique ints that define the private keys
  that are being used to spend the UTXO. Each UTXO has an array of addresses
  that can spend the UTXO. Each int represents the index in this address array
  that will sign this transaction. The array must be sorted low to high.
- **`NFTTransferOutput`** is the output of this operation and must be an [NFT Transfer Output](/docs/api-reference/x-chain/txn-format#nft-transfer-output). This
  output doesn't have the **`TypeId`**, because the type is known by the context
  of being in this operation.

### Gantt NFT Transfer Op Specification

```text
+------------------------------+------------------------------------+
| type_id         : int        |                            4 bytes |
+-----------------+------------+------------------------------------+
| address_indices : []int      | 4 + 4 * len(address_indices) bytes |
+-----------------+------------+------------------------------------+
| group_id        : int        |                            4 bytes |
+-----------------+------------+------------------------------------+
| payload         : []byte     |             4 + len(payload) bytes |
+-----------------+------------+------------------------------------+
| locktime        : long       |                            8 bytes |
+-----------+------------+------------------------------------------+
| threshold       : int        |                            4 bytes |
+-----------------+------------+------------------------------------+
| addresses       : [][20]byte |      4 + 20 * len(addresses) bytes |
+-----------------+------------+------------------------------------+
                               |                  36 + len(payload) |
                               |        + 4 * len(address_indices)  |
                               |        + 20 * len(addresses) bytes |
                               +------------------------------------+
```

### Proto NFT Transfer Op Specification

```text
message NFTTransferOp {
    uint32 typeID = 1;                   // 04 bytes
    repeated uint32 address_indices = 2; // 04 bytes + 04 bytes * len(address_indices)
    uint32 group_id = 3;                 // 04 bytes
    bytes payload = 4;                   // 04 bytes + len(payload)
    uint64 locktime = 5;                 // 08 bytes
    uint32 threshold = 6;                // 04 bytes
    repeated bytes addresses = 7;        // 04 bytes + 20 bytes * len(addresses)
}
```

### NFT Transfer Op Example

Let's make an NFT transfer operation with:

- **`TypeID`**: `13`
- **`AddressIndices`**:
- `0x00000007`
- `0x00000003`
- **`GroupID`**: `12345`
- **`Payload`**: `0x431100`
- **`Locktime`**: `54321`
- **`Threshold`**: `1`
- **`Addresses`**:
- `0xc3344128e060128ede3523a24a461c8943ab0859`
- `0x51025c61fbcfc078f69334f834be6dd26d55a955`

```text
[
    TypeID         <- 0x0000000d
    AddressIndices <- [
        0x00000007,
        0x00000003,
    ]
    GroupID        <- 0x00003039
    Payload        <- 0x431100
    Locktime       <- 0x000000000000d431
    Threshold      <- 00000001
    Addresses      <- [
        0x51025c61fbcfc078f69334f834be6dd26d55a955,
        0xc3344128e060128ede3523a24a461c8943ab0859,
    ]
]
=
[
    // Type ID
    0x00, 0x00, 0x00, 0x0d,
    // number of address indices:
    0x00, 0x00, 0x00, 0x02,
    // address index 0:
    0x00, 0x00, 0x00, 0x07,
    // address index 1:
    0x00, 0x00, 0x00, 0x03,
    // groupID:
    0x00, 0x00, 0x30, 0x39,
    // length of payload:
    0x00, 0x00, 0x00, 0x03,
    // payload:
    0x43, 0x11, 0x00,
    // locktime:
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xd4, 0x31,
    // threshold:
    0x00, 0x00, 0x00, 0x01,
    // number of addresses:
    0x00, 0x00, 0x00, 0x02,
    // addrs[0]:
    0x51, 0x02, 0x5c, 0x61, 0xfb, 0xcf, 0xc0, 0x78,
    0xf6, 0x93, 0x34, 0xf8, 0x34, 0xbe, 0x6d, 0xd2,
    0x6d, 0x55, 0xa9, 0x55,
    // addrs[1]:
    0xc3, 0x34, 0x41, 0x28, 0xe0, 0x60, 0x12, 0x8e,
    0xde, 0x35, 0x23, 0xa2, 0x4a, 0x46, 0x1c, 0x89,
    0x43, 0xab, 0x08, 0x59,
]
```

## Initial State

Initial state describes the initial state of an asset when it is created. It
contains the ID of the feature extension that the asset uses, and a variable
length array of outputs that denote the genesis UTXO set of the asset.

### What Initial State Contains

Initial state contains a `FxID` and an array of `Output`.

- **`FxID`** is an int that defines which feature extension this state is part
  of. For SECP256K1 assets, this is `0x00000000`. For NFT assets, this is
  `0x00000001`.
- **`Outputs`** is a variable length array of
  [outputs](/docs/api-reference/x-chain/txn-format#outputs), as defined above.

### Gantt Initial State Specification

```text
+---------------+----------+-------------------------------+
| fx_id         : int      |                       4 bytes |
+---------------+----------+-------------------------------+
| outputs       : []Output |       4 + size(outputs) bytes |
+---------------+----------+-------------------------------+
                           |       8 + size(outputs) bytes |
                           +-------------------------------+
```

### Proto Initial State Specification

```text
message InitialState {
    uint32 fx_id = 1;                  // 04 bytes
    repeated Output outputs = 2;       // 04 + size(outputs) bytes
}
```

### Initial State Example

Let's make an initial state:

- `FxID`: `0x00000000`
- `InitialState`: `["Example SECP256K1 Transfer Output from above"]`

```text
[
    FxID <- 0x00000000
    InitialState  <- [
        0x000000070000000000003039000000000000d431000000010000000251025c61fbcfc078f69334f834be6dd26d55a955c3344128e060128ede3523a24a461c8943ab0859,
    ]
]
=
[
    // fxID:
    0x00, 0x00, 0x00, 0x00,
    // num outputs:
    0x00, 0x00, 0x00, 0x01,
    // output:
    0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x30, 0x39, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0xd4, 0x31, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x02, 0x51, 0x02, 0x5c, 0x61,
    0xfb, 0xcf, 0xc0, 0x78, 0xf6, 0x93, 0x34, 0xf8,
    0x34, 0xbe, 0x6d, 0xd2, 0x6d, 0x55, 0xa9, 0x55,
    0xc3, 0x34, 0x41, 0x28, 0xe0, 0x60, 0x12, 0x8e,
    0xde, 0x35, 0x23, 0xa2, 0x4a, 0x46, 0x1c, 0x89,
    0x43, 0xab, 0x08, 0x59,
]
```

## Credentials

Credentials have two possible types: `SECP256K1Credential`, and `NFTCredential`.
Each credential is paired with an Input or Operation. The order of the
credentials match the order of the inputs or operations.

## SECP256K1 Credential

A [secp256k1](/docs/api-reference/standards/cryptographic-primitives#secp256k1-addresses) credential
contains a list of 65-byte recoverable signatures.

### What SECP256K1 Credential Contains

- **`TypeID`** is the ID for this type. It is `0x00000009`.
- **`Signatures`** is an array of 65-byte recoverable signatures. The order of
  the signatures must match the input's signature indices.

### Gantt SECP256K1 Credential Specification

```text
+------------------------------+---------------------------------+
| type_id         : int        |                         4 bytes |
+-----------------+------------+---------------------------------+
| signatures      : [][65]byte |  4 + 65 * len(signatures) bytes |
+-----------------+------------+---------------------------------+
                               |  8 + 65 * len(signatures) bytes |
                               +---------------------------------+
```

### Proto SECP256K1 Credential Specification

```text
message SECP256K1Credential {
    uint32 typeID = 1;             // 4 bytes
    repeated bytes signatures = 2; // 4 bytes + 65 bytes * len(signatures)
}
```

### SECP256K1 Credential Example

Let's make a payment input with:

- **`TypeID`**: `9`
- **`signatures`**:
- `0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1e1d1f202122232425262728292a2b2c2e2d2f303132333435363738393a3b3c3d3e3f00`
- `0x404142434445464748494a4b4c4d4e4f505152535455565758595a5b5c5e5d5f606162636465666768696a6b6c6e6d6f707172737475767778797a7b7c7d7e7f00`

```text
[
    TypeID         <- 0x00000009
    Signatures <- [
        0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1e1d1f202122232425262728292a2b2c2e2d2f303132333435363738393a3b3c3d3e3f00,
        0x404142434445464748494a4b4c4d4e4f505152535455565758595a5b5c5e5d5f606162636465666768696a6b6c6e6d6f707172737475767778797a7b7c7d7e7f00,
    ]
]
=
[
    // Type ID
    0x00, 0x00, 0x00, 0x09,
    // length:
    0x00, 0x00, 0x00, 0x02,
    // sig[0]
    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
    0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
    0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
    0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1e, 0x1d, 0x1f,
    0x20, 0x21, 0x22, 0x23, 0x24, 0x25, 0x26, 0x27,
    0x28, 0x29, 0x2a, 0x2b, 0x2c, 0x2e, 0x2d, 0x2f,
    0x30, 0x31, 0x32, 0x33, 0x34, 0x35, 0x36, 0x37,
    0x38, 0x39, 0x3a, 0x3b, 0x3c, 0x3d, 0x3e, 0x3f,
    0x00,
    // sig[1]
    0x40, 0x41, 0x42, 0x43, 0x44, 0x45, 0x46, 0x47,
    0x48, 0x49, 0x4a, 0x4b, 0x4c, 0x4d, 0x4e, 0x4f,
    0x50, 0x51, 0x52, 0x53, 0x54, 0x55, 0x56, 0x57,
    0x58, 0x59, 0x5a, 0x5b, 0x5c, 0x5e, 0x5d, 0x5f,
    0x60, 0x61, 0x62, 0x63, 0x64, 0x65, 0x66, 0x67,
    0x68, 0x69, 0x6a, 0x6b, 0x6c, 0x6e, 0x6d, 0x6f,
    0x70, 0x71, 0x72, 0x73, 0x74, 0x75, 0x76, 0x77,
    0x78, 0x79, 0x7a, 0x7b, 0x7c, 0x7d, 0x7e, 0x7f,
    0x00,
]
```

## NFT Credential

An NFT credential is the same as an [secp256k1 credential](/docs/api-reference/x-chain/txn-format#secp256k1-credential) with a
different TypeID. The TypeID for an NFT credential is `0x0000000e`.

## Unsigned Transactions

Unsigned transactions contain the full content of a transaction with only the
signatures missing. Unsigned transactions have four possible types:
[`CreateAssetTx`](/docs/api-reference/x-chain/txn-format#what-unsigned-create-asset-tx-contains),
[`OperationTx`](/docs/api-reference/x-chain/txn-format#what-unsigned-operation-tx-contains),
[`ImportTx`](/docs/api-reference/x-chain/txn-format#what-unsigned-import-tx-contains),
and
[`ExportTx`](/docs/api-reference/x-chain/txn-format#what-unsigned-export-tx-contains).
They all embed
[`BaseTx`](/docs/api-reference/x-chain/txn-format#what-base-tx-contains), which
contains common fields and operations.

## Unsigned BaseTx

### What Base TX Contains

A base TX contains a `TypeID`, `NetworkID`, `BlockchainID`, `Outputs`, `Inputs`, and `Memo`.

- **`TypeID`** is the ID for this type. It is `0x00000000`.
- **`NetworkID`** is an int that defines which network this transaction is meant
  to be issued to. This value is meant to support transaction routing and is not
  designed for replay attack prevention.
- **`BlockchainID`** is a 32-byte array that defines which blockchain this
  transaction was issued to. This is used for replay attack prevention for
  transactions that could potentially be valid across network or blockchain.
- **`Outputs`** is an array of [transferable output objects](/docs/api-reference/x-chain/txn-format#transferable-output). Outputs must
  be sorted lexicographically by their serialized representation. The total
  quantity of the assets created in these outputs must be less than or equal to
  the total quantity of each asset consumed in the inputs minus the transaction
  fee.
- **`Inputs`** is an array of [transferable input objects](/docs/api-reference/x-chain/txn-format#transferable-input). Inputs must be
  sorted and unique. Inputs are sorted first lexicographically by their
  **`TxID`** and then by the **`UTXOIndex`** from low to high. If there are
  inputs that have the same **`TxID`** and **`UTXOIndex`**, then the transaction
  is invalid as this would result in a double spend.
- **`Memo`** Memo field contains arbitrary bytes, up to 256 bytes.

### Gantt Base TX Specification

```text
+--------------------------------------+-----------------------------------------+
| type_id       : int                  |                                 4 bytes |
+---------------+----------------------+-----------------------------------------+
| network_id    : int                  |                                 4 bytes |
+---------------+----------------------+-----------------------------------------+
| blockchain_id : [32]byte             |                                32 bytes |
+---------------+----------------------+-----------------------------------------+
| outputs       : []TransferableOutput |                 4 + size(outputs) bytes |
+---------------+----------------------+-----------------------------------------+
| inputs        : []TransferableInput  |                  4 + size(inputs) bytes |
+---------------+----------------------+-----------------------------------------+
| memo          : [256]byte            |                    4 + size(memo) bytes |
+---------------+----------------------+-----------------------------------------+
                          | 52 + size(outputs) + size(inputs) + size(memo) bytes |
                          +------------------------------------------------------+
```

### Proto Base TX Specification

```text
message BaseTx {
    uint32 typeID = 1;           // 04 bytes
    uint32 network_id = 2;       // 04 bytes
    bytes blockchain_id = 3;     // 32 bytes
    repeated Output outputs = 4; // 04 bytes + size(outs)
    repeated Input inputs = 5;   // 04 bytes + size(ins)
    bytes memo = 6;              // 04 bytes + size(memo)
}
```

### Base TX Example

Let's make an base TX that uses the inputs and outputs from the previous examples:

- **`TypeID`**: `0`
- **`NetworkID`**: `4`
- **`BlockchainID`**: `0xffffffffeeeeeeeeddddddddcccccccbbbbbbbbaaaaaaaa9999999988888888`
- **`Outputs`**:
  - `"Example Transferable Output as defined above"`
- **`Inputs`**:
  - `"Example Transferable Input as defined above"`
- **`Memo`**: `0x00010203`

```text
[
    TypeID       <- 0x00000000
    NetworkID    <- 0x00000004
    BlockchainID <- 0xffffffffeeeeeeeeddddddddcccccccbbbbbbbbaaaaaaaa9999999988888888
    Outputs      <- [
        0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f000000070000000000003039000000000000d431000000010000000251025c61fbcfc078f69334f834be6dd26d55a955c3344128e060128ede3523a24a461c8943ab0859
    ]
    Inputs       <- [
        0xf1e1d1c1b1a191817161514131211101f0e0d0c0b0a09080706050403020100000000005000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f0000000500000000075bcd15000000020000000700000003
    ]
    Memo <- 0x00010203
]
=
[
    // typeID
    0x00, 0x00, 0x00, 0x00,
    // networkID:
    0x00, 0x00, 0x00, 0x04,
    // blockchainID:
    0xff, 0xff, 0xff, 0xff, 0xee, 0xee, 0xee, 0xee,
    0xdd, 0xdd, 0xdd, 0xdd, 0xcc, 0xcc, 0xcc, 0xcc,
    0xbb, 0xbb, 0xbb, 0xbb, 0xaa, 0xaa, 0xaa, 0xaa,
    0x99, 0x99, 0x99, 0x99, 0x88, 0x88, 0x88, 0x88,
    // number of outputs:
    0x00, 0x00, 0x00, 0x01,
    // transferable output:
    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
    0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
    0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
    0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
    0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x30, 0x39, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0xd4, 0x31, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x02, 0x51, 0x02, 0x5c, 0x61,
    0xfb, 0xcf, 0xc0, 0x78, 0xf6, 0x93, 0x34, 0xf8,
    0x34, 0xbe, 0x6d, 0xd2, 0x6d, 0x55, 0xa9, 0x55,
    0xc3, 0x34, 0x41, 0x28, 0xe0, 0x60, 0x12, 0x8e,
    0xde, 0x35, 0x23, 0xa2, 0x4a, 0x46, 0x1c, 0x89,
    0x43, 0xab, 0x08, 0x59,
    // number of inputs:
    0x00, 0x00, 0x00, 0x01,
    // transferable input:
    0xf1, 0xe1, 0xd1, 0xc1, 0xb1, 0xa1, 0x91, 0x81,
    0x71, 0x61, 0x51, 0x41, 0x31, 0x21, 0x11, 0x01,
    0xf0, 0xe0, 0xd0, 0xc0, 0xb0, 0xa0, 0x90, 0x80,
    0x70, 0x60, 0x50, 0x40, 0x30, 0x20, 0x10, 0x00,
    0x00, 0x00, 0x00, 0x05, 0x00, 0x01, 0x02, 0x03,
    0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b,
    0x0c, 0x0d, 0x0e, 0x0f, 0x10, 0x11, 0x12, 0x13,
    0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1a, 0x1b,
    0x1c, 0x1d, 0x1e, 0x1f, 0x00, 0x00, 0x00, 0x05,
    0x00, 0x00, 0x00, 0x00, 0x07, 0x5b, 0xcd, 0x15,
    0x00, 0x00, 0x00, 0x02, 0x00, 0x00, 0x00, 0x07,
    0x00, 0x00, 0x00, 0x03,
    // Memo length:
    0x00, 0x00, 0x00, 0x04,
    // Memo:
    0x00, 0x01, 0x02, 0x03,
]
```

## Unsigned CreateAssetTx

### What Unsigned Create Asset TX Contains

An unsigned create asset TX contains a `BaseTx`, `Name`, `Symbol`,
`Denomination`, and `InitialStates`. The `TypeID` is `0x00000001`.

- **`BaseTx`**
- **`Name`** is a human readable string that defines the name of the asset this
  transaction will create. The name is not guaranteed to be unique. The name
  must consist of only printable ASCII characters and must be no longer than 128
  characters.
- **`Symbol`** is a human readable string that defines the symbol of the asset
  this transaction will create. The symbol is not guaranteed to be unique. The
  symbol must consist of only printable ASCII characters and must be no longer
  than 4 characters.
- **`Denomination`** is a byte that defines the divisibility of the asset this
  transaction will create. For example, the AVAX token is divisible into
  billionths. Therefore, the denomination of the AVAX token is 9. The
  denomination must be no more than 32.
- **`InitialStates`** is a variable length array that defines the feature
  extensions this asset supports, and the [initial state](/docs/api-reference/x-chain/txn-format#initial-state) of those feature
  extensions.

### Gantt Unsigned Create Asset TX Specification

```text
+----------------+----------------+--------------------------------------+
| base_tx        : BaseTx         |                  size(base_tx) bytes |
+----------------+----------------+--------------------------------------+
| name           : string         |                  2 + len(name) bytes |
+----------------+----------------+--------------------------------------+
| symbol         : string         |                2 + len(symbol) bytes |
+----------------+----------------+--------------------------------------+
| denomination   : byte           |                              1 bytes |
+----------------+----------------+--------------------------------------+
| initial_states : []InitialState |       4 + size(initial_states) bytes |
+----------------+----------------+--------------------------------------+
                                  | size(base_tx) + size(initial_states) |
                                  |  + 9 + len(name) + len(symbol) bytes |
                                  +--------------------------------------+
```

### Proto Unsigned Create Asset TX Specification

```text
message CreateAssetTx {
    BaseTx base_tx = 1;                       // size(base_tx)
    string name = 2;                          // 2 bytes + len(name)
    name symbol = 3;                          // 2 bytes + len(symbol)
    uint8 denomination = 4;                   // 1 bytes
    repeated InitialState initial_states = 5; // 4 bytes + size(initial_states)
}
```

### Unsigned Create Asset TX Example

Let's make an unsigned base TX that uses the inputs and outputs from the previous examples:

- `BaseTx`: `"Example BaseTx as defined above with ID set to 1"`
- `Name`: `Volatility Index`
- `Symbol`: `VIX`
- `Denomination`: `2`
- **`InitialStates`**:
- `"Example Initial State as defined above"`

```text
[
    BaseTx        <- 0x0000000100000004ffffffffeeeeeeeeddddddddccccccccbbbbbbbbaaaaaaaa999999998888888800000001000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f000000070000000000003039000000000000d431000000010000000251025c61fbcfc078f69334f834be6dd26d55a955c3344128e060128ede3523a24a461c8943ab085900000001f1e1d1c1b1a191817161514131211101f0e0d0c0b0a09080706050403020100000000005000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f0000000500000000075bcd150000000200000007000000030000000400010203
    Name          <- 0x0010566f6c6174696c69747920496e646578
    Symbol        <- 0x0003564958
    Denomination  <- 0x02
    InitialStates <- [
        0x0000000000000001000000070000000000003039000000000000d431000000010000000251025c61fbcfc078f69334f834be6dd26d55a955c3344128e060128ede3523a24a461c8943ab0859,
    ]
]
=
[
    // base tx:
    0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x04,
    0xff, 0xff, 0xff, 0xff, 0xee, 0xee, 0xee, 0xee,
    0xdd, 0xdd, 0xdd, 0xdd,
    0xcc, 0xcc, 0xcc, 0xcc, 0xbb, 0xbb, 0xbb, 0xbb,
    0xaa, 0xaa, 0xaa, 0xaa, 0x99, 0x99, 0x99, 0x99,
    0x88, 0x88, 0x88, 0x88, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
    0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
    0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
    0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
    0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x30, 0x39, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0xd4, 0x31, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x02, 0x51, 0x02, 0x5c, 0x61,
    0xfb, 0xcf, 0xc0, 0x78, 0xf6, 0x93, 0x34, 0xf8,
    0x34, 0xbe, 0x6d, 0xd2, 0x6d, 0x55, 0xa9, 0x55,
    0xc3, 0x34, 0x41, 0x28, 0xe0, 0x60, 0x12, 0x8e,
    0xde, 0x35, 0x23, 0xa2, 0x4a, 0x46, 0x1c, 0x89,
    0x43, 0xab, 0x08, 0x59, 0x00, 0x00, 0x00, 0x01,
    0xf1, 0xe1, 0xd1, 0xc1, 0xb1, 0xa1, 0x91, 0x81,
    0x71, 0x61, 0x51, 0x41, 0x31, 0x21, 0x11, 0x01,
    0xf0, 0xe0, 0xd0, 0xc0, 0xb0, 0xa0, 0x90, 0x80,
    0x70, 0x60, 0x50, 0x40, 0x30, 0x20, 0x10, 0x00,
    0x00, 0x00, 0x00, 0x05, 0x00, 0x01, 0x02, 0x03,
    0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b,
    0x0c, 0x0d, 0x0e, 0x0f, 0x10, 0x11, 0x12, 0x13,
    0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1a, 0x1b,
    0x1c, 0x1d, 0x1e, 0x1f, 0x00, 0x00, 0x00, 0x05,
    0x00, 0x00, 0x00, 0x00, 0x07, 0x5b, 0xcd, 0x15,
    0x00, 0x00, 0x00, 0x02, 0x00, 0x00, 0x00, 0x07,
    0x00, 0x00, 0x00, 0x03, 0x00, 0x00, 0x00, 0x04,
    0x00, 0x01, 0x02, 0x03
    // name:
    0x00, 0x10, 0x56, 0x6f, 0x6c, 0x61, 0x74, 0x69,
    0x6c, 0x69, 0x74, 0x79, 0x20, 0x49, 0x6e, 0x64,
    0x65, 0x78,
    // symbol length:
    0x00, 0x03,
    // symbol:
    0x56, 0x49, 0x58,
    // denomination:
    0x02,
    // number of InitialStates:
    0x00, 0x00, 0x00, 0x01,
    // InitialStates[0]:
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x30, 0x39, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0xd4, 0x31, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x02, 0x51, 0x02, 0x5c, 0x61,
    0xfb, 0xcf, 0xc0, 0x78, 0xf6, 0x93, 0x34, 0xf8,
    0x34, 0xbe, 0x6d, 0xd2, 0x6d, 0x55, 0xa9, 0x55,
    0xc3, 0x34, 0x41, 0x28, 0xe0, 0x60, 0x12, 0x8e,
    0xde, 0x35, 0x23, 0xa2, 0x4a, 0x46, 0x1c, 0x89,
    0x43, 0xab, 0x08, 0x59,
]
```

## Unsigned OperationTx

### What Unsigned Operation TX Contains

An unsigned operation TX contains a `BaseTx`, and `Ops`. The `TypeID` for this type is `0x00000002`.

- **`BaseTx`**
- **`Ops`** is a variable-length array of [Transferable Ops](/docs/api-reference/x-chain/txn-format#transferable-op).

### Gantt Unsigned Operation TX Specification

```text
+---------+------------------+-------------------------------------+
| base_tx : BaseTx           |                 size(base_tx) bytes |
+---------+------------------+-------------------------------------+
| ops     : []TransferableOp |                 4 + size(ops) bytes |
+---------+------------------+-------------------------------------+
                             | 4 + size(ops) + size(base_tx) bytes |
                             +-------------------------------------+
```

### Proto Unsigned Operation TX Specification

```text
message OperationTx {
    BaseTx base_tx = 1;          // size(base_tx)
    repeated TransferOp ops = 2; // 4 bytes + size(ops)
}
```

### Unsigned Operation TX Example

Let's make an unsigned operation TX that uses the inputs and outputs from the previous examples:

- `BaseTx`: `"Example BaseTx above" with TypeID set to 2`
- **`Ops`**: \[`"Example Transferable Op as defined above"`\]

```text
[
    BaseTx <- 0x0000000200000004ffffffffeeeeeeeeddddddddccccccccbbbbbbbbaaaaaaaa999999998888888800000001000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f000000070000000000003039000000000000d431000000010000000251025c61fbcfc078f69334f834be6dd26d55a955c3344128e060128ede3523a24a461c8943ab085900000001f1e1d1c1b1a191817161514131211101f0e0d0c0b0a09080706050403020100000000005000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f0000000500000000075bcd150000000200000007000000030000000400010203
    Ops <- [
        0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f00000001f1e1d1c1b1a191817161514131211101f0e0d0c0b0a090807060504030201000000000050000000d0000000200000003000000070000303900000003431100000000010000000251025c61fbcfc078f69334f834be6dd26d55a955c3344128e060128ede3523a24a461c8943ab0859,
    ]
]
=
[
    // base tx:
    0x00, 0x00, 0x00, 0x02,
    0x00, 0x00, 0x00, 0x04, 0xff, 0xff, 0xff, 0xff,
    0xee, 0xee, 0xee, 0xee, 0xdd, 0xdd, 0xdd, 0xdd,
    0xcc, 0xcc, 0xcc, 0xcc, 0xbb, 0xbb, 0xbb, 0xbb,
    0xaa, 0xaa, 0xaa, 0xaa, 0x99, 0x99, 0x99, 0x99,
    0x88, 0x88, 0x88, 0x88, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
    0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
    0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
    0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
    0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x30, 0x39, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0xd4, 0x31, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x02, 0x51, 0x02, 0x5c, 0x61,
    0xfb, 0xcf, 0xc0, 0x78, 0xf6, 0x93, 0x34, 0xf8,
    0x34, 0xbe, 0x6d, 0xd2, 0x6d, 0x55, 0xa9, 0x55,
    0xc3, 0x34, 0x41, 0x28, 0xe0, 0x60, 0x12, 0x8e,
    0xde, 0x35, 0x23, 0xa2, 0x4a, 0x46, 0x1c, 0x89,
    0x43, 0xab, 0x08, 0x59, 0x00, 0x00, 0x00, 0x01,
    0xf1, 0xe1, 0xd1, 0xc1, 0xb1, 0xa1, 0x91, 0x81,
    0x71, 0x61, 0x51, 0x41, 0x31, 0x21, 0x11, 0x01,
    0xf0, 0xe0, 0xd0, 0xc0, 0xb0, 0xa0, 0x90, 0x80,
    0x70, 0x60, 0x50, 0x40, 0x30, 0x20, 0x10, 0x00,
    0x00, 0x00, 0x00, 0x05, 0x00, 0x01, 0x02, 0x03,
    0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b,
    0x0c, 0x0d, 0x0e, 0x0f, 0x10, 0x11, 0x12, 0x13,
    0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1a, 0x1b,
    0x1c, 0x1d, 0x1e, 0x1f, 0x00, 0x00, 0x00, 0x05,
    0x00, 0x00, 0x00, 0x00, 0x07, 0x5b, 0xcd, 0x15,
    0x00, 0x00, 0x00, 0x02, 0x00, 0x00, 0x00, 0x07,
    0x00, 0x00, 0x00, 0x03, 0x00, 0x00, 0x00, 0x04,
    0x00, 0x01, 0x02, 0x03
    // number of operations:
    0x00, 0x00, 0x00, 0x01,
    // transfer operation:
    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
    0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
    0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
    0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
    0x00, 0x00, 0x00, 0x01, 0xf1, 0xe1, 0xd1, 0xc1,
    0xb1, 0xa1, 0x91, 0x81, 0x71, 0x61, 0x51, 0x41,
    0x31, 0x21, 0x11, 0x01, 0xf0, 0xe0, 0xd0, 0xc0,
    0xb0, 0xa0, 0x90, 0x80, 0x70, 0x60, 0x50, 0x40,
    0x30, 0x20, 0x10, 0x00, 0x00, 0x00, 0x00, 0x05,
    0x00, 0x00, 0x00, 0x0d, 0x00, 0x00, 0x00, 0x02,
    0x00, 0x00, 0x00, 0x03, 0x00, 0x00, 0x00, 0x07,
    0x00, 0x00, 0x30, 0x39, 0x00, 0x00, 0x00, 0x03,
    0x43, 0x11, 0x00, 0x00, 0x00, 0x00, 0x01, 0x00,
    0x00, 0x00, 0x02, 0x51, 0x02, 0x5c, 0x61, 0xfb,
    0xcf, 0xc0, 0x78, 0xf6, 0x93, 0x34, 0xf8, 0x34,
    0xbe, 0x6d, 0xd2, 0x6d, 0x55, 0xa9, 0x55, 0xc3,
    0x34, 0x41, 0x28, 0xe0, 0x60, 0x12, 0x8e, 0xde,
    0x35, 0x23, 0xa2, 0x4a, 0x46, 0x1c, 0x89, 0x43,
    0xab, 0x08, 0x59,
]
```

## Unsigned ImportTx

### What Unsigned Import TX Contains

An unsigned import TX contains a `BaseTx`, `SourceChain` and `Ins`. \* The `TypeID`for this type is `0x00000003`.

- **`BaseTx`**
- **`SourceChain`** is a 32-byte source blockchain ID.
- **`Ins`** is a variable length array of [Transferable Inputs](/docs/api-reference/x-chain/txn-format#transferable-input).

### Gantt Unsigned Import TX Specification

```text
+---------+----------------------+-----------------------------+
| base_tx : BaseTx               |         size(base_tx) bytes |
+-----------------+--------------+-----------------------------+
| source_chain    : [32]byte     |                    32 bytes |
+---------+----------------------+-----------------------------+
| ins     : []TransferIn         |         4 + size(ins) bytes |
+---------+----------------------+-----------------------------+
                        | 36 + size(ins) + size(base_tx) bytes |
                        +--------------------------------------+
```

### Proto Unsigned Import TX Specification

```text
message ImportTx {
    BaseTx base_tx = 1;          // size(base_tx)
    bytes source_chain = 2;      // 32 bytes
    repeated TransferIn ins = 3; // 4 bytes + size(ins)
}
```

### Unsigned Import TX Example

Let's make an unsigned import TX that uses the inputs from the previous examples:

- `BaseTx`: `"Example BaseTx as defined above"`, but with `TypeID` set to `3`
- `SourceChain`: `0x0000000000000000000000000000000000000000000000000000000000000000`
- `Ins`: `"Example SECP256K1 Transfer Input as defined above"`

```text
[
    BaseTx        <- 0x0000000300000004ffffffffeeeeeeeeddddddddccccccccbbbbbbbbaaaaaaaa999999998888888800000001000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f000000070000000000003039000000000000d431000000010000000251025c61fbcfc078f69334f834be6dd26d55a955c3344128e060128ede3523a24a461c8943ab085900000001f1e1d1c1b1a191817161514131211101f0e0d0c0b0a09080706050403020100000000005000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f0000000500000000075bcd150000000200000007000000030000000400010203
    SourceChain <- 0x0000000000000000000000000000000000000000000000000000000000000000
    Ins <- [
        f1e1d1c1b1a191817161514131211101f0e0d0c0b0a09080706050403020100000000005000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f0000000500000000075bcd15000000020000000300000007,
    ]
]
=
[
    // base tx:
    0x00, 0x00, 0x00, 0x03,
    0x00, 0x00, 0x00, 0x04, 0xff, 0xff, 0xff, 0xff,
    0xee, 0xee, 0xee, 0xee, 0xdd, 0xdd, 0xdd, 0xdd,
    0xcc, 0xcc, 0xcc, 0xcc, 0xbb, 0xbb, 0xbb, 0xbb,
    0xaa, 0xaa, 0xaa, 0xaa, 0x99, 0x99, 0x99, 0x99,
    0x88, 0x88, 0x88, 0x88, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
    0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
    0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
    0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
    0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x30, 0x39, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0xd4, 0x31, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x02, 0x51, 0x02, 0x5c, 0x61,
    0xfb, 0xcf, 0xc0, 0x78, 0xf6, 0x93, 0x34, 0xf8,
    0x34, 0xbe, 0x6d, 0xd2, 0x6d, 0x55, 0xa9, 0x55,
    0xc3, 0x34, 0x41, 0x28, 0xe0, 0x60, 0x12, 0x8e,
    0xde, 0x35, 0x23, 0xa2, 0x4a, 0x46, 0x1c, 0x89,
    0x43, 0xab, 0x08, 0x59, 0x00, 0x00, 0x00, 0x01,
    0xf1, 0xe1, 0xd1, 0xc1, 0xb1, 0xa1, 0x91, 0x81,
    0x71, 0x61, 0x51, 0x41, 0x31, 0x21, 0x11, 0x01,
    0xf0, 0xe0, 0xd0, 0xc0, 0xb0, 0xa0, 0x90, 0x80,
    0x70, 0x60, 0x50, 0x40, 0x30, 0x20, 0x10, 0x00,
    0x00, 0x00, 0x00, 0x05, 0x00, 0x01, 0x02, 0x03,
    0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b,
    0x0c, 0x0d, 0x0e, 0x0f, 0x10, 0x11, 0x12, 0x13,
    0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1a, 0x1b,
    0x1c, 0x1d, 0x1e, 0x1f, 0x00, 0x00, 0x00, 0x05,
    0x00, 0x00, 0x00, 0x00, 0x07, 0x5b, 0xcd, 0x15,
    0x00, 0x00, 0x00, 0x02, 0x00, 0x00, 0x00, 0x07,
    0x00, 0x00, 0x00, 0x03, 0x00, 0x00, 0x00, 0x04,
    0x00, 0x01, 0x02, 0x03
    // source chain:
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    // input count:
    0x00, 0x00, 0x00, 0x01,
    // txID:
    0xf1, 0xe1, 0xd1, 0xc1, 0xb1, 0xa1, 0x91, 0x81,
    0x71, 0x61, 0x51, 0x41, 0x31, 0x21, 0x11, 0x01,
    0xf0, 0xe0, 0xd0, 0xc0, 0xb0, 0xa0, 0x90, 0x80,
    0x70, 0x60, 0x50, 0x40, 0x30, 0x20, 0x10, 0x00,
    // utxoIndex:
    0x00, 0x00, 0x00, 0x05,
    // assetID:
    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
    0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
    0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
    0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
    // input:
    0x00, 0x00, 0x00, 0x05, 0x00, 0x00, 0x00, 0x00,
    0x07, 0x5b, 0xcd, 0x15, 0x00, 0x00, 0x00, 0x02,
    0x00, 0x00, 0x00, 0x03, 0x00, 0x00, 0x00, 0x07,
]
```

## Unsigned ExportTx

### What Unsigned Export TX Contains

An unsigned export TX contains a `BaseTx`, `DestinationChain`, and `Outs`. The
`TypeID` for this type is `0x00000004`.

- **`DestinationChain`** is the 32 byte ID of the chain where the funds are being exported to.
- **`Outs`** is a variable length array of [Transferable Outputs](/docs/api-reference/x-chain/txn-format#transferable-output).

### Gantt Unsigned Export TX Specification

```text
+-------------------+---------------+--------------------------------------+
| base_tx           : BaseTx        |                  size(base_tx) bytes |
+-------------------+---------------+--------------------------------------+
| destination_chain : [32]byte      |                             32 bytes |
+-------------------+---------------+--------------------------------------+
| outs              : []TransferOut |                 4 + size(outs) bytes |
+-------------------+---------------+--------------------------------------+
                          | 36 + size(outs) + size(base_tx) bytes |
                          +---------------------------------------+
```

### Proto Unsigned Export TX Specification

```text
message ExportTx {
    BaseTx base_tx = 1;            // size(base_tx)
    bytes destination_chain = 2;   // 32 bytes
    repeated TransferOut outs = 3; // 4 bytes + size(outs)
}
```

### Unsigned Export TX Example

Let's make an unsigned export TX that uses the outputs from the previous examples:

- `BaseTx`: `"Example BaseTx as defined above"`, but with `TypeID` set to `4`
- `DestinationChain`: `0x0000000000000000000000000000000000000000000000000000000000000000`
- `Outs`: `"Example SECP256K1 Transfer Output as defined above"`

```text
[
    BaseTx           <- 0x0000000400000004ffffffffeeeeeeeeddddddddccccccccbbbbbbbbaaaaaaaa999999998888888800000001000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f000000070000000000003039000000000000d431000000010000000251025c61fbcfc078f69334f834be6dd26d55a955c3344128e060128ede3523a24a461c8943ab085900000001f1e1d1c1b1a191817161514131211101f0e0d0c0b0a09080706050403020100000000005000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f0000000500000000075bcd150000000200000007000000030000000400010203
    DestinationChain <- 0x0000000000000000000000000000000000000000000000000000000000000000
    Outs <- [
        000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f000000070000000000003039000000000000d431000000010000000251025c61fbcfc078f69334f834be6dd26d55a955c3344128e060128ede3523a24a461c8943ab0859,
    ]
]
=
[
    // base tx:
    0x00, 0x00, 0x00, 0x04
    0x00, 0x00, 0x00, 0x04, 0xff, 0xff, 0xff, 0xff,
    0xee, 0xee, 0xee, 0xee, 0xdd, 0xdd, 0xdd, 0xdd,
    0xcc, 0xcc, 0xcc, 0xcc, 0xbb, 0xbb, 0xbb, 0xbb,
    0xaa, 0xaa, 0xaa, 0xaa, 0x99, 0x99, 0x99, 0x99,
    0x88, 0x88, 0x88, 0x88, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
    0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
    0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
    0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
    0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x30, 0x39, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0xd4, 0x31, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x02, 0x51, 0x02, 0x5c, 0x61,
    0xfb, 0xcf, 0xc0, 0x78, 0xf6, 0x93, 0x34, 0xf8,
    0x34, 0xbe, 0x6d, 0xd2, 0x6d, 0x55, 0xa9, 0x55,
    0xc3, 0x34, 0x41, 0x28, 0xe0, 0x60, 0x12, 0x8e,
    0xde, 0x35, 0x23, 0xa2, 0x4a, 0x46, 0x1c, 0x89,
    0x43, 0xab, 0x08, 0x59, 0x00, 0x00, 0x00, 0x01,
    0xf1, 0xe1, 0xd1, 0xc1, 0xb1, 0xa1, 0x91, 0x81,
    0x71, 0x61, 0x51, 0x41, 0x31, 0x21, 0x11, 0x01,
    0xf0, 0xe0, 0xd0, 0xc0, 0xb0, 0xa0, 0x90, 0x80,
    0x70, 0x60, 0x50, 0x40, 0x30, 0x20, 0x10, 0x00,
    0x00, 0x00, 0x00, 0x05, 0x00, 0x01, 0x02, 0x03,
    0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b,
    0x0c, 0x0d, 0x0e, 0x0f, 0x10, 0x11, 0x12, 0x13,
    0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1a, 0x1b,
    0x1c, 0x1d, 0x1e, 0x1f, 0x00, 0x00, 0x00, 0x05,
    0x00, 0x00, 0x00, 0x00, 0x07, 0x5b, 0xcd, 0x15,
    0x00, 0x00, 0x00, 0x02, 0x00, 0x00, 0x00, 0x07,
    0x00, 0x00, 0x00, 0x03, 0x00, 0x00, 0x00, 0x04,
    0x00, 0x01, 0x02, 0x03
    // destination_chain:
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    // outs[] count:
    0x00, 0x00, 0x00, 0x01,
    // assetID:
    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
    0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
    0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
    0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
    // output:
    0x00, 0x00, 0x00, 0x07,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x30, 0x39,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xd4, 0x31,
    0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x02,
    0x51, 0x02, 0x5c, 0x61, 0xfb, 0xcf, 0xc0, 0x78,
    0xf6, 0x93, 0x34, 0xf8, 0x34, 0xbe, 0x6d, 0xd2,
    0x6d, 0x55, 0xa9, 0x55, 0xc3, 0x34, 0x41, 0x28,
    0xe0, 0x60, 0x12, 0x8e, 0xde, 0x35, 0x23, 0xa2,
    0x4a, 0x46, 0x1c, 0x89, 0x43, 0xab, 0x08, 0x59,
]
```

## Signed Transaction

A signed transaction is an unsigned transaction with the addition of an array of [credentials](/docs/api-reference/x-chain/txn-format#credentials).

### What Signed Transaction Contains

A signed transaction contains a `CodecID`, `UnsignedTx`, and `Credentials`.

- **`CodecID`** The only current valid codec id is `00 00`.
- **`UnsignedTx`** is an unsigned transaction, as described above.
- **`Credentials`** is an array of
  [credentials](/docs/api-reference/x-chain/txn-format#credentials). Each credential
  will be paired with the input in the same index at this credential.

### Gantt Signed Transaction Specification

```text
+---------------------+--------------+------------------------------------------------+
| codec_id            : uint16       |                                        2 bytes |
+---------------------+--------------+------------------------------------------------+
| unsigned_tx         : UnsignedTx   |                        size(unsigned_tx) bytes |
+---------------------+--------------+------------------------------------------------+
| credentials         : []Credential |                    4 + size(credentials) bytes |
+---------------------+--------------+------------------------------------------------+
                                     | 6 + size(unsigned_tx) + len(credentials) bytes |
                                     +------------------------------------------------+
```

### Proto Signed Transaction Specification

```text
message Tx {
    uint16 codec_id = 1;                 // 2 bytes
    UnsignedTx unsigned_tx = 2;          // size(unsigned_tx)
    repeated Credential credentials = 3; // 4 bytes + size(credentials)
}
```

### Signed Transaction Example

Let's make a signed transaction that uses the unsigned transaction and
credentials from the previous examples.

- **`CodecID`**: `0`
- **`UnsignedTx`**: `0x0000000100000004ffffffffeeeeeeeeddddddddccccccccbbbbbbbbaaaaaaaa999999998888888800000001000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f000000070000000000003039000000000000d431000000010000000251025c61fbcfc078f69334f834be6dd26d55a955c3344128e060128ede3523a24a461c8943ab085900000001f1e1d1c1b1a191817161514131211101f0e0d0c0b0a09080706050403020100000000005000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f0000000500000000075bcd150000000200000007000000030000000400010203`
- **`Credentials`** `0x0000000900000002000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1e1d1f202122232425262728292a2b2c2e2d2f303132333435363738393a3b3c3d3e3f00404142434445464748494a4b4c4d4e4f505152535455565758595a5b5c5e5d5f606162636465666768696a6b6c6e6d6f707172737475767778797a7b7c7d7e7f00`

```text
[
    CodecID     <- 0x0000
    UnsignedTx  <- 0x0000000100000004ffffffffeeeeeeeeddddddddccccccccbbbbbbbbaaaaaaaa999999998888888800000001000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f000000070000000000003039000000000000d431000000010000000251025c61fbcfc078f69334f834be6dd26d55a955c3344128e060128ede3523a24a461c8943ab085900000001f1e1d1c1b1a191817161514131211101f0e0d0c0b0a09080706050403020100000000005000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f0000000500000000075bcd150000000200000007000000030000000400010203
    Credentials <- [
        0x0000000900000002000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1e1d1f202122232425262728292a2b2c2e2d2f303132333435363738393a3b3c3d3e3f00404142434445464748494a4b4c4d4e4f505152535455565758595a5b5c5e5d5f606162636465666768696a6b6c6e6d6f707172737475767778797a7b7c7d7e7f00,
    ]
]
=
[
    // Codec ID
    0x00, 0x00,
    // unsigned transaction:
    0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x04,
    0xff, 0xff, 0xff, 0xff, 0xee, 0xee, 0xee, 0xee,
    0xdd, 0xdd, 0xdd, 0xdd, 0xcc, 0xcc, 0xcc, 0xcc,
    0xbb, 0xbb, 0xbb, 0xbb, 0xaa, 0xaa, 0xaa, 0xaa,
    0x99, 0x99, 0x99, 0x99, 0x88, 0x88, 0x88, 0x88,
    0x00, 0x00, 0x00, 0x01, 0x00, 0x01, 0x02, 0x03,
    0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b,
    0x0c, 0x0d, 0x0e, 0x0f, 0x10, 0x11, 0x12, 0x13,
    0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1a, 0x1b,
    0x1c, 0x1d, 0x1e, 0x1f, 0x00, 0x00, 0x00, 0x07,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x30, 0x39,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xd4, 0x31,
    0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x02,
    0x51, 0x02, 0x5c, 0x61, 0xfb, 0xcf, 0xc0, 0x78,
    0xf6, 0x93, 0x34, 0xf8, 0x34, 0xbe, 0x6d, 0xd2,
    0x6d, 0x55, 0xa9, 0x55, 0xc3, 0x34, 0x41, 0x28,
    0xe0, 0x60, 0x12, 0x8e, 0xde, 0x35, 0x23, 0xa2,
    0x4a, 0x46, 0x1c, 0x89, 0x43, 0xab, 0x08, 0x59,
    0x00, 0x00, 0x00, 0x01, 0xf1, 0xe1, 0xd1, 0xc1,
    0xb1, 0xa1, 0x91, 0x81, 0x71, 0x61, 0x51, 0x41,
    0x31, 0x21, 0x11, 0x01, 0xf0, 0xe0, 0xd0, 0xc0,
    0xb0, 0xa0, 0x90, 0x80, 0x70, 0x60, 0x50, 0x40,
    0x30, 0x20, 0x10, 0x00, 0x00, 0x00, 0x00, 0x05,
    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
    0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
    0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
    0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
    0x00, 0x00, 0x00, 0x05, 0x00, 0x00, 0x00, 0x00,
    0x07, 0x5b, 0xcd, 0x15, 0x00, 0x00, 0x00, 0x02,
    0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x03,
    0x00, 0x00, 0x00, 0x04, 0x00, 0x01, 0x02, 0x03
    // number of credentials:
    0x00, 0x00, 0x00, 0x01,
    // credential[0]:
    0x00, 0x00, 0x00, 0x09, 0x00, 0x00, 0x00, 0x02,
    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
    0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
    0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
    0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1e, 0x1d, 0x1f,
    0x20, 0x21, 0x22, 0x23, 0x24, 0x25, 0x26, 0x27,
    0x28, 0x29, 0x2a, 0x2b, 0x2c, 0x2e, 0x2d, 0x2f,
    0x30, 0x31, 0x32, 0x33, 0x34, 0x35, 0x36, 0x37,
    0x38, 0x39, 0x3a, 0x3b, 0x3c, 0x3d, 0x3e, 0x3f,
    0x00, 0x40, 0x41, 0x42, 0x43, 0x44, 0x45, 0x46,
    0x47, 0x48, 0x49, 0x4a, 0x4b, 0x4c, 0x4d, 0x4e,
    0x4f, 0x50, 0x51, 0x52, 0x53, 0x54, 0x55, 0x56,
    0x57, 0x58, 0x59, 0x5a, 0x5b, 0x5c, 0x5e, 0x5d,
    0x5f, 0x60, 0x61, 0x62, 0x63, 0x64, 0x65, 0x66,
    0x67, 0x68, 0x69, 0x6a, 0x6b, 0x6c, 0x6e, 0x6d,
    0x6f, 0x70, 0x71, 0x72, 0x73, 0x74, 0x75, 0x76,
    0x77, 0x78, 0x79, 0x7a, 0x7b, 0x7c, 0x7d, 0x7e,
    0x7f, 0x00,
```

## UTXO

A UTXO is a standalone representation of a transaction output.

### What UTXO Contains

A UTXO contains a `CodecID`, `TxID`, `UTXOIndex`, `AssetID`, and `Output`.

- **`CodecID`** The only valid `CodecID` is `00 00`
- **`TxID`** is a 32-byte transaction ID. Transaction IDs are calculated by
  taking sha256 of the bytes of the signed transaction.
- **`UTXOIndex`** is an int that specifies which output in the transaction
  specified by **`TxID`** that this UTXO was created by.
- **`AssetID`** is a 32-byte array that defines which asset this UTXO
  references.
- **`Output`** is the output object that created this UTXO. The serialization of
  Outputs was defined above. Valid output types are [SECP Mint Output](/docs/api-reference/x-chain/txn-format#secp256k1-mint-output), [SECP Transfer Output](/docs/api-reference/x-chain/txn-format#secp256k1-transfer-output),
  [NFT Mint Output](/docs/api-reference/x-chain/txn-format#nft-mint-output), [NFT Transfer Output](/docs/api-reference/x-chain/txn-format#nft-transfer-output).

### Gantt UTXO Specification

```text
+--------------+----------+-------------------------+
| codec_id     : uint16   |                 2 bytes |
+--------------+----------+-------------------------+
| tx_id        : [32]byte |                32 bytes |
+--------------+----------+-------------------------+
| output_index : int      |                 4 bytes |
+--------------+----------+-------------------------+
| asset_id     : [32]byte |                32 bytes |
+--------------+----------+-------------------------+
| output       : Output   |      size(output) bytes |
+--------------+----------+-------------------------+
                          | 70 + size(output) bytes |
                          +-------------------------+
```

### Proto UTXO Specification

```text
message Utxo {
    uint16 codec_id = 1;     // 02 bytes
    bytes tx_id = 2;         // 32 bytes
    uint32 output_index = 3; // 04 bytes
    bytes asset_id = 4;      // 32 bytes
    Output output = 5;       // size(output)
}
```

### UTXO Examples

Let's make a UTXO with a SECP Mint Output:

- **`CodecID`**: `0`
- **`TxID`**: `0x47c92ed62d18e3cccda512f60a0d5b1e939b6ab73fb2d011e5e306e79bd0448f`
- **`UTXOIndex`**: `0` = `0x00000001`
- **`AssetID`**: `0x47c92ed62d18e3cccda512f60a0d5b1e939b6ab73fb2d011e5e306e79bd0448f`
- **`Output`**: `0x00000006000000000000000000000001000000013cb7d3842e8cee6a0ebd09f1fe884f6861e1b29c6276aa2a`

```text
[
    CodecID   <- 0x0000
    TxID      <- 0x47c92ed62d18e3cccda512f60a0d5b1e939b6ab73fb2d011e5e306e79bd0448f
    UTXOIndex <- 0x00000001
    AssetID   <- 0x47c92ed62d18e3cccda512f60a0d5b1e939b6ab73fb2d011e5e306e79bd0448f
    Output    <- 00000006000000000000000000000001000000013cb7d3842e8cee6a0ebd09f1fe884f6861e1b29c6276aa2a
]
=
[
    // codecID:
    0x00, 0x00,
    // txID:
    0x47, 0xc9, 0x2e, 0xd6, 0x2d, 0x18, 0xe3, 0xcc,
    0xcd, 0xa5, 0x12, 0xf6, 0x0a, 0x0d, 0x5b, 0x1e,
    0x93, 0x9b, 0x6a, 0xb7, 0x3f, 0xb2, 0xd0, 0x11,
    0xe5, 0xe3, 0x06, 0xe7, 0x9b, 0xd0, 0x44, 0x8f,
    // utxo index:
    0x00, 0x00, 0x00, 0x01,
    // assetID:
    0x47, 0xc9, 0x2e, 0xd6, 0x2d, 0x18, 0xe3, 0xcc,
    0xcd, 0xa5, 0x12, 0xf6, 0x0a, 0x0d, 0x5b, 0x1e,
    0x93, 0x9b, 0x6a, 0xb7, 0x3f, 0xb2, 0xd0, 0x11,
    0xe5, 0xe3, 0x06, 0xe7, 0x9b, 0xd0, 0x44, 0x8f,
    // secp mint output:
    0x00, 0x00, 0x00, 0x06, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x01, 0x3c, 0xb7, 0xd3, 0x84,
    0x2e, 0x8c, 0xee, 0x6a, 0x0e, 0xbd, 0x09, 0xf1,
    0xfe, 0x88, 0x4f, 0x68, 0x61, 0xe1, 0xb2, 0x9c,
    0x62, 0x76, 0xaa, 0x2a,
]
```

Let's make a UTXO with a SECP Transfer Output from the signed transaction created above:

- **`CodecID`**: `0`
- **`TxID`**: `0xf966750f438867c3c9828ddcdbe660e21ccdbb36a9276958f011ba472f75d4e7`
- **`UTXOIndex`**: `0` = `0x00000000`
- **`AssetID`**: `0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f`
- **`Output`**: `"Example SECP256K1 Transferable Output as defined above"`

```text
[
    CodecID   <- 0x0000
    TxID      <- 0xf966750f438867c3c9828ddcdbe660e21ccdbb36a9276958f011ba472f75d4e7
    UTXOIndex <- 0x00000000
    AssetID   <- 0x000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f
    Output    <-     0x000000070000000000003039000000000000d431000000010000000251025c61fbcfc078f69334f834be6dd26d55a955c3344128e060128ede3523a24a461c8943ab0859
]
=
[
    // codecID:
    0x00, 0x00,
    // txID:
    0xf9, 0x66, 0x75, 0x0f, 0x43, 0x88, 0x67, 0xc3,
    0xc9, 0x82, 0x8d, 0xdc, 0xdb, 0xe6, 0x60, 0xe2,
    0x1c, 0xcd, 0xbb, 0x36, 0xa9, 0x27, 0x69, 0x58,
    0xf0, 0x11, 0xba, 0x47, 0x2f, 0x75, 0xd4, 0xe7,
    // utxo index:
    0x00, 0x00, 0x00, 0x00,
    // assetID:
    0x00, 0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07,
    0x08, 0x09, 0x0a, 0x0b, 0x0c, 0x0d, 0x0e, 0x0f,
    0x10, 0x11, 0x12, 0x13, 0x14, 0x15, 0x16, 0x17,
    0x18, 0x19, 0x1a, 0x1b, 0x1c, 0x1d, 0x1e, 0x1f,
    // secp transfer output:
    0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x30, 0x39, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0xd4, 0x31, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x02, 0x00, 0x01, 0x02, 0x03,
    0x04, 0x05, 0x06, 0x07, 0x08, 0x09, 0x0a, 0x0b,
    0x0c, 0x0d, 0x0e, 0x0f, 0x10, 0x11, 0x12, 0x13,
    0x14, 0x15, 0x16, 0x17, 0x18, 0x19, 0x1a, 0x1b,
    0x1c, 0x1d, 0x1e, 0x1f, 0x20, 0x21, 0x22, 0x23,
    0x24, 0x25, 0x26, 0x27,
]
```

Let's make a UTXO with an NFT Mint Output:

- **`CodecID`**: `0`
- **`TxID`**: `0x03c686efe8d80c519f356929f6da945f7ff90378f0044bb0e1a5d6c1ad06bae7`
- **`UTXOIndex`**: `0` = `0x00000001`
- **`AssetID`**: `0x03c686efe8d80c519f356929f6da945f7ff90378f0044bb0e1a5d6c1ad06bae7`
- **`Output`**: `0x0000000a00000000000000000000000000000001000000013cb7d3842e8cee6a0ebd09f1fe884f6861e1b29c6276aa2a`

```text
[
    CodecID   <- 0x0000
    TxID      <- 0x03c686efe8d80c519f356929f6da945f7ff90378f0044bb0e1a5d6c1ad06bae7
    UTXOIndex <- 0x00000001
    AssetID   <- 0x03c686efe8d80c519f356929f6da945f7ff90378f0044bb0e1a5d6c1ad06bae7
    Output    <- 0000000a00000000000000000000000000000001000000013cb7d3842e8cee6a0ebd09f1fe884f6861e1b29c6276aa2a
]
=
[
    // codecID:
    0x00, 0x00,
    // txID:
    0x03, 0xc6, 0x86, 0xef, 0xe8, 0xd8, 0x0c, 0x51,
    0x9f, 0x35, 0x69, 0x29, 0xf6, 0xda, 0x94, 0x5f,
    0x7f, 0xf9, 0x03, 0x78, 0xf0, 0x04, 0x4b, 0xb0,
    0xe1, 0xa5, 0xd6, 0xc1, 0xad, 0x06, 0xba, 0xe7,
    // utxo index:
    0x00, 0x00, 0x00, 0x01,
    // assetID:
    0x03, 0xc6, 0x86, 0xef, 0xe8, 0xd8, 0x0c, 0x51,
    0x9f, 0x35, 0x69, 0x29, 0xf6, 0xda, 0x94, 0x5f,
    0x7f, 0xf9, 0x03, 0x78, 0xf0, 0x04, 0x4b, 0xb0,
    0xe1, 0xa5, 0xd6, 0xc1, 0xad, 0x06, 0xba, 0xe7,
    // nft mint output:
    0x00, 0x00, 0x00, 0x0a, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x01,
    0x3c, 0xb7, 0xd3, 0x84, 0x2e, 0x8c, 0xee, 0x6a,
    0x0e, 0xbd, 0x09, 0xf1, 0xfe, 0x88, 0x4f, 0x68,
    0x61, 0xe1, 0xb2, 0x9c, 0x62, 0x76, 0xaa, 0x2a,
]
```

Let's make a UTXO with an NFT Transfer Output:

- **`CodecID`**: `0`
- **`TxID`**: `0xa68f794a7de7bdfc5db7ba5b73654304731dd586bbf4a6d7b05be6e49de2f936`
- **`UTXOIndex`**: `0` = `0x00000001`
- **`AssetID`**: `0x03c686efe8d80c519f356929f6da945f7ff90378f0044bb0e1a5d6c1ad06bae7`
- **`Output`**: `0x0000000b000000000000000b4e4654205061796c6f6164000000000000000000000001000000013cb7d3842e8cee6a0ebd09f1fe884f6861e1b29c6276aa2a`

```text
[
    CodecID   <- 0x0000
    TxID      <- 0xa68f794a7de7bdfc5db7ba5b73654304731dd586bbf4a6d7b05be6e49de2f936
    UTXOIndex <- 0x00000001
    AssetID   <- 0x03c686efe8d80c519f356929f6da945f7ff90378f0044bb0e1a5d6c1ad06bae7
    Output    <- 0000000b000000000000000b4e4654205061796c6f6164000000000000000000000001000000013cb7d3842e8cee6a0ebd09f1fe884f6861e1b29c6276aa2a
]
=
[
    // codecID:
    0x00, 0x00,
    // txID:
    0xa6, 0x8f, 0x79, 0x4a, 0x7d, 0xe7, 0xbd, 0xfc,
    0x5d, 0xb7, 0xba, 0x5b, 0x73, 0x65, 0x43, 0x04,
    0x73, 0x1d, 0xd5, 0x86, 0xbb, 0xf4, 0xa6, 0xd7,
    0xb0, 0x5b, 0xe6, 0xe4, 0x9d, 0xe2, 0xf9, 0x36,
    // utxo index:
    0x00, 0x00, 0x00, 0x01,
    // assetID:
    0x03, 0xc6, 0x86, 0xef, 0xe8, 0xd8, 0x0c, 0x51,
    0x9f, 0x35, 0x69, 0x29, 0xf6, 0xda, 0x94, 0x5f,
    0x7f, 0xf9, 0x03, 0x78, 0xf0, 0x04, 0x4b, 0xb0,
    0xe1, 0xa5, 0xd6, 0xc1, 0xad, 0x06, 0xba, 0xe7,
    // nft transfer output:
    0x00, 0x00, 0x00, 0x0b, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x0b, 0x4e, 0x46, 0x54, 0x20,
    0x50, 0x61, 0x79, 0x6c, 0x6f, 0x61, 0x64, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x01, 0x00, 0x00, 0x00, 0x01, 0x3c,
    0xb7, 0xd3, 0x84, 0x2e, 0x8c, 0xee, 0x6a, 0x0e,
    0xbd, 0x09, 0xf1, 0xfe, 0x88, 0x4f, 0x68, 0x61,
    0xe1, 0xb2, 0x9c, 0x62, 0x76, 0xaa, 0x2a,
]
```

## GenesisAsset

An asset to be issued in an instance of the AVM's Genesis

### What GenesisAsset Contains

An instance of a GenesisAsset contains an `Alias`, `NetworkID`, `BlockchainID`,
`Outputs`, `Inputs`, `Memo`, `Name`, `Symbol`, `Denomination`, and
`InitialStates`.

- **`Alias`** is the alias for this asset.
- **`NetworkID`** defines which network this transaction is meant to be issued
  to. This value is meant to support transaction routing and is not designed for
  replay attack prevention.
- **`BlockchainID`** is the ID (32-byte array) that defines which blockchain
  this transaction was issued to. This is used for replay attack prevention for
  transactions that could potentially be valid across network or blockchain.
- **`Outputs`** is an array of [transferable output objects](/docs/api-reference/x-chain/txn-format#transferable-output). Outputs must
  be sorted lexicographically by their serialized representation. The total
  quantity of the assets created in these outputs must be less than or equal to
  the total quantity of each asset consumed in the inputs minus the transaction
  fee.
- **`Inputs`** is an array of [transferable input objects](/docs/api-reference/x-chain/txn-format#transferable-input). Inputs must be
  sorted and unique. Inputs are sorted first lexicographically by their
  **`TxID`** and then by the **`UTXOIndex`** from low to high. If there are
  inputs that have the same **`TxID`** and **`UTXOIndex`**, then the transaction
  is invalid as this would result in a double spend.
- **`Memo`** is a memo field that contains arbitrary bytes, up to 256 bytes.
- **`Name`** is a human readable string that defines the name of the asset this
  transaction will create. The name is not guaranteed to be unique. The name
  must consist of only printable ASCII characters and must be no longer than 128
  characters.
- **`Symbol`** is a human readable string that defines the symbol of the asset
  this transaction will create. The symbol is not guaranteed to be unique. The
  symbol must consist of only printable ASCII characters and must be no longer
  than 4 characters.
- **`Denomination`** is a byte that defines the divisibility of the asset this
  transaction will create. For example, the AVAX token is divisible into
  billionths. Therefore, the denomination of the AVAX token is 9. The
  denomination must be no more than 32.
- **`InitialStates`** is a variable length array that defines the feature
  extensions this asset supports, and the [initial state](/docs/api-reference/x-chain/txn-format#initial-state) of those feature
  extensions.

### Gantt GenesisAsset Specification

````text
+----------------+----------------------+--------------------------------+
| alias          : string               |           2 + len(alias) bytes |
+----------------+----------------------+--------------------------------+
| network_id     : int                  |                        4 bytes |
+----------------+----------------------+--------------------------------+
| blockchain_id  : [32]byte             |                       32 bytes |
+----------------+----------------------+--------------------------------+
| outputs        : []TransferableOutput |        4 + size(outputs) bytes |
+----------------+----------------------+--------------------------------+
| inputs         : []TransferableInput  |         4 + size(inputs) bytes |
+----------------+----------------------+--------------------------------+
| memo           : [256]byte            |           4 + size(memo) bytes |
+----------------+----------------------+--------------------------------+
| name           : string               |            2 + len(name) bytes |
+----------------+----------------------+--------------------------------+
| symbol         : string               |          2 + len(symbol) bytes |
+----------------+----------------------+--------------------------------+
| denomination   : byte                 |                        1 bytes |
+----------------+----------------------+--------------------------------+
| initial_states : []InitialState       | 4 + size(initial_states) bytes |
+----------------+----------------------+--------------------------------+
|           59 + size(alias) + size(outputs) + size(inputs) + size(memo) |
|                 + len(name) + len(symbol) + size(initial_states) bytes |
+------------------------------------------------------------------------+

### Proto GenesisAsset Specification

```text
message GenesisAsset {
    string alias = 1;                          // 2 bytes + len(alias)
    uint32 network_id = 2;                     // 04 bytes
    bytes blockchain_id = 3;                   // 32 bytes
    repeated Output outputs = 4;               // 04 bytes + size(outputs)
    repeated Input inputs = 5;                 // 04 bytes + size(inputs)
    bytes memo = 6;                            // 04 bytes + size(memo)
    string name = 7;                           // 2 bytes + len(name)
    name symbol = 8;                           // 2 bytes + len(symbol)
    uint8 denomination = 9;                    // 1 bytes
    repeated InitialState initial_states = 10; // 4 bytes + size(initial_states)
}
````

### GenesisAsset Example

Let's make a GenesisAsset:

- **`Alias`**: `asset1`
- **`NetworkID`**: `12345`
- **`BlockchainID`**: `0x0000000000000000000000000000000000000000000000000000000000000000`
- **`Outputs`**: \[\]
- **`Inputs`**: \[\]
- **`Memo`**: `2Zc54v4ek37TEwu4LiV3j41PUMRd6acDDU3ZCVSxE7X`
- **`Name`**: `asset1`
- **`Symbol`**: `MFCA`
- **`Denomination`**: `1`
- **`InitialStates`**:
- `"Example Initial State as defined above"`

```text
[
    Alias         <- 0x617373657431
    NetworkID     <- 0x00003039
    BlockchainID  <- 0x0000000000000000000000000000000000000000000000000000000000000000
    Outputs       <- []
    Inputs        <- []
    Memo          <- 0x66x726f6d20736e6f77666c616b6520746f206176616c616e636865
    Name          <- 0x617373657431
    Symbol        <- 0x66x726f6d20736e6f77666c616b6520746f206176616c616e636865
    Denomination  <- 0x66x726f6d20736e6f77666c616b6520746f206176616c616e636865
    InitialStates <- [
        0x0000000000000001000000070000000000003039000000000000d431000000010000000251025c61fbcfc078f69334f834be6dd26d55a955c3344128e060128ede3523a24a461c8943ab0859
    ]
]
=
[
    // asset alias len:
    0x00, 0x06,
    // asset alias:
    0x61, 0x73, 0x73, 0x65, 0x74, 0x31,
    // network_id:
    0x00, 0x00, 0x30, 0x39,
    // blockchain_id:
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
    // output_len:
    0x00, 0x00, 0x00, 0x00,
    // input_len:
    0x00, 0x00, 0x00, 0x00,
    // memo_len:
    0x00, 0x00, 0x00, 0x1b,
    // memo:
    0x66, 0x72, 0x6f, 0x6d, 0x20, 0x73, 0x6e, 0x6f, 0x77, 0x66, 0x6c, 0x61,
    0x6b, 0x65, 0x20, 0x74, 0x6f, 0x20, 0x61, 0x76, 0x61, 0x6c, 0x61, 0x6e, 0x63, 0x68, 0x65,
    // asset_name_len:
    0x00, 0x0f,
    // asset_name:
    0x6d, 0x79, 0x46, 0x69, 0x78, 0x65, 0x64, 0x43, 0x61, 0x70, 0x41, 0x73, 0x73, 0x65, 0x74,
    // symbol_len:
    0x00, 0x04,
    // symbol:
    0x4d, 0x46, 0x43, 0x41,
    // denomination:
    0x07,
    // number of InitialStates:
    0x00, 0x00, 0x00, 0x01,
    // InitialStates[0]:
    0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0x30, 0x39, 0x00, 0x00, 0x00, 0x00,
    0x00, 0x00, 0xd4, 0x31, 0x00, 0x00, 0x00, 0x01,
    0x00, 0x00, 0x00, 0x02, 0x51, 0x02, 0x5c, 0x61,
    0xfb, 0xcf, 0xc0, 0x78, 0xf6, 0x93, 0x34, 0xf8,
    0x34, 0xbe, 0x6d, 0xd2, 0x6d, 0x55, 0xa9, 0x55,
    0xc3, 0x34, 0x41, 0x28, 0xe0, 0x60, 0x12, 0x8e,
    0xde, 0x35, 0x23, 0xa2, 0x4a, 0x46, 0x1c, 0x89,
    0x43, 0xab, 0x08, 0x59,
]
```



# Background and Requirements (/docs/virtual-machines/custom-precompiles/background-requirements)

---
title: Background and Requirements
description: Learn about the background and requirements for customizing Ethereum Virtual Machine.
---

This is a brief overview of what this tutorial will cover.

- Write a Solidity interface
- Generate the precompile template
- Implement the precompile functions in Golang
- Write and run tests

<Callout type="warn">
Stateful precompiles are [alpha software](https://en.wikipedia.org/wiki/Software_release_life_cycle#Alpha). Build at your own risk.
</Callout>

In this tutorial, we used a branch based on Subnet-EVM version `v0.5.2`. You can find the branch [here](https://github.com/ava-labs/subnet-evm/tree/helloworld-official-tutorial-v2). The code in this branch is the same as Subnet-EVM except for the `precompile/contracts/helloworld` directory. The directory contains the code for the `HelloWorld` precompile. We will be using this precompile as an example to learn how to write a stateful precompile. The code in this branch can become outdated. You should always use the latest version of Subnet-EVM when you develop your own precompile.

## Precompile-EVM

Subnet-EVM precompiles can be registered from an external repo. This allows developer to build their precompiles without maintaining a fork of Subnet-EVM. The precompiles are then registered in the Subnet-EVM at build time.

The difference between using Subnet-EVM and Precompile-EVM is that with Subnet-EVM you can change EVM internals to interact with your precompiles. Such as changing fee structure, adding new opcodes, changing how to build a block, etc. With Precompile-EVM you can only add new stateful precompiles that can interact with the StateDB. Precompiles built with Precompile-EVM are still very powerful because it can directly access to the state and modify it.

There is a template repo for how to build a precompile with this way called [Precompile-EVM](https://github.com/ava-labs/precompile-evm). Both Subnet-EVM and Precompile-EVM share similar directory structures and common codes.

You can reference the Precompile-EVM PR that adds Hello World precompile [here](https://github.com/ava-labs/precompile-evm/pull/12).

## Requirements

This tutorial assumes familiarity with Golang and JavaScript.

Additionally, users should be deeply familiar with the EVM in order to understand its invariants since adding a Stateful Precompile modifies the EVM itself.

Here are some recommended resources to learn the ins and outs of the EVM:

- [The Ethereum Virtual Machine](https://github.com/ethereumbook/ethereumbook/blob/develop/13evm.asciidoc)
- [Precompiles in Solidity](https://medium.com/@rbkhmrcr/precompiles-solidity-e5d29bd428c4)
- [Deconstructing a Smart Contract](https://blog.openzeppelin.com/deconstructing-a-solidity-contract-part-i-introduction-832efd2d7737/)
- [Layout of State Variables in Storage](https://docs.soliditylang.org/en/v0.8.10/internals/layout_in_storage.html)
- [Layout in Memory](https://docs.soliditylang.org/en/v0.8.10/internals/layout_in_memory.html)
- [Layout of Call Data](https://docs.soliditylang.org/en/v0.8.10/internals/layout_in_calldata.html)
- [Contract ABI Specification](https://docs.soliditylang.org/en/v0.8.10/abi-spec.html)
- [Customizing the EVM with Stateful Precompiles](https://medium.com/avalancheavax/customizing-the-evm-with-stateful-precompiles-f44a34f39efd)

Please install the following before getting started.

First, install the latest version of Go. Follow the instructions [here](https://go.dev/doc/install). You can verify by running `go version`.

Set the `$GOPATH` environment variable properly for Go to look for Go Workspaces. Please read [this](https://go.dev/doc/gopath_code) for details. You can verify by running `echo $GOPATH`.

<Callout title="Note">
See [here](https://github.com/golang/go/wiki/SettingGOPATH) for instructions on setting the GOPATH based on system configurations.
</Callout>

As a few things will be installed into `$GOPATH/bin`, please make sure that `$GOPATH/bin` is in your `$PATH`, otherwise, you may get an error running the commands below. To do that, run the command: `export PATH=$PATH:$GOROOT/bin:$GOPATH/bin`

Download the following prerequisites into your `$GOPATH`:

- Git Clone the repository (Subnet-EVM or Precompile-EVM)
- Git Clone [AvalancheGo](https://github.com/ava-labs/avalanchego) repository
- Install [Avalanche Network Runner](/docs/tooling/avalanche-network-runner/introduction)
- Install [solc](https://github.com/ethereum/solc-js#usage-on-the-command-line)
- Install [Node.js and NPM](https://nodejs.org/en/download) For easy copy paste, use the below commands:

```bash
cd $GOPATH
mkdir -p src/github.com/ava-labs
cd src/github.com/ava-labs
```

Clone the repository:

<Tabs items={['Subnet-EVM', 'Precompile-EVM']}>
<Tab value="Subnet-EVM">
```bash
git clone git@github.com:ava-labs/subnet-evm.git
```

Then run the following commands:

```bash
git clone git@github.com:ava-labs/avalanchego.git
curl -sSfL https://raw.githubusercontent.com/ava-labs/avalanche-network-runner/main/scripts/install.sh | sh -s
npm install -g solc
```
</Tab>
<Tab value="Precompile-EVM">
```bash
git clone git@github.com:ava-labs/precompile-evm.git
```

Alternatively you can use it as a template repo from github.

Then run the following commands:

```bash
git clone git@github.com:ava-labs/avalanchego.git
curl -sSfL https://raw.githubusercontent.com/ava-labs/avalanche-network-runner/main/scripts/install.sh | sh -s
npm install -g solc
```
</Tab>
</Tabs>

## Complete Code

You can inspect example pull request for the complete code.

<Tabs items={['Subnet-EVM', 'Precompile-EVM']}>
  <Tab value="Subnet-EVM">
    [Subnet-EVM Hello World Pull Request](https://github.com/ava-labs/subnet-evm/pull/565/)
  </Tab>
  <Tab value="Precompile-EVM">
    [Precompile-EVM Hello World Pull Request](https://github.com/ava-labs/precompile-evm/pull/12/)
  </Tab>
</Tabs>

For a full-fledged example, you can also check out the [Reward Manager Precompile](https://github.com/ava-labs/subnet-evm/blob/helloworld-official-tutorial-v2/precompile/contracts/rewardmanager/).

# Generating Your Precompile (/docs/virtual-machines/custom-precompiles/create-precompile)

---
title: Generating Your Precompile
description: In this section, we will go over the process for automatically generating the template code which you can configure accordingly for your stateful precompile.
---

First, we must create the Solidity interface that we want our precompile to implement. This will be the HelloWorld Interface. It will have two simple functions, `sayHello()`, `setGreeting()` and an event `GreetingChanged`. These two functions will demonstrate the getting and setting respectively of a value stored in the precompile's state space.

The `sayHello()` function is a `view` function, meaning it does not modify the state of the precompile and returns a string result. The `setGreeting()` function is a state changer function, meaning it modifies the state of the precompile. The `HelloWorld` interface inherits `IAllowList` interface to use the allow list functionality.

For this tutorial, we will be working in a new branch in Subnet-EVM/Precompile-EVM repo.

<Tabs items={['Subnet-EVM', 'Precompile-EVM']}>
<Tab value="Subnet-EVM">
```bash
cd $GOPATH/src/github.com/ava-labs/subnet-evm
```

We will start off in this directory `./contracts/`:

```bash
cd contracts/
```

Create a new file called `IHelloWorld.sol` and copy and paste the below code:

```solidity title="contracts/IHelloWorld.sol"
// (c) 2022-2023, Ava Labs, Inc. All rights reserved.
// See the file LICENSE for licensing terms.

// SPDX-License-Identifier: MIT

pragma solidity >=0.8.0;
import "./IAllowList.sol";

interface IHelloWorld is IAllowList {
  event GreetingChanged(
    address indexed sender,
    string oldGreeting,
    string newGreeting
  );

  // sayHello returns the stored greeting string
  function sayHello() external view returns (string calldata result);

  // setGreeting  stores the greeting string
  function setGreeting(string calldata response) external;
}
```

Now we have an interface that our precompile can implement! Let's create an [ABI](https://docs.soliditylang.org/en/v0.8.13/abi-spec.html#contract-abi-specification) of our Solidity interface.

In the same directory, let's run:

```bash
solc --abi ./contracts/interfaces/IHelloWorld.sol -o ./abis
```

This generates the ABI code under `./abis/contracts_interfaces_IHelloWorld_sol_IHelloWorld.abi`.

```
[
  {
    "anonymous": false,
    "inputs": [
      {
        "indexed": true,
        "internalType": "address",
        "name": "sender",
        "type": "address"
      },
      {
        "indexed": false,
        "internalType": "string",
        "name": "oldGreeting",
        "type": "string"
      },
      {
        "indexed": false,
        "internalType": "string",
        "name": "newGreeting",
        "type": "string"
      }
    ],
    "name": "GreetingChanged",
    "type": "event"
  },
  {
    "anonymous": false,
    "inputs": [
      {
        "indexed": true,
        "internalType": "uint256",
        "name": "role",
        "type": "uint256"
      },
      {
        "indexed": true,
        "internalType": "address",
        "name": "account",
        "type": "address"
      },
      {
        "indexed": true,
        "internalType": "address",
        "name": "sender",
        "type": "address"
      },
      {
        "indexed": false,
        "internalType": "uint256",
        "name": "oldRole",
        "type": "uint256"
      }
    ],
    "name": "RoleSet",
    "type": "event"
  },
  {
    "inputs": [
      { "internalType": "address", "name": "addr", "type": "address" }
    ],
    "name": "readAllowList",
    "outputs": [
      { "internalType": "uint256", "name": "role", "type": "uint256" }
    ],
    "stateMutability": "view",
    "type": "function"
  },
  {
    "inputs": [],
    "name": "sayHello",
    "outputs": [
      { "internalType": "string", "name": "result", "type": "string" }
    ],
    "stateMutability": "view",
    "type": "function"
  },
  {
    "inputs": [
      { "internalType": "address", "name": "addr", "type": "address" }
    ],
    "name": "setAdmin",
    "outputs": [],
    "stateMutability": "nonpayable",
    "type": "function"
  },
  {
    "inputs": [
      { "internalType": "address", "name": "addr", "type": "address" }
    ],
    "name": "setEnabled",
    "outputs": [],
    "stateMutability": "nonpayable",
    "type": "function"
  },
  {
    "inputs": [
      { "internalType": "string", "name": "response", "type": "string" }
    ],
    "name": "setGreeting",
    "outputs": [],
    "stateMutability": "nonpayable",
    "type": "function"
  },
  {
    "inputs": [
      { "internalType": "address", "name": "addr", "type": "address" }
    ],
    "name": "setManager",
    "outputs": [],
    "stateMutability": "nonpayable",
    "type": "function"
  },
  {
    "inputs": [
      { "internalType": "address", "name": "addr", "type": "address" }
    ],
    "name": "setNone",
    "outputs": [],
    "stateMutability": "nonpayable",
    "type": "function"
  }
]
```

As you can see the ABI also contains the `IAllowList` interface functions. This is because the `IHelloWorld` interface inherits from the `IAllowList` interface.

Note: The ABI must have named outputs in order to generate the precompile template.

Now that we have an ABI for the precompile gen tool to interact with, we can run the following command to generate our HelloWorld precompile files!

Let's go back to the root of the repository and run the PrecompileGen script helper:

```bash
cd ..
```

Both of these Subnet-EVM and Precompile-EVM have the same `generate_precompile.sh` script. The one in Precompile-EVM installs the script from Subnet-EVM and runs it.

```bash
./scripts/generate_precompile.sh --help

# output
Using branch: precompile-tutorial
NAME:
precompilegen - subnet-evm precompile generator tool

USAGE:
main [global options] command [command options] [arguments...]

VERSION:
1.10.26-stable

COMMANDS:
help, h Shows a list of commands or help for one command

GLOBAL OPTIONS:

    --abi value
          Path to the contract ABI json to generate, - for STDIN

    --out value
          Output folder for the generated precompile files, - for STDOUT (default =
          ./precompile/contracts/{pkg}). Test files won't be generated if STDOUT is used
    --pkg value
          Go package name to generate the precompile into (default = {type})
    --type value
          Struct name for the precompile (default = {abi file name})
MISC
    --help, -h                     (default: false)
          show help
    --version, -v                  (default: false)
          print the version
COPYRIGHT:
Copyright 2013-2022 The go-ethereum Authors
```

Now let's generate the precompile template files!
</Tab>

<Tab value="Precompile-EVM">
```bash
cd $GOPATH/src/github.com/ava-labs/precompile-evm
```

We will start off in this directory `./contracts/`:

```bash
cd contracts/
```

For Precompile-EVM interfaces and other contracts in Subnet-EVM can be accessible through `@avalabs/subnet-evm-contracts` package. This is already added to the `package.json` file. You can install it by running `npm install`. In order to import `IAllowList` interface, you can use the following import statement:

```solidity
import "@avalabs/subnet-evm-contracts/contracts/interfaces/IAllowList.sol";
```

The full file looks like this:

```solidity
// SPDX-License-Identifier: MIT
pragma solidity >=0.8.0;
import "@avalabs/subnet-evm-contracts/contracts/interfaces/IAllowList.sol";

interface IHelloWorld is IAllowList {
  event GreetingChanged(
    address indexed sender,
    string oldGreeting,
    string newGreeting
  );

  // sayHello returns the stored greeting string
  function sayHello() external view returns (string calldata result);

  // setGreeting stores the greeting string
  function setGreeting(string calldata response) external;
}
```

Now we have an interface that our precompile can implement! Let's create an ABI of our Solidity interface.

In Precompile-EVM we import contracts from `@avalabs/subnet-evm-contracts` package. In order to generate the ABI in Precompile-EVM we need to include the `node_modules` folder to find imported contracts with following flags:

- `--abi`: ABI specification of the contracts.
- `--base-path path`: Use the given path as the root of the source tree instead of the root of the filesystem.
- `--include-path path`: Make an additional source directory available to the default import callback. Use this option if you want to import contracts whose location is not fixed in relation to your main source tree; for example third-party libraries installed using a package manager. Can be used multiple times. Can only be used if base path has a non-empty value.
- `--output-dir path`: If given, creates one file per output component and contract/file at the specified directory.
- `--overwrite`: Overwrite existing files (used together with` --output-dir`).

```bash
solc --abi ./contracts/interfaces/IHelloWorld.sol -o ./abis --base-path . --include-path ./node_modules
```

This generates the ABI code under `./abis/contracts_interfaces_IHelloWorld_sol_IHelloWorld.abi`.

```
[
  {
    "anonymous": false,
    "inputs": [
      {
        "indexed": true,
        "internalType": "address",
        "name": "sender",
        "type": "address"
      },
      {
        "indexed": false,
        "internalType": "string",
        "name": "oldGreeting",
        "type": "string"
      },
      {
        "indexed": false,
        "internalType": "string",
        "name": "newGreeting",
        "type": "string"
      }
    ],
    "name": "GreetingChanged",
    "type": "event"
  },
  {
    "anonymous": false,
    "inputs": [
      {
        "indexed": true,
        "internalType": "uint256",
        "name": "role",
        "type": "uint256"
      },
      {
        "indexed": true,
        "internalType": "address",
        "name": "account",
        "type": "address"
      },
      {
        "indexed": true,
        "internalType": "address",
        "name": "sender",
        "type": "address"
      },
      {
        "indexed": false,
        "internalType": "uint256",
        "name": "oldRole",
        "type": "uint256"
      }
    ],
    "name": "RoleSet",
    "type": "event"
  },
  {
    "inputs": [
      { "internalType": "address", "name": "addr", "type": "address" }
    ],
    "name": "readAllowList",
    "outputs": [
      { "internalType": "uint256", "name": "role", "type": "uint256" }
    ],
    "stateMutability": "view",
    "type": "function"
  },
  {
    "inputs": [],
    "name": "sayHello",
    "outputs": [
      { "internalType": "string", "name": "result", "type": "string" }
    ],
    "stateMutability": "view",
    "type": "function"
  },
  {
    "inputs": [
      { "internalType": "address", "name": "addr", "type": "address" }
    ],
    "name": "setAdmin",
    "outputs": [],
    "stateMutability": "nonpayable",
    "type": "function"
  },
  {
    "inputs": [
      { "internalType": "address", "name": "addr", "type": "address" }
    ],
    "name": "setEnabled",
    "outputs": [],
    "stateMutability": "nonpayable",
    "type": "function"
  },
  {
    "inputs": [
      { "internalType": "string", "name": "response", "type": "string" }
    ],
    "name": "setGreeting",
    "outputs": [],
    "stateMutability": "nonpayable",
    "type": "function"
  },
  {
    "inputs": [
      { "internalType": "address", "name": "addr", "type": "address" }
    ],
    "name": "setManager",
    "outputs": [],
    "stateMutability": "nonpayable",
    "type": "function"
  },
  {
    "inputs": [
      { "internalType": "address", "name": "addr", "type": "address" }
    ],
    "name": "setNone",
    "outputs": [],
    "stateMutability": "nonpayable",
    "type": "function"
  }
]
```

As you can see the ABI also contains the `IAllowList` interface functions. This is because the `IHelloWorld` interface inherits from the `IAllowList` interface.

Note: The ABI must have named outputs in order to generate the precompile template.

Now that we have an ABI for the precompile gen tool to interact with, we can run the following command to generate our HelloWorld precompile files!

Let's go back to the root of the repository and run the PrecompileGen script helper:

```bash
cd ..
```

Both of these Subnet-EVM and Precompile-EVM have the same generate_precompile.sh script. The one in Precompile-EVM installs the script from Subnet-EVM and runs it.

```bash
./scripts/generate_precompile.sh --help

# output
Using branch: precompile-tutorial
NAME:
precompilegen - subnet-evm precompile generator tool

USAGE:
main [global options] command [command options] [arguments...]

VERSION:
1.10.26-stable

COMMANDS:
help, h Shows a list of commands or help for one command

GLOBAL OPTIONS:

    --abi value
          Path to the contract ABI json to generate, - for STDIN

    --out value
          Output folder for the generated precompile files, - for STDOUT (default =
          ./precompile/contracts/{pkg}). Test files won't be generated if STDOUT is used
    --pkg value
          Go package name to generate the precompile into (default = {type})
    --type value
          Struct name for the precompile (default = {abi file name})
MISC
    --help, -h                     (default: false)
          show help
    --version, -v                  (default: false)
          print the version
COPYRIGHT:
Copyright 2013-2022 The go-ethereum Authors
```
Now let's generate the precompile template files!
</Tab>
</Tabs>

<Tabs items={['Subnet-EVM', 'Precompile-EVM']}>
<Tab value="Subnet-EVM">
In Subnet-EVM precompile implementations reside under the `./precompile/contracts` directory. Let's generate our precompile template in the `./precompile/contracts/helloworld` directory, where `helloworld` is the name of the Go package we want to generate the precompile into.

```bash
./scripts/generate_precompile.sh --abi ./contracts/abis/contracts_interfaces_IHelloWorld_sol_IHelloWorld.abi --type HelloWorld --pkg helloworld
```

This generates a precompile template files `contract.go`, `contract.abi`, `config.go`, `module.go`, `event.go` and `README.md` files. `README.md` explains general guidelines for precompile development. You should carefully read this file before modifying the precompile template.

```
There are some must-be-done changes waiting in the generated file. Each area requiring you to add your code is marked with CUSTOM CODE to make them easy to find and modify.
Additionally there are other files you need to edit to activate your precompile.
These areas are highlighted with comments "ADD YOUR PRECOMPILE HERE".
For testing take a look at other precompile tests in contract_test.go and config_test.go in other precompile folders.
General guidelines for precompile development:

1- Set a suitable config key in generated module.go. E.g: "yourPrecompileConfig"
2- Read the comment and set a suitable contract address in generated module.go. E.g:
ContractAddress = common.HexToAddress("ASUITABLEHEXADDRESS")
3- It is recommended to only modify code in the highlighted areas marked with "CUSTOM CODE STARTS HERE". Typically, custom codes are required in only those areas.
Modifying code outside of these areas should be done with caution and with a deep understanding of how these changes may impact the EVM.
4- If you have any event defined in your precompile, review the generated event.go file and set your event gas costs. You should also emit your event in your function in the contract.go file.
5- Set gas costs in generated contract.go
6- Force import your precompile package in precompile/registry/registry.go
7- Add your config unit tests under generated package config_test.go
8- Add your contract unit tests under generated package contract_test.go
9- Additionally you can add a full-fledged VM test for your precompile under plugin/vm/vm_test.go. See existing precompile tests for examples.
10- Add your solidity interface and test contract to contracts/contracts
11- Write solidity contract tests for your precompile in contracts/contracts/test
12- Write TypeScript DS-Test counterparts for your solidity tests in contracts/test
13- Create your genesis with your precompile enabled in tests/precompile/genesis/
14- Create e2e test for your solidity test in tests/precompile/solidity/suites.go
15- Run your e2e precompile Solidity tests with './scripts/run_ginkgo.sh`
```

Let's follow these steps and create our HelloWorld precompile.
</Tab>
<Tab value="Precompile-EVM">
For Precompile-EVM we don't need to put files under a deep directory structure. We can just generate the precompile template under its own directory via `--out ./helloworld` flag.

```bash
./scripts/generate_precompile.sh --abi ./contracts/abis/contracts_interfaces_IHelloWorld_sol_IHelloWorld.abi --type HelloWorld --pkg helloworld --out ./helloworld
```

This generates a precompile template files `contract.go`, `contract.abi`, `config.go`, `module.go`, `event.go` and `README.md` files. `README.md` explains general guidelines for precompile development. You should carefully read this file before modifying the precompile template.

```
There are some must-be-done changes waiting in the generated file. Each area requiring you to add your code is marked with CUSTOM CODE to make them easy to find and modify.
Additionally there are other files you need to edit to activate your precompile.
These areas are highlighted with comments "ADD YOUR PRECOMPILE HERE".
For testing take a look at other precompile tests in contract_test.go and config_test.go in other precompile folders.
General guidelines for precompile development:

1- Set a suitable config key in generated module.go. E.g: "yourPrecompileConfig"
2- Read the comment and set a suitable contract address in generated module.go. E.g:
ContractAddress = common.HexToAddress("ASUITABLEHEXADDRESS")
3- It is recommended to only modify code in the highlighted areas marked with "CUSTOM CODE STARTS HERE". Typically, custom codes are required in only those areas.
Modifying code outside of these areas should be done with caution and with a deep understanding of how these changes may impact the EVM.
4- If you have any event defined in your precompile, review the generated event.go file and set your event gas costs. You should also emit your event in your function in the contract.go file.
5- Set gas costs in generated contract.go
6- Force import your precompile package in precompile/registry/registry.go
7- Add your config unit tests under generated package config_test.go
8- Add your contract unit tests under generated package contract_test.go
9- Additionally you can add a full-fledged VM test for your precompile under plugin/vm/vm_test.go. See existing precompile tests for examples.
10- Add your solidity interface and test contract to contracts/contracts
11- Write solidity contract tests for your precompile in contracts/contracts/test
12- Write TypeScript DS-Test counterparts for your solidity tests in contracts/test
13- Create your genesis with your precompile enabled in tests/precompile/genesis/
14- Create e2e test for your solidity test in tests/precompile/solidity/suites.go
15- Run your e2e precompile Solidity tests with './scripts/run_ginkgo.sh`
```

Let's follow these steps and create our HelloWorld precompile!
</Tab>
</Tabs>

# Defining Your Precompile (/docs/virtual-machines/custom-precompiles/defining-precompile)

---
title: Defining Your Precompile
description: Now that we have autogenerated the template code required for our precompile, let's actually write the logic for the precompile itself.
---

## Setting Config Key

Let's jump to `helloworld/module.go` file first. This file contains the module definition for our precompile. You can see the `ConfigKey` is set to some default value of `helloWorldConfig`. This key should be unique to the precompile.

This config key determines which JSON key to use when reading the precompile's config from the JSON upgrade/genesis file. In this case, the config key is `helloWorldConfig` and the JSON config should look like this:

```json
{
  "helloWorldConfig": {
    "blockTimestamp": 0
		...
  }
}
```

## Setting Contract Address

In the `helloworld/module.go` you can see the `ContractAddress` is set to some default value. This should be changed to a suitable address for your precompile. The address should be unique to the precompile. There is a registry of precompile addresses under [`precompile/registry/registry.go`](https://github.com/ava-labs/subnet-evm/blob/helloworld-official-tutorial-v2/precompile/registry/registry.go).

A list of addresses is specified in the comments under this file. Modify the default value to be the next user available stateful precompile address. For forks of Subnet-EVM or Precompile-EVM, users should start at `0x0300000000000000000000000000000000000000` to ensure that their own modifications do not conflict with stateful precompiles that may be added to Subnet-EVM in the future. You should pick an address that is not already taken.

```go title="helloworld/module.go"
// This list is kept just for reference. The actual addresses defined in respective packages of precompiles.
// Note: it is important that none of these addresses conflict with each other or any other precompiles
// in core/vm/contracts.go.
// The first stateful precompiles were added in coreth to support nativeAssetCall and nativeAssetBalance. New stateful precompiles
// originating in coreth will continue at this prefix, so we reserve this range in subnet-evm so that they can be migrated into
// subnet-evm without issue.
// These start at the address: 0x0100000000000000000000000000000000000000 and will increment by 1.
// Optional precompiles implemented in subnet-evm start at 0x0200000000000000000000000000000000000000 and will increment by 1
// from here to reduce the risk of conflicts.
// For forks of subnet-evm, users should start at 0x0300000000000000000000000000000000000000 to ensure
// that their own modifications do not conflict with stateful precompiles that may be added to subnet-evm
// in the future.
// ContractDeployerAllowListAddress = common.HexToAddress("0x0200000000000000000000000000000000000000")
// ContractNativeMinterAddress      = common.HexToAddress("0x0200000000000000000000000000000000000001")
// TxAllowListAddress               = common.HexToAddress("0x0200000000000000000000000000000000000002")
// FeeManagerAddress                = common.HexToAddress("0x0200000000000000000000000000000000000003")
// RewardManagerAddress             = common.HexToAddress("0x0200000000000000000000000000000000000004")
// HelloWorldAddress                = common.HexToAddress("0x0300000000000000000000000000000000000000")
// ADD YOUR PRECOMPILE HERE
// {YourPrecompile}Address          = common.HexToAddress("0x03000000000000000000000000000000000000??")
```

Don't forget to update the actual variable `ContractAddress` in `module.go` to the address you chose. It should look like this:

```go title="helloworld/module.go"
// ContractAddress is the defined address of the precompile contract.
// This should be unique across all precompile contracts.
// See params/precompile_modules.go for registered precompile contracts and more information.
var ContractAddress = common.HexToAddress("0x0300000000000000000000000000000000000000")
```

Now when Subnet-EVM sees the `helloworld.ContractAddress` as input when executing [`CALL`](https://github.com/ava-labs/subnet-evm/blob/helloworld-official-tutorial-v2/core/vm/evm.go#L251), [`CALLCODE`](https://github.com/ava-labs/subnet-evm/blob/helloworld-official-tutorial-v2/core/vm/evm.go#L341), [`DELEGATECALL`](https://github.com/ava-labs/subnet-evm/blob/helloworld-official-tutorial-v2/core/vm/evm.go#L392), [`STATICCALL`](https://github.com/ava-labs/subnet-evm/blob/helloworld-official-tutorial-v2/core/vm/evm.go#L435), it can run the precompile if the precompile is enabled.

## Adding Custom Code

Search (`CTRL F`) throughout the file with `CUSTOM CODE STARTS HERE` to find the areas in the precompile package that you need to modify. You should start with the reference imports code block.

### Module File

The module file contains fundamental information about the precompile. This includes the key for the precompile, the address of the precompile, and a configurator. This file is located at [`./precompile/helloworld/module.go`](https://github.com/ava-labs/subnet-evm/blob/helloworld-official-tutorial-v2/precompile/contracts/helloworld/module.go) for Subnet-EVM and [./helloworld/module.go](https://github.com/ava-labs/precompile-evm/blob/hello-world-example/helloworld/module.go) for Precompile-EVM.

This file defines the module for the precompile. The module is used to register the precompile to the precompile registry. The precompile registry is used to read configs and enable the precompile. Registration is done in the `init()` function of the module file. `MakeConfig()` is used to create a new instance for the precompile config. This will be used in custom Unmarshal/Marshal logic. You don't need to override these functions.

#### Configure()

Module file contains a `configurator` which implements the `contract.Configurator` interface. This interface includes a `Configure()` function used to configure the precompile and set the initial state of the precompile. This function is called when the precompile is enabled. This is typically used to read from a given config in upgrade/genesis JSON and sets the initial state of the precompile accordingly. This function also calls `AllowListConfig.Configure()` to invoke AllowList configuration as the last step. You should keep it as it is if you want to use AllowList. You can modify this function for your custom logic. You can circle back to this function later after you have finalized the implementation of the precompile config.

### Config File

The config file contains the config for the precompile. This file is located at [`./precompile/helloworld/config.go`](https://github.com/ava-labs/subnet-evm/blob/helloworld-official-tutorial-v2/precompile/contracts/helloworld/config.go) for Subnet-EVM and [./helloworld/config.go](https://github.com/ava-labs/precompile-evm/blob/hello-world-example/helloworld/config.go) for Precompile-EVM. This file contains the `Config` struct, which implements `precompileconfig.Config` interface. It has some embedded structs like `precompileconfig.Upgrade`. `Upgrade` is used to enable upgrades for the precompile. It contains the `BlockTimestamp` and `Disable` to enable/disable upgrades. `BlockTimestamp` is the timestamp of the block when the upgrade will be activated. `Disable` is used to disable the upgrade. If you use `AllowList` for the precompile, there is also `allowlist.AllowListConfig` embedded in the `Config` struct. `AllowListConfig` is used to specify initial roles for specified addresses. If you have any custom fields in your precompile config, you can add them here. These custom fields will be read from upgrade/genesis JSON and set in the precompile config.

```go title="precompile/helloworld/config.go"
// Config implements the precompileconfig.Config interface and
// adds specific configuration for HelloWorld.
type Config struct {
	allowlist.AllowListConfig
	precompileconfig.Upgrade
}
```

#### Verify()

`Verify()` is called on startup and an error is treated as fatal. Generated code contains a call to `AllowListConfig.Verify()` to verify the `AllowListConfig`. You can leave that as is and start adding your own custom verify code after that.

We can leave this function as is right now because there is no invalid custom configuration for the `Config`.

```go title="precompile/helloworld/config.go"
// Verify tries to verify Config and returns an error accordingly.
func (c *Config) Verify() error {
	// Verify AllowList first
	if err := c.AllowListConfig.Verify(); err != nil {
		return err
	}

	// CUSTOM CODE STARTS HERE
	// Add your own custom verify code for Config here
	// and return an error accordingly
	return nil
}
```

#### Equal()

Next, we see is `Equal()`. This function determines if two precompile configs are equal. This is used to determine if the precompile needs to be upgraded. There is some default code that is generated for checking `Upgrade` and `AllowListConfig` equality.

```go title="precompile/helloworld/config.go"
// Equal returns true if [s] is a [*Config] and it has been configured identical to [c].
func (c *Config) Equal(s precompileconfig.Config) bool {
	// typecast before comparison
	other, ok := (s).(*Config)
	if !ok {
		return false
	}
	// CUSTOM CODE STARTS HERE
	// modify this boolean accordingly with your custom Config, to check if [other] and the current [c] are equal
	// if Config contains only Upgrade  and AllowListConfig  you can skip modifying it.
	equals := c.Upgrade.Equal(&other.Upgrade) && c.AllowListConfig.Equal(&other.AllowListConfig)
	return equals
}
```

We can leave this function as is since we check `Upgrade` and `AllowListConfig` for equality which are the only fields that `Config` struct has.

### Modify Configure()

We can now circle back to `Configure()` in `module.go` as we finished implementing `Config` struct. This function configures the `state` with the initial configuration at`blockTimestamp` when the precompile is enabled.

In the HelloWorld example, we want to set up a default key-value mapping in the state where the key is `storageKey` and the value is `Hello World!`. The `StateDB` allows us to store a key-value mapping of 32-byte hashes. The below code snippet can be copied and pasted to overwrite the default `Configure()` code.

```go title="precompile/helloworld/module.go"
const defaultGreeting = "Hello World!"

// Configure configures [state] with the given [cfg] precompileconfig.
// This function is called by the EVM once per precompile contract activation.
// You can use this function to set up your precompile contract's initial state,
// by using the [cfg] config and [state] stateDB.
func (*configurator) Configure(chainConfig contract.ChainConfig, cfg precompileconfig.Config, state contract.StateDB, _ contract.BlockContext) error {
	config, ok := cfg.(*Config)
	if !ok {
		return fmt.Errorf("incorrect config %T: %v", config, config)
	}
	// CUSTOM CODE STARTS HERE

	// This will be called in the first block where HelloWorld stateful precompile is enabled.
	// 1) If BlockTimestamp is nil, this will not be called
	// 2) If BlockTimestamp is 0, this will be called while setting up the genesis block
	// 3) If BlockTimestamp is 1000, this will be called while processing the first block
	// whose timestamp is >= 1000
	//
	// Set the initial value under [common.BytesToHash([]byte("storageKey")] to "Hello World!"
	StoreGreeting(state, defaultGreeting)
	// AllowList is activated for this precompile. Configuring allowlist addresses here.
	return config.AllowListConfig.Configure(state, ContractAddress)
}
```

### Event File

The event file contains the events that the precompile can emit. This file is located at [`./precompile/helloworld/event.go`](https://github.com/ava-labs/subnet-evm/blob/helloworld-official-tutorial-v2/precompile/contracts/helloworld/event.go) for Subnet-EVM and [./helloworld/event.go](https://github.com/ava-labs/precompile-evm/blob/hello-world-example/helloworld/event.go) for Precompile-EVM. The file begins with a comment about events and how they can be emitted:

<Tabs items={['Subnet-EVM', 'Precompile-EVM']}>
<Tab value="Subnet-EVM">
```go title="precompile/helloworld/event.go"
/* NOTE: Events can only be emitted in state-changing functions. So you cannot use events in read-only (view) functions.
Events are generally emitted at the end of a state-changing function with AddLog method of the StateDB. The AddLog method takes 4 arguments:
	1. Address of the contract that emitted the event.
	2. Topic hashes of the event.
	3. Encoded non-indexed data of the event.
	4. Block number at which the event was emitted.
The first argument is the address of the contract that emitted the event.
Topics can be at most 4 elements, the first topic is the hash of the event signature and the rest are the indexed event arguments. There can be at most 3 indexed arguments.
Topics cannot be fully unpacked into their original values since they're 32-bytes hashes.
The non-indexed arguments are encoded using the ABI encoding scheme. The non-indexed arguments can be unpacked into their original values.
Before packing the event, you need to calculate the gas cost of the event. The gas cost of an event is the base gas cost + the gas cost of the topics + the gas cost of the non-indexed data.
See Get{EvetName}EventGasCost functions for more details.
You can use the following code to emit an event in your state-changing precompile functions (generated packer might be different):*/

topics, data, err := PackMyEvent(
	topic1,
	topic2,
	data1,
	data2,
)
if err != nil {
	return nil, remainingGas, err
}
accessibleState.GetStateDB().AddLog(&types.Log{
	Address:     ContractAddress,
	Topics:      topics,
	Data:        data,
	BlockNumber: accessibleState.GetBlockContext().Number().Uint64(),
})
```
</Tab>
<Tab value="Precompile-EVM">
```go title="precompile/helloworld/event.go"
/* NOTE: Events can only be emitted in state-changing functions. So you cannot use events in read-only (view) functions.
Events are generally emitted at the end of a state-changing function with AddLog method of the StateDB. The AddLog method takes 4 arguments:
	1. Address of the contract that emitted the event.
	2. Topic hashes of the event.
	3. Encoded non-indexed data of the event.
	4. Block number at which the event was emitted.
The first argument is the address of the contract that emitted the event.
Topics can be at most 4 elements, the first topic is the hash of the event signature and the rest are the indexed event arguments. There can be at most 3 indexed arguments.
Topics cannot be fully unpacked into their original values since they're 32-bytes hashes.
The non-indexed arguments are encoded using the ABI encoding scheme. The non-indexed arguments can be unpacked into their original values.
Before packing the event, you need to calculate the gas cost of the event. The gas cost of an event is the base gas cost + the gas cost of the topics + the gas cost of the non-indexed data.
See Get{EvetName}EventGasCost functions for more details.
You can use the following code to emit an event in your state-changing precompile functions (generated packer might be different):*/

topics, data, err := PackMyEvent(
	topic1,
	topic2,
	data1,
	data2,
)
if err != nil {
	return nil, remainingGas, err
}
accessibleState.GetStateDB().AddLog(
	ContractAddress,
	topics,
	data,
	accessibleState.GetBlockContext().Number().Uint64(),
)
```
</Tab>
</Tabs>

In this file you should set your event's gas cost and implement the `Get{EventName}EventGasCost` function. This function should take the data you want to emit and calculate the gas cost. In this example we defined our event as follow, and plan to emit it in the `setGreeting` function:

```go
event GreetingChanged(address indexed sender, string oldGreeting, string newGreeting);
```

We used arbitrary strings as non-indexed event data, remind that each emitted event is stored on chain, thus charging right amount is critical. We calculated gas cost according to the length of the string to make sure we're charging right amount of gas. If you're sure that you're dealing with a fixed length data, you can use a fixed gas cost for your event. We will show how events can be emitted under the Contract File section.

### Contract File

The contract file contains the functions of the precompile contract that will be called by the EVM. The file is located at [`./precompile/helloworld/contract.go`](https://github.com/ava-labs/subnet-evm/blob/helloworld-official-tutorial-v2/precompile/contracts/helloworld/contract.go) for Subnet-EVM and [./helloworld/contract.go](https://github.com/ava-labs/precompile-evm/blob/hello-world-example/helloworld/contract.go) for Precompile-EVM. Since we use `IAllowList` interface there will be auto-generated code for `AllowList` functions like below:

```go title="precompile/helloworld/contract.go"
// GetHelloWorldAllowListStatus returns the role of [address] for the HelloWorld list.
func GetHelloWorldAllowListStatus(stateDB contract.StateDB, address common.Address) allowlist.Role {
	return allowlist.GetAllowListStatus(stateDB, ContractAddress, address)
}

// SetHelloWorldAllowListStatus sets the permissions of [address] to [role] for the
// HelloWorld list. Assumes [role] has already been verified as valid.
// This stores the [role] in the contract storage with address [ContractAddress]
// and [address] hash. It means that any reusage of the [address] key for different value
// conflicts with the same slot [role] is stored.
// Precompile implementations must use a different key than [address] for their storage.
func SetHelloWorldAllowListStatus(stateDB contract.StateDB, address common.Address, role allowlist.Role) {
	allowlist.SetAllowListRole(stateDB, ContractAddress, address, role)
}
```

These will be helpful to use AllowList precompile helper in our functions.

#### Packers and Unpackers

There are also auto-generated Packers and Unpackers for the ABI. These will be used in `sayHello` and `setGreeting` functions to comfort the ABI. These functions are auto-generated and will be used in necessary places accordingly. You don't need to worry about how to deal with them, but it's good to know what they are.

Note: There were few changes to precompile packers with Durango. In this example we assumed that the HelloWorld precompile contract has been deployed before Durango. We need to activate this condition only after Durango. If this is a new precompile and never deployed before Durango, you can activate it immediately by removing the if condition.

Each input to a precompile contract function has it's own `Unpacker` function as follows (if deployed before Durango):

```go title="precompile/helloworld/contract.go"
// UnpackSetGreetingInput attempts to unpack [input] into the string type argument
// assumes that [input] does not include selector (omits first 4 func signature bytes)
// if [useStrictMode] is true, it will return an error if the length of [input] is not [common.HashLength]
func UnpackSetGreetingInput(input []byte, useStrictMode bool) (string, error) {
	// Initially we had this check to ensure that the input was the correct length.
	// However solidity does not always pack the input to the correct length, and allows
	// for extra padding bytes to be added to the end of the input. Therefore, we have removed
	// this check with the Durango. We still need to keep this check for backwards compatibility.
	if useStrictMode && len(input) > common.HashLength {
		return "", ErrInputExceedsLimit
	}
	res, err := HelloWorldABI.UnpackInput("setGreeting", input, useStrictMode)
	if err != nil {
		return "", err
	}
	unpacked := *abi.ConvertType(res[0], new(string)).(*string)
	return unpacked, nil
}
```

If this is a new precompile that will be deployed after Durango, you can skip strict mode handling and use false:

```go title="precompile/helloworld/contract.go"
func UnpackSetGreetingInput(input []byte) (string, error) {
	res, err := HelloWorldABI.UnpackInput("setGreeting", input, false)
	if err != nil {
		return "", err
	}
	unpacked := *abi.ConvertType(res[0], new(string)).(*string)
	return unpacked, nil
}
```

The ABI is a binary format and the input to the precompile contract function is a byte array. The `Unpacker` function converts this input to a more easy-to-use format so that we can use it in our function.

Similarly, there is a `Packer` function for each output of a precompile contract function as follows:

```go title="precompile/helloworld/contract.go"
// PackSayHelloOutput attempts to pack given result of type string
// to conform the ABI outputs.
func PackSayHelloOutput(result string) ([]byte, error) {
	return HelloWorldABI.PackOutput("sayHello", result)
}
```

This function converts the output of the function to a byte array that conforms to the ABI and can be returned to the EVM as a result.

#### Modify sayHello()

The next place to modify is in our `sayHello()` function. In a previous step, we created the `IHelloWorld.sol` interface with two functions `sayHello()` and `setGreeting()`. We finally get to implement them here. If any contract calls these functions from the interface, the below function gets executed. This function is a simple getter function.

In `Configure()` we set up a mapping with the key as `storageKey` and the value as `Hello World!`. In this function, we will be returning whatever value is at `storageKey`. The below code snippet can be copied and pasted to overwrite the default `setGreeting` code.

First, we add a helper function to get the greeting value from the stateDB, this will be helpful when we test our contract. We will use the `storageKeyHash` to store the value in the Contract's reserved storage in the stateDB.

```go title="precompile/helloworld/contract.go"
var (
  // storageKeyHash is the hash of the storage key "storageKey" in the contract storage.
	// This is used to store the value of the greeting in the contract storage.
	// It is important to use a unique key here to avoid conflicts with other storage keys
	// like addresses, AllowList, etc.
	storageKeyHash = common.BytesToHash([]byte("storageKey"))
)
// GetGreeting returns the value of the storage key "storageKey" in the contract storage,
// with leading zeroes trimmed.
// This function is mostly used for tests.
func GetGreeting(stateDB contract.StateDB) string {
	// Get the value set at recipient
	value := stateDB.GetState(ContractAddress, storageKeyHash)
	return string(common.TrimLeftZeroes(value.Bytes()))
}
```

Now we can modify the `sayHello` function to return the stored value.

```go title="precompile/helloworld/contract.go"
func sayHello(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {
	if remainingGas, err = contract.DeductGas(suppliedGas, SayHelloGasCost); err != nil {
		return nil, 0, err
	}
	// CUSTOM CODE STARTS HERE

	// Get the current state
	currentState := accessibleState.GetStateDB()
	// Get the value set at recipient
	value := GetGreeting(currentState)
	packedOutput, err := PackSayHelloOutput(value)
	if err != nil {
		return nil, remainingGas, err
	}

	// Return the packed output and the remaining gas
	return packedOutput, remainingGas, nil
}
```

#### Modify setGreeting()

`setGreeting()` function is a simple setter function. It takes in `input` and we will set that as the value in the state mapping with the key as `storageKey`. It also checks if the VM running the precompile is in read-only mode. If it is, it returns an error. At the end of a successful execution, it will emit `GreetingChanged` event.

There is also a generated `AllowList` code in that function. This generated code checks if the caller address is eligible to perform this state-changing operation. If not, it returns an error.

Let's add the helper function to set the greeting value in the stateDB, this will be helpful when we test our contract.

```go title="precompile/helloworld/contract.go"
// StoreGreeting sets the value of the storage key "storageKey" in the contract storage.
func StoreGreeting(stateDB contract.StateDB, input string) {
	inputPadded := common.LeftPadBytes([]byte(input), common.HashLength)
	inputHash := common.BytesToHash(inputPadded)

	stateDB.SetState(ContractAddress, storageKeyHash, inputHash)
}
```

The below code snippet can be copied and pasted to overwrite the default `setGreeting()` code.

<Tabs items={['Subnet-EVM', 'Precompile-EVM']}>
<Tab value="Subnet-EVM">
```go title="precompile/helloworld/contract.go"
func setGreeting(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {
	if remainingGas, err = contract.DeductGas(suppliedGas, SetGreetingGasCost); err != nil {
		return nil, 0, err
	}
	if readOnly {
		return nil, remainingGas, vmerrs.ErrWriteProtection
	}
	// do not use strict mode after Durango
	useStrictMode := !contract.IsDurangoActivated(accessibleState)
	// attempts to unpack [input] into the arguments to the SetGreetingInput.
	// Assumes that [input] does not include selector
	// You can use unpacked [inputStruct] variable in your code
	inputStruct, err := UnpackSetGreetingInput(input, useStrictMode)
	if err != nil {
		return nil, remainingGas, err
	}
	// Allow list is enabled and SetGreeting is a state-changer function.
	// This part of the code restricts the function to be called only by enabled/admin addresses in the allow list.
	// You can modify/delete this code if you don't want this function to be restricted by the allow list.
	stateDB := accessibleState.GetStateDB()
	// Verify that the caller is in the allow list and therefore has the right to call this function.
	callerStatus := allowlist.GetAllowListStatus(stateDB, ContractAddress, caller)
	if !callerStatus.IsEnabled() {
		return nil, remainingGas, fmt.Errorf("%w: %s", ErrCannotSetGreeting, caller)
	}
	// allow list code ends here.

	// CUSTOM CODE STARTS HERE
	// With Durango, you can emit an event in your state-changing precompile functions.
	// Note: If you have been using the precompile before Durango, you should activate it only after Durango.
	// Activating this code before Durango will result in a consensus failure.
	// If this is a new precompile and never deployed before Durango, you can activate it immediately by removing
	// the if condition.
	// We will first read the old greeting. So we should charge the gas for reading the storage.
	if remainingGas, err = contract.DeductGas(remainingGas, contract.ReadGasCostPerSlot); err != nil {
		return nil, 0, err
	}
	oldGreeting := GetGreeting(stateDB)

	eventData := GreetingChangedEventData{
		OldGreeting: oldGreeting,
		NewGreeting: inputStruct,
	}
	topics, data, err := PackGreetingChangedEvent(caller, eventData)
	if err != nil {
		return nil, remainingGas, err
	}
	// Charge the gas for emitting the event.
	eventGasCost := GetGreetingChangedEventGasCost(eventData)
	if remainingGas, err = contract.DeductGas(remainingGas, eventGasCost); err != nil {
		return nil, 0, err
	}

	// Emit the event
	stateDB.AddLog(&types.Log{
		Address:     ContractAddress,
		Topics:      topics,
		Data:        data,
		BlockNumber: accessibleState.GetBlockContext().Number().Uint64(),
	})

	// setGreeting is the execution function
	// "SetGreeting(name string)" and sets the storageKey
	// in the string returned by hello world
	StoreGreeting(stateDB, inputStruct)

	// This function does not return an output, leave this one as is
	packedOutput := []byte{}

	// Return the packed output and the remaining gas
	return packedOutput, remainingGas, nil
}
```
</Tab>
<Tab value="Precompile-EVM">
```go title="precompile/helloworld/contract.go"
func setGreeting(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {
	if remainingGas, err = contract.DeductGas(suppliedGas, SetGreetingGasCost); err != nil {
		return nil, 0, err
	}
	if readOnly {
		return nil, remainingGas, vmerrs.ErrWriteProtection
	}
	// do not use strict mode after Durango
	useStrictMode := !contract.IsDurangoActivated(accessibleState)
	// attempts to unpack [input] into the arguments to the SetGreetingInput.
	// Assumes that [input] does not include selector
	// You can use unpacked [inputStruct] variable in your code
	inputStruct, err := UnpackSetGreetingInput(input, useStrictMode)
	if err != nil {
		return nil, remainingGas, err
	}
	// Allow list is enabled and SetGreeting is a state-changer function.
	// This part of the code restricts the function to be called only by enabled/admin addresses in the allow list.
	// You can modify/delete this code if you don't want this function to be restricted by the allow list.
	stateDB := accessibleState.GetStateDB()
	// Verify that the caller is in the allow list and therefore has the right to call this function.
	callerStatus := allowlist.GetAllowListStatus(stateDB, ContractAddress, caller)
	if !callerStatus.IsEnabled() {
		return nil, remainingGas, fmt.Errorf("%w: %s", ErrCannotSetGreeting, caller)
	}
	// allow list code ends here.

	// CUSTOM CODE STARTS HERE
	// With Durango, you can emit an event in your state-changing precompile functions.
	// Note: If you have been using the precompile before Durango, you should activate it only after Durango.
	// Activating this code before Durango will result in a consensus failure.
	// If this is a new precompile and never deployed before Durango, you can activate it immediately by removing
	// the if condition.
	// We will first read the old greeting. So we should charge the gas for reading the storage.
	if remainingGas, err = contract.DeductGas(remainingGas, contract.ReadGasCostPerSlot); err != nil {
		return nil, 0, err
	}
	oldGreeting := GetGreeting(stateDB)

	eventData := GreetingChangedEventData{
		OldGreeting: oldGreeting,
		NewGreeting: inputStruct,
	}
	topics, data, err := PackGreetingChangedEvent(caller, eventData)
	if err != nil {
		return nil, remainingGas, err
	}
	// Charge the gas for emitting the event.
	eventGasCost := GetGreetingChangedEventGasCost(eventData)
	if remainingGas, err = contract.DeductGas(remainingGas, eventGasCost); err != nil {
		return nil, 0, err
	}

	// Emit the event
	stateDB.AddLog(&types.Log{
		Address:     ContractAddress,
		Topics:      topics,
		Data:        data,
		BlockNumber: accessibleState.GetBlockContext().Number().Uint64(),
	})

	// setGreeting is the execution function
	// "SetGreeting(name string)" and sets the storageKey
	// in the string returned by hello world
	StoreGreeting(stateDB, inputStruct)

	// This function does not return an output, leave this one as is
	packedOutput := []byte{}

	// Return the packed output and the remaining gas
	return packedOutput, remainingGas, nil
}
```
</Tab>
</Tabs>

<Callout title="Note">
Precompile events introduced with Durango. In this example we assumed that the `HelloWorld` precompile contract has been deployed before Durango.

If this is a new precompile and it will be deployed after Durango, you can activate it immediately by removing the Durango if condition (`contract.IsDurangoActivated(accessibleState)`).
</Callout>

### Setting Gas Costs

Setting gas costs for functions is very important and should be done carefully. If the gas costs are set too low, then functions can be abused and can cause DoS attacks. If the gas costs are set too high, then the contract will be too expensive to run.

Subnet-EVM has some predefined gas costs for write and read operations in [`precompile/contract/utils.go`](https://github.com/ava-labs/subnet-evm/blob/helloworld-official-tutorial-v2/precompile/contract/utils.go#L19-L20). In order to provide a baseline for gas costs, we have set the following gas costs.

```go title="precompile/contract/utils.go"
// Gas costs for stateful precompiles
const (
	WriteGasCostPerSlot = 20_000
	ReadGasCostPerSlot  = 5_000
)
```

- `WriteGasCostPerSlot` is the cost of one write such as modifying a state storage slot.
- `ReadGasCostPerSlot` is the cost of reading a state storage slot.

This should be in your gas cost estimations based on how many times the precompile function does a read or a write. For example, if the precompile modifies the state slot of its precompile address twice then the gas cost for that function would be `40_000`. However, if the precompile does additional operations and requires more computational power, then you should increase the gas costs accordingly.

On top of these gas costs, we also have to account for the gas costs of AllowList gas costs. These are the gas costs of reading and writing permissions for addresses in AllowList. These are defined under Subnet-EVM's [`precompile/allowlist/allowlist.go`](https://github.com/ava-labs/subnet-evm/blob/helloworld-official-tutorial-v2/precompile/allowlist/allowlist.go#L28-L29).

By default, these are added to the default gas costs of the state-change functions (SetGreeting) of the precompile. Meaning that these functions will cost an additional `ReadAllowListGasCost` in order to read permissions from the storage. If you don't plan to read permissions from the storage then you can omit these.

Now going back to our `/helloworld/contract.go`, we can modify our precompile function gas costs. Please search (`CTRL F`) `SET A GAS COST HERE` to locate the default gas cost code.

```go title="helloworld/contract.go"
SayHelloGasCost    uint64 = 0                                  // SET A GAS COST HERE
SetGreetingGasCost uint64 = 0 + allowlist.ReadAllowListGasCost // SET A GAS COST HERE
```

We get and set our greeting with `sayHello()` and `setGreeting()` in one slot respectively so we can define the gas costs as follows. We also read permissions from the AllowList in `setGreeting()` so we keep `allowlist.ReadAllowListGasCost`.

```go title="helloworld/contract.go"
SayHelloGasCost    uint64 = contract.ReadGasCostPerSlot
SetGreetingGasCost uint64 = contract.WriteGasCostPerSlot + allowlist.ReadAllowListGasCost
```

## Registering Your Precompile

We should register our precompile package to the Subnet-EVM to be discovered by other packages. Our `Module` file contains an `init()` function that registers our precompile. `init()` is called when the package is imported. We should register our precompile in a common package so that it can be imported by other packages.

<Tabs items={['Subnet-EVM', 'Precompile-EVM']}>
<Tab value="Subnet-EVM">
For Subnet-EVM we have a precompile registry under [`/precompile/registry/registry.go`](https://github.com/ava-labs/subnet-evm/blob/helloworld-official-tutorial-v2/precompile/registry/registry.go). This registry force-imports precompiles from other packages, for example:

```go title="precompile/registry/registry.go"
// Force imports of each precompile to ensure each precompile's init function runs and registers itself
// with the registry.
import (
	_ "github.com/ava-labs/subnet-evm/precompile/contracts/deployerallowlist"

	_ "github.com/ava-labs/subnet-evm/precompile/contracts/nativeminter"

	_ "github.com/ava-labs/subnet-evm/precompile/contracts/txallowlist"

	_ "github.com/ava-labs/subnet-evm/precompile/contracts/feemanager"

	_ "github.com/ava-labs/subnet-evm/precompile/contracts/rewardmanager"

	_ "github.com/ava-labs/subnet-evm/precompile/contracts/helloworld"
	// ADD YOUR PRECOMPILE HERE
	// _ "github.com/ava-labs/subnet-evm/precompile/contracts/yourprecompile"
)
```

The registry itself also force-imported by the [\`/plugin/evm/vm.go](https://github.com/ava-labs/subnet-evm/blob/helloworld-official-tutorial-v2/plugin/evm/vm.go#L50). This ensures that the registry is imported and the precompiles are registered.
</Tab>

<Tab value="Precompile-EVM">
For Precompile-EVM there is a `plugin/main.go` file in Precompile-EVM that orchestrates this precompile registration.

```go title="plugin/main.go"
// (c) 2019-2023, Ava Labs, Inc. All rights reserved.
// See the file LICENSE for licensing terms.

package main

import (
	"fmt"

	"github.com/ava-labs/avalanchego/version"
	"github.com/ava-labs/subnet-evm/plugin/evm"
	"github.com/ava-labs/subnet-evm/plugin/runner"

	// Each precompile generated by the precompilegen tool has a self-registering init function
	// that registers the precompile with the subnet-evm. Importing the precompile package here
	// will cause the precompile to be registered with the subnet-evm.
	_ "github.com/ava-labs/precompile-evm/helloworld"
	// ADD YOUR PRECOMPILE HERE
	//_ "github.com/ava-labs/precompile-evm/{yourprecompilepkg}"
)
```
</Tab>
</Tabs>


# Writing Test Cases (/docs/virtual-machines/custom-precompiles/defining-test-cases)

---
title: Writing Test Cases
description: In this section, we will go over the different ways we can write test cases for our stateful precompile.
---

## Adding Config Tests

Precompile generation tool generates skeletons for unit tests as well. Generated config tests will be under [`./precompile/contracts/helloworld/config_test.go`](https://github.com/ava-labs/subnet-evm/blob/helloworld-official-tutorial-v2/precompile/contracts/helloworld/config_test.go) for Subnet-EVM and [`./helloworld/config_test.go`](https://github.com/ava-labs/precompile-evm/blob/hello-world-example/helloworld/config_test.go) for Precompile-EVM. There are mainly two functions we need to test: `Verify` and `Equal`. `Verify` checks if the precompile is configured correctly. `Equal` checks if the precompile is equal to another precompile. Generated `Verify` tests contain a valid case.

You can add more invalid cases depending on your implementation. `Equal` tests generate some invalid cases to test different timestamps, types, and AllowList cases. You can check each `config_test.go` files for other precompiles under the Subnet-EVM's [`./precompile/contracts`](https://github.com/ava-labs/subnet-evm/blob/helloworld-official-tutorial-v2/precompile/contracts/) directory for more examples.

## Adding Contract Tests

The tool also generates contract tests to make sure our precompile is working correctly. Generated tests include cases to test allow list capabilities, gas costs, and calling functions in read-only mode. You can check other `contract_test.go` files in the `/precompile/contracts`. Hello World contract tests will be under [`./precompile/contracts/helloworld/contract_test.go`](https://github.com/ava-labs/subnet-evm/blob/helloworld-official-tutorial-v2/precompile/contracts/helloworld/contract_test.go) for Subnet-EVM and [`./helloworld/contract_test.go`](https://github.com/ava-labs/precompile-evm/blob/hello-world-example/helloworld/contract_test.go) for Precompile-EVM.

We will also add more test to cover functionalities of `sayHello()` and `setGreeting()`. Contract tests are defined in a standard structure that each test can customize to their needs. The test structure is as follows:

```go
// PrecompileTest is a test case for a precompile
type PrecompileTest struct {
	// Caller is the address of the precompile caller
	Caller common.Address
	// Input the raw input bytes to the precompile
	Input []byte
	// InputFn is a function that returns the raw input bytes to the precompile
	// If specified, Input will be ignored.
	InputFn func(t *testing.T) []byte
	// SuppliedGas is the amount of gas supplied to the precompile
	SuppliedGas uint64
	// ReadOnly is whether the precompile should be called in read only
	// mode. If true, the precompile should not modify the state.
	ReadOnly bool
	// Config is the config to use for the precompile
	// It should be the same precompile config that is used in the
	// precompile's configurator.
	// If nil, Configure will not be called.
	Config precompileconfig.Config
	// BeforeHook is called before the precompile is called.
	BeforeHook func(t *testing.T, state contract.StateDB)
	// AfterHook is called after the precompile is called.
	AfterHook func(t *testing.T, state contract.StateDB)
	// ExpectedRes is the expected raw byte result returned by the precompile
	ExpectedRes []byte
	// ExpectedErr is the expected error returned by the precompile
	ExpectedErr string
	// BlockNumber is the block number to use for the precompile's block context
	BlockNumber int64
}
```

Each test can populate the fields of the `PrecompileTest` struct to customize the test. This test uses an AllowList helper function `allowlist.RunPrecompileWithAllowListTests(t, Module, state.NewTestStateDB, tests)` which can run all specified tests plus AllowList test suites. If you don't plan to use AllowList, you can directly run them as follows:

```go
	for name, test := range tests {
		t.Run(name, func(t *testing.T) {
			test.Run(t, module, newStateDB(t))
		})
	}
```

## Adding VM Tests (Optional)

This is only applicable for direct Subnet-EVM forks as test files are not directly exported in Golang. If you use Precompile-EVM you can skip this step.

VM tests are tests that run the precompile by calling it through the Subnet-EVM. These are the most comprehensive tests that we can run. If your precompile modifies how the Subnet-EVM works, for example changing blockchain rules, you should add a VM test. For example, you can take a look at the `TestRewardManagerPrecompileSetRewardAddress` function in [here](https://github.com/ava-labs/subnet-evm/blob/helloworld-official-tutorial-v2/plugin/evm/vm_test.go#L2772).

For this Hello World example, we don't modify any Subnet-EVM rules, so we don't need to add any VM tests.

## Adding Solidity Test Contracts

Let's add our test contract to `./contracts/contracts`. This smart contract lets us interact with our precompile! We cast the `HelloWorld` precompile address to the `IHelloWorld` interface. In doing so, `helloWorld` is now a contract of type `IHelloWorld` and when we call any functions on that contract, we will be redirected to the HelloWorld precompile address.

The below code snippet can be copied and pasted into a new file called `ExampleHelloWorld.sol`:

```go
//SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;
import "./IHelloWorld.sol";

// ExampleHelloWorld shows how the HelloWorld precompile can be used in a smart contract.
contract ExampleHelloWorld {
  address constant HELLO_WORLD_ADDRESS =
    0x0300000000000000000000000000000000000000;
  IHelloWorld helloWorld = IHelloWorld(HELLO_WORLD_ADDRESS);

  function sayHello() public view returns (string memory) {
    return helloWorld.sayHello();
  }

  function setGreeting(string calldata greeting) public {
    helloWorld.setGreeting(greeting);
  }
}
```

<Callout type="warn">
Hello World Precompile is a different contract than ExampleHelloWorld and has a different address. Since the precompile uses AllowList for a permissioned access, any call to the precompile including from ExampleHelloWorld will be denied unless the caller is added to the AllowList.
</Callout>

Please note that this contract is simply a wrapper and is calling the precompile functions. The reason why we add another example smart contract is to have a simpler stateless tests.

For the test contract we write our test in `./contracts/test/ExampleHelloWorldTest.sol`.
<Tabs items={['Subnet-EVM', 'Precompile-EVM']}>
<Tab value="Subnet-EVM">
```solidity
//SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;
import "../ExampleHelloWorld.sol";
import "../interfaces/IHelloWorld.sol";
import "./AllowListTest.sol";

contract ExampleHelloWorldTest is AllowListTest {
  IHelloWorld helloWorld = IHelloWorld(HELLO_WORLD_ADDRESS);

  function step_getDefaultHelloWorld() public {
    ExampleHelloWorld example = new ExampleHelloWorld();
    address exampleAddress = address(example);
    assertRole(helloWorld.readAllowList(exampleAddress), AllowList.Role.None);
    assertEq(example.sayHello(), "Hello World!");
  }

  function step_doesNotSetGreetingBeforeEnabled() public {
    ExampleHelloWorld example = new ExampleHelloWorld();
    address exampleAddress = address(example);
    assertRole(helloWorld.readAllowList(exampleAddress), AllowList.Role.None);
    try example.setGreeting("testing") {
      assertTrue(false, "setGreeting should fail");
    } catch {}
  }

  function step_setAndGetGreeting() public {
    ExampleHelloWorld example = new ExampleHelloWorld();
    address exampleAddress = address(example);
    assertRole(helloWorld.readAllowList(exampleAddress), AllowList.Role.None);
    helloWorld.setEnabled(exampleAddress);
    assertRole(
      helloWorld.readAllowList(exampleAddress),
      AllowList.Role.Enabled
    );
    string memory greeting = "testgreeting";
    example.setGreeting(greeting);
    assertEq(example.sayHello(), greeting);
  }
}
```
</Tab>
<Tab value="Precompile-EVM">
For Precompile-EVM, you should import AllowListTest with `@avalabs/subnet-evm-contracts` NPM package:

```solidity
//SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;
import "../ExampleHelloWorld.sol";
import "../interfaces/IHelloWorld.sol";
import "@avalabs/subnet-evm-contracts/contracts/test/AllowListTest.sol";

contract ExampleHelloWorldTest is AllowListTest {
  IHelloWorld helloWorld = IHelloWorld(HELLO_WORLD_ADDRESS);

  function step_getDefaultHelloWorld() public {
    ExampleHelloWorld example = new ExampleHelloWorld();
    address exampleAddress = address(example);
    assertRole(helloWorld.readAllowList(exampleAddress), AllowList.Role.None);
    assertEq(example.sayHello(), "Hello World!");
  }

  function step_doesNotSetGreetingBeforeEnabled() public {
    ExampleHelloWorld example = new ExampleHelloWorld();
    address exampleAddress = address(example);
    assertRole(helloWorld.readAllowList(exampleAddress), AllowList.Role.None);
    try example.setGreeting("testing") {
      assertTrue(false, "setGreeting should fail");
    } catch {}
  }

  function step_setAndGetGreeting() public {
    ExampleHelloWorld example = new ExampleHelloWorld();
    address exampleAddress = address(example);
    assertRole(helloWorld.readAllowList(exampleAddress), AllowList.Role.None);
    helloWorld.setEnabled(exampleAddress);
    assertRole(
      helloWorld.readAllowList(exampleAddress),
      AllowList.Role.Enabled
    );
    string memory greeting = "testgreeting";
    example.setGreeting(greeting);
    assertEq(example.sayHello(), greeting);
  }
}
```

</Tab>
</Tabs>

## Adding DS-Test Case

We can now trigger this test contract via `hardhat` tests. The test script uses Subnet-EVM's `test` framework test in `./contracts/test`. You can find more information about the test framework [here](https://github.com/ava-labs/subnet-evm/blob/helloworld-official-tutorial-v2/contracts/test/utils.ts). We also can test the events emitted by the precompile. The test script looks like this:

<Tabs items={['Subnet-EVM', 'Precompile-EVM']}>
<Tab value="Subnet-EVM">
The test script looks like this:

```go
// (c) 2019-2022, Ava Labs, Inc. All rights reserved.
// See the file LICENSE for licensing terms.

import { expect } from "chai";
import { SignerWithAddress } from "@nomiclabs/hardhat-ethers/signers";
import { Contract } from "ethers";
import { ethers } from "hardhat";
import { test } from "./utils";

// make sure this is always an admin for hello world precompile
const ADMIN_ADDRESS = "0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC";
const HELLO_WORLD_ADDRESS = "0x0300000000000000000000000000000000000000";

describe("ExampleHelloWorldTest", function () {
  this.timeout("30s");

  beforeEach("Setup DS-Test contract", async function () {
    const signer = await ethers.getSigner(ADMIN_ADDRESS);
    const helloWorldPromise = ethers.getContractAt(
      "IHelloWorld",
      HELLO_WORLD_ADDRESS,
      signer
    );

    return ethers
      .getContractFactory("ExampleHelloWorldTest", { signer })
      .then((factory) => factory.deploy())
      .then((contract) => {
        this.testContract = contract;
        return contract.deployed().then(() => contract);
      })
      .then(() => Promise.all([helloWorldPromise]))
      .then(([helloWorld]) => helloWorld.setAdmin(this.testContract.address))
      .then((tx) => tx.wait());
  });

  test("should gets default hello world", ["step_getDefaultHelloWorld"]);

  test(
    "should not set greeting before enabled",
    "step_doesNotSetGreetingBeforeEnabled"
  );

  test(
    "should set and get greeting with enabled account",
    "step_setAndGetGreeting"
  );
});

describe("IHelloWorld events", function () {
  let owner: SignerWithAddress;
  let contract: Contract;
  let defaultGreeting = "Hello, World!";
  before(async function () {
    owner = await ethers.getSigner(ADMIN_ADDRESS);
    contract = await ethers.getContractAt(
      "IHelloWorld",
      HELLO_WORLD_ADDRESS,
      owner
    );

    // reset greeting
    let tx = await contract.setGreeting(defaultGreeting);
    await tx.wait();
  });

  it("should emit GreetingChanged event", async function () {
    let newGreeting = "helloprecompile";
    await expect(contract.setGreeting(newGreeting))
      .to.emit(contract, "GreetingChanged")
      .withArgs(
        owner.address,
        // old greeting
        defaultGreeting,
        // new greeting
        newGreeting
      );
  });
});
```
</Tab>
<Tab value="Precompile-EVM">
The test script looks like this:

```go 
// (c) 2019-2022, Ava Labs, Inc. All rights reserved.
// See the file LICENSE for licensing terms.

import { expect } from "chai";
import { SignerWithAddress } from "@nomiclabs/hardhat-ethers/signers";
import { Contract } from "ethers";
import { ethers } from "hardhat";
import { test } from "@avalabs/subnet-evm-contracts";

// make sure this is always an admin for hello world precompile
const ADMIN_ADDRESS = "0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC";
const HELLO_WORLD_ADDRESS = "0x0300000000000000000000000000000000000000";

describe("ExampleHelloWorldTest", function () {
  this.timeout("30s");

  beforeEach("Setup DS-Test contract", async function () {
    const signer = await ethers.getSigner(ADMIN_ADDRESS);
    const helloWorldPromise = ethers.getContractAt(
      "IHelloWorld",
      HELLO_WORLD_ADDRESS,
      signer
    );

    return ethers
      .getContractFactory("ExampleHelloWorldTest", { signer })
      .then((factory) => factory.deploy())
      .then((contract) => {
        this.testContract = contract;
        return contract.deployed().then(() => contract);
      })
      .then(() => Promise.all([helloWorldPromise]))
      .then(([helloWorld]) => helloWorld.setAdmin(this.testContract.address))
      .then((tx) => tx.wait());
  });

  test("should gets default hello world", ["step_getDefaultHelloWorld"]);

  test(
    "should not set greeting before enabled",
    "step_doesNotSetGreetingBeforeEnabled"
  );

  test(
    "should set and get greeting with enabled account",
    "step_setAndGetGreeting"
  );
});

describe("IHelloWorld events", function () {
  let owner: SignerWithAddress;
  let contract: Contract;
  let defaultGreeting = "Hello, World!";
  before(async function () {
    owner = await ethers.getSigner(ADMIN_ADDRESS);
    contract = await ethers.getContractAt(
      "IHelloWorld",
      HELLO_WORLD_ADDRESS,
      owner
    );

    // reset greeting
    let tx = await contract.setGreeting(defaultGreeting);
    await tx.wait();
  });

  it("should emit GreetingChanged event", async function () {
    let newGreeting = "helloprecompile";
    await expect(contract.setGreeting(newGreeting))
      .to.emit(contract, "GreetingChanged")
      .withArgs(
        owner.address,
        // old greeting
        defaultGreeting,
        // new greeting
        newGreeting
      );
  });
});
```
</Tab>
</Tabs>


# Executing Test Cases (/docs/virtual-machines/custom-precompiles/executing-test-cases)

---
title: Executing Test Cases
description: In this section, we will go over how to be able to execute the test cases you wrote in the last section.
---

## Adding the Test Genesis File

To run our e2e contract tests, we will need to create an Avalanche L1 that has the `Hello World` precompile activated, so we will copy and paste the below genesis file into: `/tests/precompile/genesis/hello_world.json`.

Note: it's important that this has the same name as the HardHat test file we created previously.

```json
{
  "config": {
    "chainId": 99999,
    "homesteadBlock": 0,
    "eip150Block": 0,
    "eip150Hash": "0x2086799aeebeae135c246c65021c82b4e15a2c451340993aacfd2751886514f0",
    "eip155Block": 0,
    "eip158Block": 0,
    "byzantiumBlock": 0,
    "constantinopleBlock": 0,
    "petersburgBlock": 0,
    "istanbulBlock": 0,
    "muirGlacierBlock": 0,
    "feeConfig": {
      "gasLimit": 20000000,
      "minBaseFee": 1000000000,
      "targetGas": 100000000,
      "baseFeeChangeDenominator": 48,
      "minBlockGasCost": 0,
      "maxBlockGasCost": 10000000,
      "targetBlockRate": 2,
      "blockGasCostStep": 500000
    },
    "helloWorldConfig": {
      "blockTimestamp": 0,
      "adminAddresses": ["0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC"]
    }
  },
  "alloc": {
    "8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC": {
      "balance": "0x52B7D2DCC80CD2E4000000"
    },
    "0x0Fa8EA536Be85F32724D57A37758761B86416123": {
      "balance": "0x52B7D2DCC80CD2E4000000"
    }
  },
  "nonce": "0x0",
  "timestamp": "0x66321C34",
  "extraData": "0x00",
  "gasLimit": "0x1312D00",
  "difficulty": "0x0",
  "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
  "coinbase": "0x0000000000000000000000000000000000000000",
  "number": "0x0",
  "gasUsed": "0x0",
  "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000"
}
```

Adding this to our genesis enables our HelloWorld precompile at the genesis block (0th block), with `0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC` as the admin address.

```json
{
  "helloWorldConfig": {
    "blockTimestamp": 0,
    "adminAddresses": ["0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC"]
  }
}
```

## Declaring the HardHat E2E Test

Now that we have declared the HardHat test and corresponding `genesis.json` file. The last step to running the e2e test is to declare the new test in `/tests/precompile/solidity/suites.go`.

At the bottom of the file you will see the following code commented out:

```go title="suites.go"
// ADD YOUR PRECOMPILE HERE
/*
ginkgo.It("your precompile", ginkgo.Label("Precompile"), ginkgo.Label("YourPrecompile"), func() {
  ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
  defer cancel()

  // Specify the name shared by the genesis file in ./tests/precompile/genesis/{your_precompile}.json
  // and the test file in ./contracts/tests/{your_precompile}.ts
  blockchainID := subnetsSuite.GetBlockchainID("{your_precompile}")
  runDefaultHardhatTests(ctx, blockchainID, "{your_precompile}")
*/
```

`runDefaultHardhatTests` will run the default Hardhat test command and use the default genesis path. If you want to use a different test command and genesis path than the defaults, you can use the `utils.CreateSubnet` and `utils.RunTestCMD`. See how they were used with default params [here](https://github.com/ava-labs/subnet-evm/blob/helloworld-official-tutorial-v2/tests/utils/subnet.go#L113)

You should copy and paste the ginkgo `It` node and update from `{your_precompile}` to `hello_world`. The string passed in to `utils.RunDefaultHardhatTests(ctx, "your_precompile")` will be used to find both the HardHat test file to execute and the genesis file, which is why you need to use the same name for both.

After modifying the `It` node, it should look like the following (you can copy and paste this directly if you prefer):

```go
ginkgo.It("hello world", ginkgo.Label("Precompile"), ginkgo.Label("HelloWorld"), func() {
  ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
  defer cancel()

  blockchainID := subnetsSuite.GetBlockchainID("hello_world")
  runDefaultHardhatTests(ctx, blockchainID, "hello_world")
})
```

Now that we've set up the new ginkgo test, we can run the ginkgo test that we want by using the `GINKGO_LABEL_FILTER`. This environment variable is passed as a flag to Ginkgo in `./scripts/run_ginkgo.sh` and restricts what tests will run to only the tests with a matching label.

## Running E2E Tests

Before we start testing, we will need to build the AvalancheGo binary and the custom Subnet-EVM binary.

Precompile-EVM bundles Subnet-EVM and runs it under the hood in the [`plugins/main.go`](https://github.com/ava-labs/precompile-evm/blob/hello-world-example/plugin/main.go#L24). Meaning that Precompile-EVM binary works the same way as Subnet-EVM binary. Precompile-EVM repo has also same scripts and the build process as Subnet-EVM. Following steps also apply to Precompile-EVM.

You should have cloned [AvalancheGo](https://github.com/ava-labs/avalanchego) within your `$GOPATH` in the [Background and Requirements](/docs/virtual-machines/custom-precompiles/background-requirements) section, so you can build AvalancheGo with the following command:

```bash
cd $GOPATH/src/github.com/ava-labs/avalanchego
./scripts/build.sh
```

Once you've built AvalancheGo, you can confirm that it was successful by printing the version:

```bash
./build/avalanchego --version
```

This should print something like the following (if you are running AvalancheGo v1.9.7):

```bash
avalanchego/1.11.0 [database=v1.4.5, rpcchainvm=33, commit=c60f7d2dd10c87f57382885b59d6fb2c763eded7, go=1.21.7]
```

This path will be used later as the environment variable `AVALANCHEGO_EXEC_PATH` in the network runner.

Please note that the RPCChainVM version of AvalancheGo and Subnet-EVM must match.

Once we've built AvalancheGo, we can navigate back to the repo and build the binary:

<Tabs items={['Subnet-EVM', 'Precompile-EVM']}>
<Tab value="Subnet-EVM">
```bash
cd $GOPATH/src/github.com/ava-labs/subnet-evm
./scripts/build.sh
```

This will build the Subnet-EVM binary and place it in AvalancheGo's `build/plugins` directory by default at the file path: `$GOPATH/src/github.com/ava-labs/avalanchego/build/plugins/srEXiWaHuhNyGwPUi444Tu47ZEDwxTWrbQiuD7FmgSAQ6X7Dy`

To confirm that the Subnet-EVM binary is compatible with AvalancheGo, you can run the same version command and confirm the RPCChainVM version matches:

```bash
$GOPATH/src/github.com/ava-labs/avalanchego/build/plugins/srEXiWaHuhNyGwPUi444Tu47ZEDwxTWrbQiuD7FmgSAQ6X7Dy --version
```

This should give similar output:

```bash
Subnet-EVM/v0.6.1 [AvalancheGo=v1.11.1, rpcchainvm=33]
```
</Tab>
<Tab value="Precompile-EVM">
```bash
cd $GOPATH/src/github.com/ava-labs/precompile-evm
./scripts/build.sh
```

This will build the Precompile-EVM binary and place it in AvalancheGo's `build/plugins` directory by default at the file path: `$GOPATH/src/github.com/ava-labs/avalanchego/build/plugins/srEXiWaHuhNyGwPUi444Tu47ZEDwxTWrbQiuD7FmgSAQ6X7Dy`

To confirm that the Precompile-EVM binary is compatible with AvalancheGo, you can run the same version command and confirm the RPCChainVM version matches:

```bash
$GOPATH/src/github.com/ava-labs/avalanchego/build/plugins/srEXiWaHuhNyGwPUi444Tu47ZEDwxTWrbQiuD7FmgSAQ6X7Dy --version
```

This should give similar output:

```bash
Precompile-EVM/v0.2.0 Subnet-EVM/v0.6.1 [AvalancheGo=v1.11.1, rpcchainvm=33]
```
</Tab>
</Tabs>

If the RPCChainVM Protocol version printed out does not match the one used in AvalancheGo then Subnet-EVM will not be able to talk to AvalancheGo and the blockchain will not start. You can find the compatibility table for AvalancheGo and Subnet-EVM [here](https://github.com/ava-labs/subnet-evm#avalanchego-compatibility).

The `build/plugins` directory will later be used as the `AVALANCHEGO_PLUGIN_PATH`.

### Running Ginkgo Tests

To run ONLY the HelloWorld precompile test, run the command:

<Tabs items={['Subnet-EVM', 'Precompile-EVM']}>
<Tab value="Subnet-EVM">
```bash
cd $GOPATH/src/github.com/ava-labs/subnet-evm
```
</Tab>
<Tab value="Precompile-EVM">
```bash
cd $GOPATH/src/github.com/ava-labs/precompile-evm
```
</Tab>
</Tabs>

use `GINKGO_LABEL_FILTER` env var to filter the test:

```bash
GINKGO_LABEL_FILTER=HelloWorld ./scripts/run_ginkgo.sh
```

You will first see the node starting up in the `BeforeSuite` section of the precompile test:

```bash
GINKGO_LABEL_FILTER=HelloWorld ./scripts/run_ginkgo.sh

# output
Using branch: hello-world-tutorial-walkthrough
building precompile.test
# github.com/ava-labs/subnet-evm/tests/precompile.test
ld: warning: could not create compact unwind for _blst_sha256_block_data_order: does not use RBP or RSP based frame

Compiled precompile.test
# github.com/ava-labs/subnet-evm/tests/load.test
ld: warning: could not create compact unwind for _blst_sha256_block_data_order: does not use RBP or RSP based frame

Compiled load.test
Running Suite: subnet-evm precompile ginkgo test suite - /Users/avalabs/go/src/github.com/ava-labs/subnet-evm
===================================================================================================================
Random Seed: 1674833631

Will run 1 of 7 specs
------------------------------
[BeforeSuite]
/Users/avalabs/go/src/github.com/ava-labs/subnet-evm/tests/precompile/precompile_test.go:31
  > Enter [BeforeSuite] TOP-LEVEL - /Users/avalabs/go/src/github.com/ava-labs/subnet-evm/tests/precompile/precompile_test.go:31 @ 01/27/23 10:33:51.001
INFO [01-27|10:33:51.002] Starting AvalancheGo node                wd=/Users/avalabs/go/src/github.com/ava-labs/subnet-evm
INFO [01-27|10:33:51.002] Executing                                cmd="./scripts/run.sh "
[streaming output] Using branch: hello-world-tutorial-walkthrough
...
[BeforeSuite] PASSED [15.002 seconds]
```

After the `BeforeSuite` completes successfully, it will skip all but the `HelloWorld` labeled precompile test:

```bash
S [SKIPPED]
[Precompiles]
/Users/avalabs/go/src/github.com/ava-labs/subnet-evm/tests/precompile/solidity/suites.go:26
  contract native minter [Precompile, ContractNativeMinter]
  /Users/avalabs/go/src/github.com/ava-labs/subnet-evm/tests/precompile/solidity/suites.go:29
------------------------------
S [SKIPPED]
[Precompiles]
/Users/avalabs/go/src/github.com/ava-labs/subnet-evm/tests/precompile/solidity/suites.go:26
  tx allow list [Precompile, TxAllowList]
  /Users/avalabs/go/src/github.com/ava-labs/subnet-evm/tests/precompile/solidity/suites.go:36
------------------------------
...
Combined output:

Compiling 2 files with 0.8.0
Compilation finished successfully


  ExampleHelloWorldTest
    ✓ should gets default hello world (4057ms)
    ✓ should not set greeting before enabled (4067ms)
    ✓ should set and get greeting with enabled account (4074ms)



  3 passing (33s)


  < Exit [It] hello world - /Users/avalabs/go/src/github.com/ava-labs/subnet-evm/tests/precompile/solidity/suites.go:64 @ 01/27/23 10:34:17.484 (11.48s)
• [11.480 seconds]
------------------------------
```

Finally, you will see the load test being skipped as well:

```bash
Running Suite: subnet-evm small load simulator test suite - /Users/avalabs/go/src/github.com/ava-labs/subnet-evm
======================================================================================================================
Random Seed: 1674833658

Will run 0 of 1 specs
S [SKIPPED]
[Load Simulator]
/Users/avalabs/go/src/github.com/ava-labs/subnet-evm/tests/load/load_test.go:49
  basic subnet load test [load]
  /Users/avalabs/go/src/github.com/ava-labs/subnet-evm/tests/load/load_test.go:50
------------------------------

Ran 0 of 1 Specs in 0.000 seconds
SUCCESS! -- 0 Passed | 0 Failed | 0 Pending | 1 Skipped
PASS
```

Looks like the tests are passing!

<Callout title="Note">
If your tests failed, please retrace your steps. Most likely the error is that the precompile was not enabled and some code is missing. Try running `npm install` in the contracts directory to ensure that hardhat and other packages are installed.

You may also use the [official tutorial implementation](https://github.com/ava-labs/subnet-evm/tree/helloworld-official-tutorial-v2) to double-check your work as well.
</Callout>


# Custom Precompiles (/docs/virtual-machines/custom-precompiles)

---
title: Custom Precompiles
description: In this tutorial, we are going to walk through how we can generate a stateful precompile from scratch. Before we start, let's brush up on what a precompile is, what a stateful precompile is, and why this is extremely useful.
---

## Background

### Precompiled Contracts

Ethereum uses precompiles to efficiently implement cryptographic primitives within the EVM instead of re-implementing the same primitives in Solidity. The following precompiles are currently included: ecrecover, sha256, blake2f, ripemd-160, Bn256Add, Bn256Mul, Bn256Pairing, the identity function, and modular exponentiation.

We can see these [precompile](https://github.com/ethereum/go-ethereum/blob/v1.11.1/core/vm/contracts.go#L82) mappings from address to function here in the Ethereum VM:

```go
// PrecompiledContractsBerlin contains the default set of pre-compiled Ethereum
// contracts used in the Berlin release.
var PrecompiledContractsBerlin = map[common.Address]PrecompiledContract{
	common.BytesToAddress([]byte{1}): &ecrecover{},
	common.BytesToAddress([]byte{2}): &sha256hash{},
	common.BytesToAddress([]byte{3}): &ripemd160hash{},
	common.BytesToAddress([]byte{4}): &dataCopy{},
	common.BytesToAddress([]byte{5}): &bigModExp{eip2565: true},
	common.BytesToAddress([]byte{6}): &bn256AddIstanbul{},
	common.BytesToAddress([]byte{7}): &bn256ScalarMulIstanbul{},
	common.BytesToAddress([]byte{8}): &bn256PairingIstanbul{},
	common.BytesToAddress([]byte{9}): &blake2F{},
}
```

These precompile addresses start from `0x0000000000000000000000000000000000000001` and increment by 1.

A [precompile](https://github.com/ava-labs/subnet-evm/blob/helloworld-official-tutorial-v2/core/vm/contracts.go#L54-L57) follows this interface:

```go
// PrecompiledContract is the basic interface for native Go contracts. The implementation
// requires a deterministic gas count based on the input size of the Run method of the
// contract.
type PrecompiledContract interface {
	RequiredGas(input []byte) uint64  // RequiredPrice calculates the contract gas use
	Run(input []byte) ([]byte, error) // Run runs the precompiled contract
}
```

Here is an example of the [sha256 precompile](https://github.com/ava-labs/subnet-evm/blob/helloworld-official-tutorial-v2/core/vm/contracts.go#L237-L250) function.

```go
type sha256hash struct{}

// RequiredGas returns the gas required to execute the pre-compiled contract.
//
// This method does not require any overflow checking as the input size gas costs
// required for anything significant is so high it's impossible to pay for.
func (c *sha256hash) RequiredGas(input []byte) uint64 {
	return uint64(len(input)+31)/32*params.Sha256PerWordGas + params.Sha256BaseGas
}

func (c *sha256hash) Run(input []byte) ([]byte, error) {
	h := sha256.Sum256(input)
	return h[:], nil
}
```

The CALL opcode (CALL, STATICCALL, DELEGATECALL, and CALLCODE) allows us to invoke this precompile.

The function signature of CALL in the EVM is as follows:

```go
 Call(
 	caller ContractRef,
 	addr common.Address,
 	input []byte,
 	gas uint64,
 	value *big.Int,
)(ret []byte, leftOverGas uint64, err error)
```

Precompiles are a shortcut to execute a function implemented by the EVM itself, rather than an actual contract. A precompile is associated with a fixed address defined in the EVM. There is no byte code associated with that address.

When a precompile is called, the EVM checks if the input address is a precompile address, and if so it executes the precompile. Otherwise, it loads the smart contract at the input address and runs it on the EVM interpreter with the specified input data.

### Stateful Precompiled Contracts

A stateful precompile builds on a precompile in that it adds state access. Stateful precompiles are not available in the default EVM, and are specific to Avalanche EVMs such as [Coreth](https://github.com/ava-labs/coreth) and [Subnet-EVM](https://github.com/ava-labs/subnet-evm).

A stateful precompile follows this [interface](https://github.com/ava-labs/subnet-evm/blob/helloworld-official-tutorial-v2/precompile/contract/interfaces.go#L17-L20):

```go
// StatefulPrecompiledContract is the interface for executing a precompiled contract
type StatefulPrecompiledContract interface {
	// Run executes the precompiled contract.
	Run(accessibleState PrecompileAccessibleState,
	caller common.Address,
	addr  common.Address,
	input []byte,
	suppliedGas uint64,
	readOnly bool)
	(ret []byte, remainingGas uint64, err error)
}
```

A stateful precompile injects state access through the `PrecompileAccessibleState` interface to provide access to the EVM state including the ability to modify balances and read/write storage.

This way we can provide even more customization of the EVM through Stateful Precompiles than we can with the original precompile interface!

### AllowList

The AllowList enables a precompile to enforce permissions on addresses. The AllowList is not a contract itself, but a helper structure to provide a control mechanism for wrapping contracts. It provides an `AllowListConfig` to the precompile so that it can take an initial configuration from genesis/upgrade. It also provides functions to set/read the permissions. In this tutorial, we used `IAllowList` interface to provide permission control to the `HelloWorld` precompile. `IAllowList` is defined in Subnet-EVM under [`./contracts/contracts/interfaces/IAllowList.sol`](https://github.com/ava-labs/subnet-evm/blob/helloworld-official-tutorial-v2/contracts/contracts/interfaces/IAllowList.sol). The interface is as follows:

```go
//SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

interface IAllowList {
  event RoleSet(
    uint256 indexed role,
    address indexed account,
    address indexed sender,
    uint256 oldRole
  );

  // Set [addr] to have the admin role over the precompile contract.
  function setAdmin(address addr) external;

  // Set [addr] to be enabled on the precompile contract.
  function setEnabled(address addr) external;

  // Set [addr] to have the manager role over the precompile contract.
  function setManager(address addr) external;

  // Set [addr] to have no role for the precompile contract.
  function setNone(address addr) external;

  // Read the status of [addr].
  function readAllowList(address addr) external view returns (uint256 role);
}
```

You can find more information about the AllowList interface [here](/docs/avalanche-l1s/upgrade/customize-avalanche-l1#allowlist-interface).

# Deploying Your Precompile (/docs/virtual-machines/custom-precompiles/precompile-deployment)

---
title: Deploying Your Precompile
description: Now that we have defined our precompile, let's deploy it to a local network.
---

We made it! Everything works in our Ginkgo tests, and now we want to spin up a local network with the Hello World precompile activated.

Start the server in a terminal in a new tab using avalanche-network-runner. Please check out [this link](/docs/tooling/avalanche-network-runner/introduction) for more information on Avalanche Network Runner, how to download it, and how to use it. The server will be in "listening" mode waiting for API calls.

We will start the server from the Subnet-EVM directory so that we can use a relative file path to the genesis JSON file:

<Tabs items={['Subnet-EVM', 'Precompile-EVM']}>
<Tab value="Subnet-EVM">
```bash
cd $GOPATH/src/github.com/ava-labs/subnet-evm
```
</Tab>

<Tab value="Precompile-EVM">
```bash
cd $GOPATH/src/github.com/ava-labs/precompile-evm
```
</Tab>
</Tabs>

Then run ANR:

```bash
avalanche-network-runner server \
--log-level debug \
--port=":8080" \
--grpc-gateway-port=":8081"
```

Since we already compiled AvalancheGo and Subnet-EVM/Precompile-EVM in a previous step, we should have the AvalancheGo and Subnet-EVM binaries ready to go.

We can now set the following paths. `AVALANCHEGO_EXEC_PATH` points to the latest AvalancheGo binary we have just built. `AVALANCHEGO_PLUGIN_PATH` points to the plugins path which should have the Subnet-EVM binary we have just built:

```bash
export AVALANCHEGO_EXEC_PATH="${GOPATH}/src/github.com/ava-labs/avalanchego/build/avalanchego"
export AVALANCHEGO_PLUGIN_PATH="${HOME}/.avalanchego/plugins"
```

The following command will "issue requests" to the server we just spun up. We can use avalanche-network-runner to spin up some nodes that run the latest version of Subnet-EVM:

```bash
  avalanche-network-runner control start \
  --log-level debug \
  --endpoint="0.0.0.0:8080" \
  --number-of-nodes=5 \
  --avalanchego-path ${AVALANCHEGO_EXEC_PATH} \
  --plugin-dir ${AVALANCHEGO_PLUGIN_PATH} \
  --blockchain-specs '[{"vm_name": "subnetevm", "genesis": "./tests/precompile/genesis/hello_world.json"}]'
```

We can look at the server terminal tab and see it booting up the local network. If the network startup is successful then you should see something like this:

```bash
[blockchain RPC for "srEXiWaHuhNyGwPUi444Tu47ZEDwxTWrbQiuD7FmgSAQ6X7Dy"] "http://127.0.0.1:9650/ext/bc/2jDWMrF9yKK8gZfJaaaSfACKeMasiNgHmuZip5mWxUfhKaYoEU"
[blockchain RPC for "srEXiWaHuhNyGwPUi444Tu47ZEDwxTWrbQiuD7FmgSAQ6X7Dy"] "http://127.0.0.1:9652/ext/bc/2jDWMrF9yKK8gZfJaaaSfACKeMasiNgHmuZip5mWxUfhKaYoEU"
[blockchain RPC for "srEXiWaHuhNyGwPUi444Tu47ZEDwxTWrbQiuD7FmgSAQ6X7Dy"] "http://127.0.0.1:9654/ext/bc/2jDWMrF9yKK8gZfJaaaSfACKeMasiNgHmuZip5mWxUfhKaYoEU"
[blockchain RPC for "srEXiWaHuhNyGwPUi444Tu47ZEDwxTWrbQiuD7FmgSAQ6X7Dy"] "http://127.0.0.1:9656/ext/bc/2jDWMrF9yKK8gZfJaaaSfACKeMasiNgHmuZip5mWxUfhKaYoEU"
[blockchain RPC for "srEXiWaHuhNyGwPUi444Tu47ZEDwxTWrbQiuD7FmgSAQ6X7Dy"] "http://127.0.0.1:9658/ext/bc/2jDWMrF9yKK8gZfJaaaSfACKeMasiNgHmuZip5mWxUfhKaYoEU"
```

This shows the extension to the API server on AvalancheGo that's specific to the Subnet-EVM Blockchain instance. To interact with it, you will want to append the `/rpc` extension, which will supply the standard Ethereum API calls.

For example, you can use the RPC URL: `http://127.0.0.1:9650/ext/bc/2jDWMrF9yKK8gZfJaaaSfACKeMasiNgHmuZip5mWxUfhKaYoEU/rpc`

## Maintenance

You should always keep your fork up to date with the latest changes in the official Subnet-EVM repo. If you have forked the Subnet-EVM repo, there could be conflicts and you may need to manually resolve them.

If you used Precompile-EVM, you can update your repo by bumping Subnet-EVM versions in [`go.mod`](https://github.com/ava-labs/precompile-evm/blob/hello-world-example/go.mod#L7) and [`version.sh`](https://github.com/ava-labs/precompile-evm/blob/hello-world-example/scripts/versions.sh#L4)

## Conclusion

We have now created a stateful precompile from scratch with the precompile generation tool. We hope you had fun and learned a little more about the Subnet-EVM. Now that you have created a simple stateful precompile, we urge you to create one of your own.

If you have an idea for a stateful precompile that may be useful to the community, feel free to create a fork of [Subnet-EVM](https://github.com/ava-labs/subnet-evm) and create a pull request.

# Complex Golang VM (/docs/virtual-machines/golang-vms/complex-golang-vm)

---
title: Complex Golang VM
description: In this tutorial, we'll walk through how to build a virtual machine by referencing the BlobVM.
---

The [BlobVM](https://github.com/ava-labs/blobvm) is a virtual machine that can be used to implement a decentralized key-value store. A blob (shorthand for "binary large object") is an arbitrary piece of data.

BlobVM stores a key-value pair by breaking it apart into multiple chunks stored with their hashes as their keys in the blockchain. A root key-value pair has references to these chunks for lookups. By default, the maximum chunk size is set to 200 KiB.

## Components

A VM defines how a blockchain should be built. A block is populated with a set of transactions which mutate the state of the blockchain when executed. When a block with a set of transactions is applied to a given state, a state transition occurs by executing all of the transactions in the block in-order and applying it to the previous block of the blockchain. By executing a series of blocks chronologically, anyone can verify and reconstruct the state of the blockchain at an arbitrary point in time.

The BlobVM repository has a few components to handle the lifecycle of tasks from a transaction being issued to a block being accepted across the network:

- **Transaction**: A state transition
- **Mempool**: Stores pending transactions that haven't been finalized yet
- **Network**: Propagates transactions from the mempool other nodes in the network
- **Block**: Defines the block format, how to verify it, and how it should be accepted or rejected across the network
- **Block Builder**: Builds blocks by including transactions from the mempool
- **Virtual Machine**: Application-level logic. Implements the VM interface needed to interact with Avalanche consensus and defines the blueprint for the blockchain.
- **Service**: Exposes APIs so users can interact with the VM
- **Factory**: Used to initialize the VM

## Lifecycle of a Transaction

A VM will often times expose a set of APIs so users can interact with the it. In the blockchain, blocks can contain a set of transactions which mutate the blockchain's state. Let's dive into the lifecycle of a transaction from its issuance to its finalization on the blockchain.

- A user makes an API request to `service.IssueRawTx` to issue their transaction. This API will deserialize the user's transaction and forward it to the VM
- The transaction is submitted to the VM which is then added to the VM's mempool
- The VM asynchronously periodically gossips new transactions in its mempool to other nodes in the network so they can learn about them
- The VM sends the Avalanche consensus engine a message to indicate that it has transactions in the mempool that are ready to be built into a block
- The VM proposes the block with to consensus
- Consensus verifies that the block is valid and well-formed
- Consensus gets the network to vote on whether the block should be accepted or rejected. If a block is rejected, its transactions are reclaimed by the mempool so they can be included in a future block. If a block is accepted, it's finalized by writing it to the blockchain.

## Coding the Virtual Machine

We'll dive into a few of the packages that are in the The BlobVM repository to learn more about how they work:

1. [`vm`](https://github.com/ava-labs/blobvm/tree/master/vm)
    - `block_builder.go`
    - `chain_vm.go`
    - `network.go`
    - `service.go`
    - `vm.go`
2. [`chain`](https://github.com/ava-labs/blobvm/tree/master/chain)
    - `unsigned_tx.go`
    - `base_tx.go`
    - `transfer_tx.go`
    - `set_tx.go`
    - `tx.go`
    - `block.go`
    - `mempool.go`
    - `storage.go`
    - `builder.go`
3. [`mempool`](https://github.com/ava-labs/blobvm/tree/master/mempool)
    - `mempool.go`

### Transactions

The state the blockchain can only be mutated by getting the network to accept a signed transaction. A signed transaction contains the transaction to be executed alongside the signature of the issuer. The signature is required to cryptographically verify the sender's identity. A VM can define an arbitrary amount of unique transactions types to support different operations on the blockchain. The BlobVM implements two different transactions types:

- [TransferTx](https://github.com/ava-labs/blobvm/blob/master/chain/transfer_tx.go) - Transfers coins between accounts.
- [SetTx](https://github.com/ava-labs/blobvm/blob/master/chain/set_tx.go) - Stores a key-value pair on the blockchain.

#### UnsignedTransaction

All transactions in the BlobVM implement the common [`UnsignedTransaction`](https://github.com/ava-labs/blobvm/blob/master/chain/unsigned_tx.go) interface, which exposes shared functionality for all transaction types.

```go
type UnsignedTransaction interface {
	Copy() UnsignedTransaction
	GetBlockID() ids.ID
	GetMagic() uint64
	GetPrice() uint64
	SetBlockID(ids.ID)
	SetMagic(uint64)
	SetPrice(uint64)
	FeeUnits(*Genesis) uint64  // number of units to mine tx
	LoadUnits(*Genesis) uint64 // units that should impact fee rate

	ExecuteBase(*Genesis) error
	Execute(*TransactionContext) error
	TypedData() *tdata.TypedData
	Activity() *Activity
}
```

#### BaseTx

Common functionality and metadata for transaction types are implemented by [`BaseTx`](https://github.com/ava-labs/blobvm/blob/master/chain/base_tx.go).

- [`SetBlockID`](https://github.com/ava-labs/blobvm/blob/master/chain/base_tx.go#L26) sets the transaction's block ID.
- [`GetBlockID`](https://github.com/ava-labs/blobvm/blob/master/chain/base_tx.go#L22) returns the transaction's block ID.
- [`SetMagic`](https://github.com/ava-labs/blobvm/blob/master/chain/base_tx.go#L34) sets the magic number. The magic number is used to differentiate chains to prevent replay attacks
- [`GetMagic`](https://github.com/ava-labs/blobvm/blob/master/chain/base_tx.go#L30) returns the magic number. Magic number is defined in genesis.
- [`SetPrice`](https://github.com/ava-labs/blobvm/blob/master/chain/base_tx.go#L42) sets the price per fee unit for this transaction.
- [`GetPrice`](https://github.com/ava-labs/blobvm/blob/master/chain/base_tx.go#L38) returns the price for this transaction.
- [`FeeUnits`](https://github.com/ava-labs/blobvm/blob/master/chain/base_tx.go#L59) returns the fee units this transaction will consume.
- [`LoadUnits`](https://github.com/ava-labs/blobvm/blob/master/chain/base_tx.go#L63) identical to `FeeUnits`
- [`ExecuteBase`](https://github.com/ava-labs/blobvm/blob/master/chain/base_tx.go#L46) executes common validation checks across different transaction types. This validates the transaction contains a valid block ID, magic number, and gas price as defined by genesis.

#### TransferTx

[`TransferTx`](https://github.com/ava-labs/blobvm/blob/master/chain/transfer_tx.go#L16) supports the transfer of tokens from one account to another.

```go
type TransferTx struct {
	*BaseTx `serialize:"true" json:"baseTx"`

	// To is the recipient of the [Units].
	To common.Address `serialize:"true" json:"to"`

	// Units are transferred to [To].
	Units uint64 `serialize:"true" json:"units"`
}
```

`TransferTx` embeds `BaseTx` to avoid re-implementing common operations with other transactions, but implements its own [`Execute`](https://github.com/ava-labs/blobvm/blob/master/chain/transfer_tx.go#L26) to support token transfers.

This performs a few checks to ensure that the transfer is valid before transferring the tokens between the two accounts.

```go
func (t *TransferTx) Execute(c *TransactionContext) error {
	// Must transfer to someone
	if bytes.Equal(t.To[:], zeroAddress[:]) {
		return ErrNonActionable
	}

	// This prevents someone from transferring to themselves.
	if bytes.Equal(t.To[:], c.Sender[:]) {
		return ErrNonActionable
	}
	if t.Units == 0 {
		return ErrNonActionable
	}
	if _, err := ModifyBalance(c.Database, c.Sender, false, t.Units); err != nil {
		return err
	}
	if _, err := ModifyBalance(c.Database, t.To, true, t.Units); err != nil {
		return err
	}
	return nil
}
```

#### SetTx

`SetTx` is used to assign a value to a key.

```go
type SetTx struct {
	*BaseTx `serialize:"true" json:"baseTx"`
	Value []byte `serialize:"true" json:"value"`
}
```

`SetTx` implements its own [`FeeUnits`](https://github.com/ava-labs/blobvm/blob/master/chain/set_tx.go#L48) method to compensate the network according to the size of the blob being stored.

```go
func (s *SetTx) FeeUnits(g *Genesis) uint64 {
	// We don't subtract by 1 here because we want to charge extra for any
	// value-based interaction (even if it is small or a delete).
	return s.BaseTx.FeeUnits(g) + valueUnits(g, uint64(len(s.Value)))
}
```

`SetTx`'s [`Execute`](https://github.com/ava-labs/blobvm/blob/master/chain/set_tx.go#L21) method performs a few safety checks to validate that the blob meets the size constraints enforced by genesis and doesn't overwrite an existing key before writing it to the blockchain.

```go
func (s *SetTx) Execute(t *TransactionContext) error {
	g := t.Genesis
	switch {
	case len(s.Value) == 0:
		return ErrValueEmpty
	case uint64(len(s.Value)) > g.MaxValueSize:
		return ErrValueTooBig
	}

	k := ValueHash(s.Value)

	// Do not allow duplicate value setting
	_, exists, err := GetValueMeta(t.Database, k)
	if err != nil {
		return err
	}
	if exists {
		return ErrKeyExists
	}

	return PutKey(t.Database, k, &ValueMeta{
		Size:    uint64(len(s.Value)),
		TxID:    t.TxID,
		Created: t.BlockTime,
	})
}
```

#### Signed Transaction

The unsigned transactions mentioned previously can't be issued to the network without first being signed. BlobVM implements signed transactions by embedding the unsigned transaction alongside its signature in [`Transaction`](https://github.com/ava-labs/blobvm/blob/master/chain/tx.go). In BlobVM, a signature is defined as the [ECDSA signature](https://en.wikipedia.org/wiki/Elliptic_Curve_Digital_Signature_Algorithm) of the issuer's private key of the [KECCAK256](https://keccak.team/keccak.html) hash of the unsigned transaction's data ([digest hash](https://eips.ethereum.org/EIPS/eip-712)).

```go
type Transaction struct {
	UnsignedTransaction `serialize:"true" json:"unsignedTransaction"`
	Signature           []byte `serialize:"true" json:"signature"`

	digestHash []byte
	bytes      []byte
	id         ids.ID
	size       uint64
	sender     common.Address
}
```

The `Transaction` type wraps any unsigned transaction. When a `Transaction` is executed, it calls the `Execute` method of the underlying embedded `UnsignedTx` and performs the following sanity checks:

1.  The underlying `UnsignedTx` must meet the requirements set by genesis. This includes checks to make sure that the transaction contains the correct magic number and meets the minimum gas price as defined by genesis
2.  The transaction's block ID must be a recently accepted block
3.  The transaction must not be a recently issued transaction
4.  The issuer of the transaction must have enough gas
5.  The transaction's gas price must be meet the next expected block's minimum gas price
6.  The transaction must execute without error

If the transaction is successfully verified, it's submitted as a pending write to the blockchain.

```go
func (t *Transaction) Execute(g *Genesis, db database.Database, blk *StatelessBlock, context *Context) error {
	if err := t.UnsignedTransaction.ExecuteBase(g); err != nil {
		return err
	}
	if !context.RecentBlockIDs.Contains(t.GetBlockID()) {
		// Hash must be recent to be any good
		// Should not happen because of mempool cleanup
		return ErrInvalidBlockID
	}
	if context.RecentTxIDs.Contains(t.ID()) {
		// Tx hash must not be recently executed (otherwise could be replayed)
		//
		// NOTE: We only need to keep cached tx hashes around as long as the
		// block hash referenced in the tx is valid
		return ErrDuplicateTx
	}

	// Ensure sender has balance
	if _, err := ModifyBalance(db, t.sender, false, t.FeeUnits(g)*t.GetPrice()); err != nil {
		return err
	}
	if t.GetPrice() < context.NextPrice {
		return ErrInsufficientPrice
	}
	if err := t.UnsignedTransaction.Execute(&TransactionContext{
		Genesis:   g,
		Database:  db,
		BlockTime: uint64(blk.Tmstmp),
		TxID:      t.id,
		Sender:    t.sender,
	}); err != nil {
		return err
	}
	if err := SetTransaction(db, t); err != nil {
		return err
	}
	return nil
}
```

##### Example

Let's walk through an example on how to issue a `SetTx` transaction to the BlobVM to write a key-value pair.

1. Create the unsigned transaction for `SetTx`

	```go
	utx := &chain.SetTx{
		BaseTx: &chain.BaseTx{},
		Value:  []byte("data"),
	}

	utx.SetBlockID(lastAcceptedID)
	utx.SetMagic(genesis.Magic)
	utx.SetPrice(price + blockCost/utx.FeeUnits(genesis))
	```

2. Calculate the [digest hash](https://github.com/ava-labs/blobvm/blob/master/chain/tx.go#L41) for the transaction.

	```go
	digest, err := chain.DigestHash(utx)
	```

3. [Sign](https://github.com/ava-labs/blobvm/blob/master/chain/crypto.go#L17) the digest hash with the issuer's private key.

	```go
	signature, err := chain.Sign(digest, privateKey)
	```

4. Create and initialize the new signed transaction.

	```go
	tx := chain.NewTx(utx, sig)
	if err := tx.Init(g); err != nil {
		return ids.Empty, 0, err
	}
	```

5. Issue the request with the client

	```
	txID, err = cli.IssueRawTx(ctx, tx.Bytes())
	```

### Mempool

#### Overview

The [mempool](https://github.com/ava-labs/blobvm/blob/master/mempool/mempool.go) is a buffer of volatile memory that stores pending transactions. Transactions are stored in the mempool whenever a node learns about a new transaction either through gossip with other nodes or through an API call issued by a user.

The mempool is implemented as a min-max [heap](https://en.wikipedia.org/wiki/Heap_data_structure) ordered by each transaction's gas price. The mempool is created during the [initialization](https://github.com/ava-labs/blobvm/blob/master/vm/vm.go#L93) of VM.

```go
vm.mempool = mempool.New(vm.genesis, vm.config.MempoolSize)
```

Whenever a transaction is submitted to VM, it first gets initialized, verified, and executed locally. If the transaction looks valid, then it's added to the [mempool](https://github.com/ava-labs/blobvm/blob/master/vm/vm.go#L414).

#### Add Method

When a transaction is added to the mempool, [`Add`](https://github.com/ava-labs/blobvm/blob/master/mempool/mempool.go#L43) is called. This performs the following:

- Checks if the transaction being added already exists in the mempool or not
- The transaction is added to the min-max heap
- If the mempool's heap size is larger than the maximum configured value, then the lowest paying transaction is evicted
- The transaction is added to the list of transactions that are able to be gossiped to other peers
- A notification is sent through the in the `mempool.Pending` channel to indicate that the consensus engine should build a new block

### Block Builder

#### Overview

The [`TimeBuilder`](https://github.com/ava-labs/blobvm/blob/master/vm/block_builder.go) implementation for `BlockBuilder` acts as an intermediary notification service between the mempool and the consensus engine. It serves the following functions:

- Periodically gossips new transactions to other nodes in the network
- Periodically notifies the consensus engine that new transactions from the mempool are ready to be built into blocks

`TimeBuilder` and can exist in 3 states:

- `dontBuild` - There are no transactions in the mempool that are ready to be included in a block
- `building` - The consensus engine has been notified that it should build a block and there are currently transactions in the mempool that are eligible to be included into a block
- `mayBuild` - There are transactions in the mempool that are eligible to be included into a block, but the consensus engine has not been notified yet

#### Gossip Method

The [`Gossip`](https://github.com/ava-labs/blobvm/blob/master/vm/block_builder.go#L183) method initiates the gossip of new transactions from the mempool at periodically as defined by `vm.config.GossipInterval`.

#### Build Method

The [`Build`](https://github.com/ava-labs/blobvm/blob/master/vm/block_builder.go#L166) method consumes transactions from the mempool and signals the consensus engine when it's ready to build a block.

If the mempool signals the `TimeBuilder` that it has available transactions, `TimeBuilder` will signal consensus that the VM is ready to build a block by sending the consensus engine a `common.PendingTxs` message.

When the consensus engine receives the `common.PendingTxs` message it calls the VM's `BuildBlock` method. The VM will then build a block from eligible transactions in the mempool.

If there are still remaining transactions in the mempool after a block is built, then the `TimeBuilder` is put into the `mayBuild` state to indicate that there are still transactions that are eligible to be built into block, but the consensus engine isn't aware of it yet.

### Network

[Network](https://github.com/ava-labs/blobvm/blob/master/vm/network.go) handles the workflow of gossiping transactions from a node's mempool to other nodes in the network.

#### GossipNewTxs Method

`GossipNewTxs` sends a list of transactions to other nodes in the network. `TimeBuilder` calls the network's `GossipNewTxs` function to gossip new transactions in the mempool.

```go
func (n *PushNetwork) GossipNewTxs(newTxs []*chain.Transaction) error {
	txs := []*chain.Transaction{}
	// Gossip at most the target units of a block at once
	for _, tx := range newTxs {
		if _, exists := n.gossipedTxs.Get(tx.ID()); exists {
			log.Debug("already gossiped, skipping", "txId", tx.ID())
			continue
		}
		n.gossipedTxs.Put(tx.ID(), nil)
		txs = append(txs, tx)
	}

	return n.sendTxs(txs)
}
```

Recently gossiped transactions are maintained in a cache to avoid DDoSing a node from repeated gossip failures.

Other nodes in the network will receive the gossiped transactions through their `AppGossip` handler. Once a gossip message is received, it's deserialized and the new transactions are submitted to the VM.

```go
func (vm *VM) AppGossip(nodeID ids.NodeID, msg []byte) error {
	txs := make([]*chain.Transaction, 0)
	if _, err := chain.Unmarshal(msg, &txs); err != nil {
		return nil
	}

	// submit incoming gossip
	log.Debug("AppGossip transactions are being submitted", "txs", len(txs))
	if errs := vm.Submit(txs...); len(errs) > 0 {
		for _, err := range errs {

		}
	}

	return nil
}
```

### Block

Blocks go through a lifecycle of being proposed by a validator, verified, and decided by consensus. Upon acceptance, a block will be committed and will be finalized on the blockchain.

BlobVM implements two types of blocks, `StatefulBlock` and `StatelessBlock`.

#### StatefulBlock

A [`StatefulBlock`](https://github.com/ava-labs/blobvm/blob/master/chain/block.go#L27) contains strictly the metadata about the block that needs to be written to the database.

```go
type StatefulBlock struct {
	Prnt        ids.ID         `serialize:"true" json:"parent"`
	Tmstmp      int64          `serialize:"true" json:"timestamp"`
	Hght        uint64         `serialize:"true" json:"height"`
	Price       uint64         `serialize:"true" json:"price"`
	Cost        uint64         `serialize:"true" json:"cost"`
	AccessProof common.Hash    `serialize:"true" json:"accessProof"`
	Txs         []*Transaction `serialize:"true" json:"txs"`
}
```

#### StatelessBlock

[StatelessBlock](https://github.com/ava-labs/blobvm/blob/master/chain/block.go#L40) is a superset of `StatefulBlock` and additionally contains fields that are needed to support block-level operations like verification and acceptance throughout its lifecycle in the VM.

```go
type StatelessBlock struct {
	*StatefulBlock   `serialize:"true" json:"block"`
	id                ids.ID
	st                choices.Status
	t                 time.Time
	bytes             []byte
	vm                VM
	children          []*StatelessBlock
	onAcceptDB        *versiondb.Database
}
```

Let's have a look at the fields of StatelessBlock:

- `StatefulBlock`: The metadata about the block that will be written to the database upon acceptance
- `bytes`: The serialized form of the `StatefulBlock`.
- `id`: The Keccak256 hash of `bytes`.
- `st`: The status of the block in consensus (i.e `Processing`, `Accepted`, or `Rejected`)
- `children`: The children of this block
- `onAcceptDB`: The database this block should be written to upon acceptance.

When the consensus engine tries to build a block by calling the VM's `BuildBlock`, the VM calls the [`block.NewBlock`](https://github.com/ava-labs/blobvm/blob/master/chain/block.go#L53) function to get a new block that is a child of the currently preferred block.

```go
func NewBlock(vm VM, parent snowman.Block, tmstp int64, context *Context) *StatelessBlock {
    return &StatelessBlock{
        StatefulBlock: &StatefulBlock{
            Tmstmp: tmstp,
            Prnt:   parent.ID(),
            Hght:   parent.Height() + 1,
            Price:  context.NextPrice,
            Cost:   context.NextCost,
        },
        vm: vm,
        st: choices.Processing,
    }
}
```

Some `StatelessBlock` fields like the block ID, byte representation, and timestamp aren't populated immediately. These are set during the `StatelessBlock`'s [`init`](https://github.com/ava-labs/blobvm/blob/master/chain/block.go#L113) method, which initializes these fields once the block has been populated with transactions.

```go
func (b *StatelessBlock) init() error {
	bytes, err := Marshal(b.StatefulBlock)
	if err != nil {
		return err
	}
	b.bytes = bytes

	id, err := ids.ToID(crypto.Keccak256(b.bytes))
	if err != nil {
		return err
	}
	b.id = id
	b.t = time.Unix(b.StatefulBlock.Tmstmp, 0)
	g := b.vm.Genesis()
	for _, tx := range b.StatefulBlock.Txs {
		if err := tx.Init(g); err != nil {
			return err
		}
	}
	return nil
}
```

To build the block, the VM will try to remove as many of the highest-paying transactions from the mempool to include them in the new block until the maximum block fee set by genesis is reached.

A block once built, can exist in two states:

1. Rejected: The block was not accepted by consensus. In this case, the mempool will reclaim the rejected block's transactions so they can be included in a future block.
2. Accepted: The block was accepted by consensus. In this case, we write the block to the blockchain by committing it to the database.

When the consensus engine receives the built block, it calls the block's [`Verify`](https://github.com/ava-labs/blobvm/blob/master/chain/block.go#L228) method to validate that the block is well-formed. In BlobVM, the following constraints are placed on valid blocks:

1. A block must contain at least one transaction and the block's timestamp must be within 10s into the future.

	```go
	if len(b.Txs) == 0 {
	return nil, nil, ErrNoTxs
	}
	if b.Timestamp().Unix() >= time.Now().Add(futureBound).Unix() {
	return nil, nil, ErrTimestampTooLate
	}
	```

2. The sum of the gas units consumed by the transactions in the block must not exceed the gas limit defined by genesis.

	```go
	blockSize := uint64(0)
	for _, tx := range b.Txs {
	blockSize += tx.LoadUnits(g)
	if blockSize > g.MaxBlockSize {
		return nil, nil, ErrBlockTooBig
	}
	}
	```

3. The parent block of the proposed block must exist and have an earlier timestamp.

	```go
	parent, err := b.vm.GetStatelessBlock(b.Prnt)
	if err != nil {
	log.Debug("could not get parent", "id", b.Prnt)
	return nil, nil, err
	}
	if b.Timestamp().Unix() < parent.Timestamp().Unix() {
	return nil, nil, ErrTimestampTooEarly
	}
	```

4. The target block price and minimum gas price must meet the minimum enforced by the VM.

	```go
	context, err := b.vm.ExecutionContext(b.Tmstmp, parent)
	if err != nil {
	return nil, nil, err
	}
	if b.Cost != context.NextCost {
	return nil, nil, ErrInvalidCost
	}
	if b.Price != context.NextPrice {
	return nil, nil, ErrInvalidPrice
	}
	```

After the results of consensus are complete, the block is either accepted by committing the block to the database or rejected by returning the block's transactions into the mempool.

```go
// implements "snowman.Block.choices.Decidable"
func (b *StatelessBlock) Accept() error {
	if err := b.onAcceptDB.Commit(); err != nil {
		return err
	}
	for _, child := range b.children {
		if err := child.onAcceptDB.SetDatabase(b.vm.State()); err != nil {
			return err
		}
	}
	b.st = choices.Accepted
	b.vm.Accepted(b)
	return nil
}

// implements "snowman.Block.choices.Decidable"
func (b *StatelessBlock) Reject() error {
	b.st = choices.Rejected
	b.vm.Rejected(b)
	return nil
}
```

### API

[Service](https://github.com/ava-labs/blobvm/blob/master/vm/public_service.go) implements an API server so users can interact with the VM. The VM implements the interface method [`CreateHandlers`](https://github.com/ava-labs/blobvm/blob/master/vm/vm.go#L267) that exposes the VM's RPC API.

```go
func (vm *VM) CreateHandlers() (map[string]*common.HTTPHandler, error) {
    apis := map[string]*common.HTTPHandler{}
    public, err := newHandler(Name, &PublicService{vm: vm})
    if err != nil {
        return nil, err
    }
    apis[PublicEndpoint] = public
    return apis, nil
}
```

One API that's exposed is [`IssueRawTx`](https://github.com/ava-labs/blobvm/blob/master/vm/public_service.go#L63) to allow users to issue transactions to the BlobVM. It accepts an `IssueRawTxArgs` that contains the transaction the user wants to issue and forwards it to the VM.

```go
func (svc *PublicService) IssueRawTx(_ *http.Request, args *IssueRawTxArgs, reply *IssueRawTxReply) error {
	tx := new(chain.Transaction)
	if _, err := chain.Unmarshal(args.Tx, tx); err != nil {
		return err
	}

	// otherwise, unexported tx.id field is empty
	if err := tx.Init(svc.vm.genesis); err != nil {
		return err
	}
	reply.TxID = tx.ID()

	errs := svc.vm.Submit(tx)
	if len(errs) == 0 {
		return nil
	}
	if len(errs) == 1 {
		return errs[0]
	}
	return fmt.Errorf("%v", errs)
}
```

### Virtual Machine

We have learned about all the components used in the BlobVM. Most of these components are referenced in the `vm.go` file, which acts as the entry point for the consensus engine as well as users interacting with the blockchain.

For example, the engine calls `vm.BuildBlock()`, that in turn calls `chain.BuildBlock()`. Another example is when a user issues a raw transaction through service APIs, the `vm.Submit()` method is called.

Let's look at some of the important methods of `vm.go` that must be implemented:

#### Initialize Method

[Initialize](https://github.com/ava-labs/blobvm/blob/master/vm/vm.go#L93) is invoked by `avalanchego` when creating the blockchain. `avalanchego` passes some parameters to the implementing VM.

- `ctx` - Metadata about the VM's execution
- `dbManager` - The database that the VM can write to
- `genesisBytes` - The serialized representation of the genesis state of this VM
- `upgradeBytes` - The serialized representation of network upgrades
- `configBytes` - The serialized VM-specific [configuration](https://github.com/ava-labs/blobvm/blob/master/vm/config.go#L10)
- `toEngine` - The channel used to send messages to the consensus engine
- `fxs` - Feature extensions that attach to this VM
- `appSender` - Used to send messages to other nodes in the network

BlobVM upon initialization persists these fields in its own state to use them throughout the lifetime of its execution.

```go
// implements "snowmanblock.ChainVM.common.VM"
func (vm *VM) Initialize(
	ctx *snow.Context,
	dbManager manager.Manager,
	genesisBytes []byte,
	upgradeBytes []byte,
	configBytes []byte,
	toEngine chan<- common.Message,
	_ []*common.Fx,
	appSender common.AppSender,
) error {
	log.Info("initializing blobvm", "version", version.Version)

	// Load config
	vm.config.SetDefaults()
	if len(configBytes) > 0 {
		if err := ejson.Unmarshal(configBytes, &vm.config); err != nil {
			return fmt.Errorf("failed to unmarshal config %s: %w", string(configBytes), err)
		}
	}

	vm.ctx = ctx
	vm.db = dbManager.Current().Database
	vm.activityCache = make([]*chain.Activity, vm.config.ActivityCacheSize)

	// Init channels before initializing other structs
	vm.stop = make(chan struct{})
	vm.builderStop = make(chan struct{})
	vm.doneBuild = make(chan struct{})
	vm.doneGossip = make(chan struct{})
	vm.appSender = appSender
	vm.network = vm.NewPushNetwork()

	vm.blocks = &cache.LRU{Size: blocksLRUSize}
	vm.verifiedBlocks = make(map[ids.ID]*chain.StatelessBlock)

	vm.toEngine = toEngine
	vm.builder = vm.NewTimeBuilder()

	// Try to load last accepted
	has, err := chain.HasLastAccepted(vm.db)
	if err != nil {
		log.Error("could not determine if have last accepted")
		return err
	}

	// Parse genesis data
	vm.genesis = new(chain.Genesis)
	if err := ejson.Unmarshal(genesisBytes, vm.genesis); err != nil {
		log.Error("could not unmarshal genesis bytes")
		return err
	}
	if err := vm.genesis.Verify(); err != nil {
		log.Error("genesis is invalid")
		return err
	}
	targetUnitsPerSecond := vm.genesis.TargetBlockSize / uint64(vm.genesis.TargetBlockRate)
	vm.targetRangeUnits = targetUnitsPerSecond * uint64(vm.genesis.LookbackWindow)
	log.Debug("loaded genesis", "genesis", string(genesisBytes), "target range units", vm.targetRangeUnits)

	vm.mempool = mempool.New(vm.genesis, vm.config.MempoolSize)

	if has { //nolint:nestif
		blkID, err := chain.GetLastAccepted(vm.db)
		if err != nil {
			log.Error("could not get last accepted", "err", err)
			return err
		}

		blk, err := vm.GetStatelessBlock(blkID)
		if err != nil {
			log.Error("could not load last accepted", "err", err)
			return err
		}

		vm.preferred, vm.lastAccepted = blkID, blk
		log.Info("initialized blobvm from last accepted", "block", blkID)
	} else {
		genesisBlk, err := chain.ParseStatefulBlock(
			vm.genesis.StatefulBlock(),
			nil,
			choices.Accepted,
			vm,
		)
		if err != nil {
			log.Error("unable to init genesis block", "err", err)
			return err
		}

		// Set Balances
		if err := vm.genesis.Load(vm.db, vm.AirdropData); err != nil {
			log.Error("could not set genesis allocation", "err", err)
			return err
		}

		if err := chain.SetLastAccepted(vm.db, genesisBlk); err != nil {
			log.Error("could not set genesis as last accepted", "err", err)
			return err
		}
		gBlkID := genesisBlk.ID()
		vm.preferred, vm.lastAccepted = gBlkID, genesisBlk
		log.Info("initialized blobvm from genesis", "block", gBlkID)
	}
	vm.AirdropData = nil
}
```

After initializing its own state, BlobVM also starts asynchronous workers to build blocks and gossip transactions to the rest of the network.

```
{
	go vm.builder.Build()
	go vm.builder.Gossip()
	return nil
}
```

#### GetBlock Method

[`GetBlock`](https://github.com/ava-labs/blobvm/blob/master/vm/vm.go#L318) returns the block with the provided ID. GetBlock will attempt to fetch the given block from the database, and return an non-nil error if it wasn't able to get it.

```go
func (vm *VM) GetBlock(id ids.ID) (snowman.Block, error) {
	b, err := vm.GetStatelessBlock(id)
	if err != nil {
		log.Warn("failed to get block", "err", err)
	}
	return b, err
}
```

#### ParseBlock Method

[`ParseBlock`](https://github.com/ava-labs/blobvm/blob/master/vm/vm.go#L373) deserializes a block.

```go
func (vm *VM) ParseBlock(source []byte) (snowman.Block, error) {
	newBlk, err := chain.ParseBlock(
		source,
		choices.Processing,
		vm,
	)
	if err != nil {
		log.Error("could not parse block", "err", err)
		return nil, err
	}
	log.Debug("parsed block", "id", newBlk.ID())

	// If we have seen this block before, return it with the most
	// up-to-date info
	if oldBlk, err := vm.GetBlock(newBlk.ID()); err == nil {
		log.Debug("returning previously parsed block", "id", oldBlk.ID())
		return oldBlk, nil
	}

	return newBlk, nil
}
```

#### BuildBlock Method

Avalanche consensus calls [`BuildBlock`](https://github.com/ava-labs/blobvm/blob/master/vm/vm.go#L397) when it receives a notification from the VM that it has pending transactions that are ready to be issued into a block.

```go
func (vm *VM) BuildBlock() (snowman.Block, error) {
	log.Debug("BuildBlock triggered")
	blk, err := chain.BuildBlock(vm, vm.preferred)
	vm.builder.HandleGenerateBlock()
	if err != nil {
		log.Debug("BuildBlock failed", "error", err)
		return nil, err
	}
	sblk, ok := blk.(*chain.StatelessBlock)
	if !ok {
		return nil, fmt.Errorf("unexpected snowman.Block %T, expected *StatelessBlock", blk)
	}

	log.Debug("BuildBlock success", "blkID", blk.ID(), "txs", len(sblk.Txs))
	return blk, nil
}
```

#### SetPreference Method

[`SetPreference`](https://github.com/ava-labs/blobvm/blob/master/vm/vm.go#L457) sets the block ID preferred by this node. A node votes to accept or reject a block based on its current preference in consensus.

```go
func (vm *VM) SetPreference(id ids.ID) error {
	log.Debug("set preference", "id", id)
	vm.preferred = id
	return nil
}
```

#### LastAccepted Method

[LastAccepted](https://github.com/ava-labs/blobvm/blob/master/vm/vm.go#L465) returns the block ID of the block that was most recently accepted by this node.

```go
func (vm *VM) LastAccepted() (ids.ID, error) {
	return vm.lastAccepted.ID(), nil
}
```

### CLI

BlobVM implements a generic key-value store, but support to read and write arbitrary files into the BlobVM blockchain is implemented in the `blob-cli`

To write a file, BlobVM breaks apart an arbitrarily large file into many small chunks. Each chunk is submitted to the VM in a `SetTx`. A root key is generated which contains all of the hashes of the chunks.

```go
func Upload(
	ctx context.Context, cli client.Client, priv *ecdsa.PrivateKey,
	f io.Reader, chunkSize int,
) (common.Hash, error) {
	hashes := []common.Hash{}
	chunk := make([]byte, chunkSize)
	shouldExit := false
	opts := []client.OpOption{client.WithPollTx()}
	totalCost := uint64(0)
	uploaded := map[common.Hash]struct{}{}
	for !shouldExit {
		read, err := f.Read(chunk)
		if errors.Is(err, io.EOF) || read == 0 {
			break
		}
		if err != nil {
			return common.Hash{}, fmt.Errorf("%w: read error", err)
		}
		if read < chunkSize {
			shouldExit = true
			chunk = chunk[:read]

			// Use small file optimization
			if len(hashes) == 0 {
				break
			}
		}
		k := chain.ValueHash(chunk)
		if _, ok := uploaded[k]; ok {
			color.Yellow("already uploaded k=%s, skipping", k)
		} else if exists, _, _, err := cli.Resolve(ctx, k); err == nil && exists {
			color.Yellow("already on-chain k=%s, skipping", k)
			uploaded[k] = struct{}{}
		} else {
			tx := &chain.SetTx{
				BaseTx: &chain.BaseTx{},
				Value:  chunk,
			}
			txID, cost, err := client.SignIssueRawTx(ctx, cli, tx, priv, opts...)
			if err != nil {
				return common.Hash{}, err
			}
			totalCost += cost
			color.Yellow("uploaded k=%s txID=%s cost=%d totalCost=%d", k, txID, cost, totalCost)
			uploaded[k] = struct{}{}
		}
		hashes = append(hashes, k)
	}

	r := &Root{}
	if len(hashes) == 0 {
		if len(chunk) == 0 {
			return common.Hash{}, ErrEmpty
		}
		r.Contents = chunk
	} else {
		r.Children = hashes
	}

	rb, err := json.Marshal(r)
	if err != nil {
		return common.Hash{}, err
	}
	rk := chain.ValueHash(rb)
	tx := &chain.SetTx{
		BaseTx: &chain.BaseTx{},
		Value:  rb,
	}
	txID, cost, err := client.SignIssueRawTx(ctx, cli, tx, priv, opts...)
	if err != nil {
		return common.Hash{}, err
	}
	totalCost += cost
	color.Yellow("uploaded root=%v txID=%s cost=%d totalCost=%d", rk, txID, cost, totalCost)
	return rk, nil
}
```

#### Example 1

```bash
blob-cli set-file ~/Downloads/computer.gif -> 6fe5a52f52b34fb1e07ba90bad47811c645176d0d49ef0c7a7b4b22013f676c8
```

Given the root hash, a file can be looked up by deserializing all of its children chunk values and reconstructing the original file.

```go
// TODO: make multi-threaded
func Download(ctx context.Context, cli client.Client, root common.Hash, f io.Writer) error {
	exists, rb, _, err := cli.Resolve(ctx, root)
	if err != nil {
		return err
	}
	if !exists {
		return fmt.Errorf("%w:%v", ErrMissing, root)
	}
	var r Root
	if err := json.Unmarshal(rb, &r); err != nil {
		return err
	}

	// Use small file optimization
	if contentLen := len(r.Contents); contentLen > 0 {
		if _, err := f.Write(r.Contents); err != nil {
			return err
		}
		color.Yellow("downloaded root=%v size=%fKB", root, float64(contentLen)/units.KiB)
		return nil
	}

	if len(r.Children) == 0 {
		return ErrEmpty
	}

	amountDownloaded := 0
	for _, h := range r.Children {
		exists, b, _, err := cli.Resolve(ctx, h)
		if err != nil {
			return err
		}
		if !exists {
			return fmt.Errorf("%w:%s", ErrMissing, h)
		}
		if _, err := f.Write(b); err != nil {
			return err
		}
		size := len(b)
		color.Yellow("downloaded chunk=%v size=%fKB", h, float64(size)/units.KiB)
		amountDownloaded += size
	}
	color.Yellow("download complete root=%v size=%fMB", root, float64(amountDownloaded)/units.MiB)
	return nil
}
```

#### Example 2

```bash
blob-cli resolve-file 6fe5a52f52b34fb1e07ba90bad47811c645176d0d49ef0c7a7b4b22013f676c8 computer_copy.gif
```

## Conclusion

This documentation covers concepts about Virtual Machine by walking through a VM that implements a decentralized key-value store.

You can learn more about the BlobVM by referencing the [README](https://github.com/ava-labs/blobvm/blob/master/README.md) in the GitHub repository.

# Simple Golang VM (/docs/virtual-machines/golang-vms/simple-golang-vm)

---
title: Simple Golang VM
description: In this tutorial, we will learn how to build a virtual machine by referencing the TimestampVM.
---

In this tutorial, we'll create a very simple VM called the [TimestampVM](https://github.com/ava-labs/timestampvm/tree/v1.2.1). Each block in the TimestampVM's blockchain contains a strictly increasing timestamp when the block was created and a 32-byte payload of data.

Such a server is useful because it can be used to prove a piece of data existed at the time the block was created. Suppose you have a book manuscript, and you want to be able to prove in the future that the manuscript exists today. You can add a block to the blockchain where the block's payload is a hash of your manuscript. In the future, you can prove that the manuscript existed today by showing that the block has the hash of your manuscript in its payload (this follows from the fact that finding the pre-image of a hash is impossible).

## TimestampVM Implementation

Now we know the interface our VM must implement and the libraries we can use to build a VM.

Let's write our VM, which implements `block.ChainVM` and whose blocks implement `snowman.Block`. You can also follow the code in the [TimestampVM repository](https://github.com/ava-labs/timestampvm/tree/main).

### Codec

`Codec` is required to encode/decode the block into byte representation. TimestampVM uses the default codec and manager.

```go title="timestampvm/codec.go"
const (
	// CodecVersion is the current default codec version
	CodecVersion = 0
)

// Codecs do serialization and deserialization
var (
	Codec codec.Manager
)

func init() {
	// Create default codec and manager
	c := linearcodec.NewDefault()
	Codec = codec.NewDefaultManager()

	// Register codec to manager with CodecVersion
	if err := Codec.RegisterCodec(CodecVersion, c); err != nil {
		panic(err)
	}
}
```

### State

The `State` interface defines the database layer and connections. Each VM should define their own database methods. `State` embeds the `BlockState` which defines block-related state operations.

```go title="timestampvm/state.go"
var (
	// These are prefixes for db keys.
	// It's important to set different prefixes for each separate database objects.
	singletonStatePrefix = []byte("singleton")
	blockStatePrefix     = []byte("block")

	_ State = &state{}
)

// State is a wrapper around avax.SingleTonState and BlockState
// State also exposes a few methods needed for managing database commits and close.
type State interface {
	// SingletonState is defined in avalanchego,
	// it is used to understand if db is initialized already.
	avax.SingletonState
	BlockState

	Commit() error
	Close() error
}

type state struct {
	avax.SingletonState
	BlockState

	baseDB *versiondb.Database
}

func NewState(db database.Database, vm *VM) State {
	// create a new baseDB
	baseDB := versiondb.New(db)

	// create a prefixed "blockDB" from baseDB
	blockDB := prefixdb.New(blockStatePrefix, baseDB)
	// create a prefixed "singletonDB" from baseDB
	singletonDB := prefixdb.New(singletonStatePrefix, baseDB)

	// return state with created sub state components
	return &state{
		BlockState:     NewBlockState(blockDB, vm),
		SingletonState: avax.NewSingletonState(singletonDB),
		baseDB:         baseDB,
	}
}

// Commit commits pending operations to baseDB
func (s *state) Commit() error {
	return s.baseDB.Commit()
}

// Close closes the underlying base database
func (s *state) Close() error {
	return s.baseDB.Close()
}
```

#### Block State

This interface and implementation provides storage functions to VM to store and retrieve blocks.

```go title="timestampvm/block_state.go"
const (
	lastAcceptedByte byte = iota
)

const (
	// maximum block capacity of the cache
	blockCacheSize = 8192
)

// persists lastAccepted block IDs with this key
var lastAcceptedKey = []byte{lastAcceptedByte}

var _ BlockState = &blockState{}

// BlockState defines methods to manage state with Blocks and LastAcceptedIDs.
type BlockState interface {
	GetBlock(blkID ids.ID) (*Block, error)
	PutBlock(blk *Block) error

	GetLastAccepted() (ids.ID, error)
	SetLastAccepted(ids.ID) error
}

// blockState implements BlocksState interface with database and cache.
type blockState struct {
	// cache to store blocks
	blkCache cache.Cacher
	// block database
	blockDB      database.Database
	lastAccepted ids.ID

	// vm reference
	vm *VM
}

// blkWrapper wraps the actual blk bytes and status to persist them together
type blkWrapper struct {
	Blk    []byte         `serialize:"true"`
	Status choices.Status `serialize:"true"`
}

// NewBlockState returns BlockState with a new cache and given db
func NewBlockState(db database.Database, vm *VM) BlockState {
	return &blockState{
		blkCache: &cache.LRU{Size: blockCacheSize},
		blockDB:  db,
		vm:       vm,
	}
}

// GetBlock gets Block from either cache or database
func (s *blockState) GetBlock(blkID ids.ID) (*Block, error) {
	// Check if cache has this blkID
	if blkIntf, cached := s.blkCache.Get(blkID); cached {
		// there is a key but value is nil, so return an error
		if blkIntf == nil {
			return nil, database.ErrNotFound
		}
		// We found it return the block in cache
		return blkIntf.(*Block), nil
	}

	// get block bytes from db with the blkID key
	wrappedBytes, err := s.blockDB.Get(blkID[:])
	if err != nil {
		// we could not find it in the db, let's cache this blkID with nil value
		// so next time we try to fetch the same key we can return error
		// without hitting the database
		if err == database.ErrNotFound {
			s.blkCache.Put(blkID, nil)
		}
		// could not find the block, return error
		return nil, err
	}

	// first decode/unmarshal the block wrapper so we can have status and block bytes
	blkw := blkWrapper{}
	if _, err := Codec.Unmarshal(wrappedBytes, &blkw); err != nil {
		return nil, err
	}

	// now decode/unmarshal the actual block bytes to block
	blk := &Block{}
	if _, err := Codec.Unmarshal(blkw.Blk, blk); err != nil {
		return nil, err
	}

	// initialize block with block bytes, status and vm
	blk.Initialize(blkw.Blk, blkw.Status, s.vm)

	// put block into cache
	s.blkCache.Put(blkID, blk)

	return blk, nil
}

// PutBlock puts block into both database and cache
func (s *blockState) PutBlock(blk *Block) error {
	// create block wrapper with block bytes and status
	blkw := blkWrapper{
		Blk:    blk.Bytes(),
		Status: blk.Status(),
	}

	// encode block wrapper to its byte representation
	wrappedBytes, err := Codec.Marshal(CodecVersion, &blkw)
	if err != nil {
		return err
	}

	blkID := blk.ID()
	// put actual block to cache, so we can directly fetch it from cache
	s.blkCache.Put(blkID, blk)

	// put wrapped block bytes into database
	return s.blockDB.Put(blkID[:], wrappedBytes)
}

// DeleteBlock deletes block from both cache and database
func (s *blockState) DeleteBlock(blkID ids.ID) error {
	s.blkCache.Put(blkID, nil)
	return s.blockDB.Delete(blkID[:])
}

// GetLastAccepted returns last accepted block ID
func (s *blockState) GetLastAccepted() (ids.ID, error) {
	// check if we already have lastAccepted ID in state memory
	if s.lastAccepted != ids.Empty {
		return s.lastAccepted, nil
	}

	// get lastAccepted bytes from database with the fixed lastAcceptedKey
	lastAcceptedBytes, err := s.blockDB.Get(lastAcceptedKey)
	if err != nil {
		return ids.ID{}, err
	}
	// parse bytes to ID
	lastAccepted, err := ids.ToID(lastAcceptedBytes)
	if err != nil {
		return ids.ID{}, err
	}
	// put lastAccepted ID into memory
	s.lastAccepted = lastAccepted
	return lastAccepted, nil
}

// SetLastAccepted persists lastAccepted ID into both cache and database
func (s *blockState) SetLastAccepted(lastAccepted ids.ID) error {
	// if the ID in memory and the given memory are same don't do anything
	if s.lastAccepted == lastAccepted {
		return nil
	}
	// put lastAccepted ID to memory
	s.lastAccepted = lastAccepted
	// persist lastAccepted ID to database with fixed lastAcceptedKey
	return s.blockDB.Put(lastAcceptedKey, lastAccepted[:])
}
```

### Block

Let's look at our block implementation. The type declaration is:

```go title="timestampvm/block.go"
// Block is a block on the chain.
// Each block contains:
// 1) ParentID
// 2) Height
// 3) Timestamp
// 4) A piece of data (a string)
type Block struct {
	PrntID ids.ID        `serialize:"true" json:"parentID"`  // parent's ID
	Hght   uint64        `serialize:"true" json:"height"`    // This block's height. The genesis block is at height 0.
	Tmstmp int64         `serialize:"true" json:"timestamp"` // Time this block was proposed at
	Dt     [dataLen]byte `serialize:"true" json:"data"`      // Arbitrary data

	id     ids.ID         // hold this block's ID
	bytes  []byte         // this block's encoded bytes
	status choices.Status // block's status
	vm     *VM            // the underlying VM reference, mostly used for state
}
```

The `serialize:"true"` tag indicates that the field should be included in the byte representation of the block used when persisting the block or sending it to other nodes.

#### Verify

This method verifies that a block is valid and stores it in the memory. It is important to store the verified block in the memory and return them in the `vm.GetBlock` method.

```go title="timestampvm/block.go"
// Verify returns nil iff this block is valid.
// To be valid, it must be that:
// b.parent.Timestamp < b.Timestamp <= [local time] + 1 hour
func (b *Block) Verify() error {
	// Get [b]'s parent
	parentID := b.Parent()
	parent, err := b.vm.getBlock(parentID)
	if err != nil {
		return errDatabaseGet
	}

	// Ensure [b]'s height comes right after its parent's height
	if expectedHeight := parent.Height() + 1; expectedHeight != b.Hght {
		return fmt.Errorf(
			"expected block to have height %d, but found %d",
			expectedHeight,
			b.Hght,
		)
	}

	// Ensure [b]'s timestamp is after its parent's timestamp.
	if b.Timestamp().Unix() < parent.Timestamp().Unix() {
		return errTimestampTooEarly
	}

	// Ensure [b]'s timestamp is not more than an hour
	// ahead of this node's time
	if b.Timestamp().Unix() >= time.Now().Add(time.Hour).Unix() {
		return errTimestampTooLate
	}

	// Put that block to verified blocks in memory
	b.vm.verifiedBlocks[b.ID()] = b

	return nil
}
```

#### Accept

`Accept` is called by the consensus to indicate this block is accepted.

```go title="timestampvm/block.go"
// Accept sets this block's status to Accepted and sets lastAccepted to this
// block's ID and saves this info to b.vm.DB
func (b *Block) Accept() error {
	b.SetStatus(choices.Accepted) // Change state of this block
	blkID := b.ID()

	// Persist data
	if err := b.vm.state.PutBlock(b); err != nil {
		return err
	}

	// Set last accepted ID to this block ID
	if err := b.vm.state.SetLastAccepted(blkID); err != nil {
		return err
	}

	// Delete this block from verified blocks as it's accepted
	delete(b.vm.verifiedBlocks, b.ID())

	// Commit changes to database
	return b.vm.state.Commit()
}
```

#### Reject

`Reject` is called by the consensus to indicate this block is rejected.

```go title="timestampvm/block.go"
// Reject sets this block's status to Rejected and saves the status in state
// Recall that b.vm.DB.Commit() must be called to persist to the DB
func (b *Block) Reject() error {
	b.SetStatus(choices.Rejected) // Change state of this block
	if err := b.vm.state.PutBlock(b); err != nil {
		return err
	}
	// Delete this block from verified blocks as it's rejected
	delete(b.vm.verifiedBlocks, b.ID())
	// Commit changes to database
	return b.vm.state.Commit()
}
```

#### Block Field Methods

These methods are required by the `snowman.Block` interface.

```go title="timestampvm/block.go"
// ID returns the ID of this block
func (b *Block) ID() ids.ID { return b.id }

// ParentID returns [b]'s parent's ID
func (b *Block) Parent() ids.ID { return b.PrntID }

// Height returns this block's height. The genesis block has height 0.
func (b *Block) Height() uint64 { return b.Hght }

// Timestamp returns this block's time. The genesis block has time 0.
func (b *Block) Timestamp() time.Time { return time.Unix(b.Tmstmp, 0) }

// Status returns the status of this block
func (b *Block) Status() choices.Status { return b.status }

// Bytes returns the byte repr. of this block
func (b *Block) Bytes() []byte { return b.bytes }
```

#### Helper Functions

These methods are convenience methods for blocks, they're not a part of the block interface.

```go
// Initialize sets [b.bytes] to [bytes], [b.id] to hash([b.bytes]),
// [b.status] to [status] and [b.vm] to [vm]
func (b *Block) Initialize(bytes []byte, status choices.Status, vm *VM) {
	b.bytes = bytes
	b.id = hashing.ComputeHash256Array(b.bytes)
	b.status = status
	b.vm = vm
}

// SetStatus sets the status of this block
func (b *Block) SetStatus(status choices.Status) { b.status = status }
```

### Virtual Machine

Now, let's look at our timestamp VM implementation, which implements the `block.ChainVM` interface. The declaration is:

```go title="timestampvm/vm.go"
// This Virtual Machine defines a blockchain that acts as a timestamp server
// Each block contains data (a payload) and the timestamp when it was created

const (
  dataLen = 32
	Name    = "timestampvm"
)

// VM implements the snowman.VM interface
// Each block in this chain contains a Unix timestamp
// and a piece of data (a string)
type VM struct {
	// The context of this vm
	ctx       *snow.Context
	dbManager manager.Manager

	// State of this VM
	state State

	// ID of the preferred block
	preferred ids.ID

	// channel to send messages to the consensus engine
	toEngine chan<- common.Message

	// Proposed pieces of data that haven't been put into a block and proposed yet
	mempool [][dataLen]byte

	// Block ID --> Block
	// Each element is a block that passed verification but
	// hasn't yet been accepted/rejected
	verifiedBlocks map[ids.ID]*Block
}
```

#### Initialize

This method is called when a new instance of VM is initialized. Genesis block is created under this method.

```go title="timestampvm/vm.go"
// Initialize this vm
// [ctx] is this vm's context
// [dbManager] is the manager of this vm's database
// [toEngine] is used to notify the consensus engine that new blocks are
//   ready to be added to consensus
// The data in the genesis block is [genesisData]
func (vm *VM) Initialize(
	ctx *snow.Context,
	dbManager manager.Manager,
	genesisData []byte,
	upgradeData []byte,
	configData []byte,
	toEngine chan<- common.Message,
	_ []*common.Fx,
	_ common.AppSender,
) error {
	version, err := vm.Version()
	if err != nil {
		log.Error("error initializing Timestamp VM: %v", err)
		return err
	}
	log.Info("Initializing Timestamp VM", "Version", version)

	vm.dbManager = dbManager
	vm.ctx = ctx
	vm.toEngine = toEngine
	vm.verifiedBlocks = make(map[ids.ID]*Block)

	// Create new state
	vm.state = NewState(vm.dbManager.Current().Database, vm)

	// Initialize genesis
	if err := vm.initGenesis(genesisData); err != nil {
		return err
	}

	// Get last accepted
	lastAccepted, err := vm.state.GetLastAccepted()
	if err != nil {
		return err
	}

	ctx.Log.Info("initializing last accepted block as %s", lastAccepted)

	// Build off the most recently accepted block
	return vm.SetPreference(lastAccepted)
}
```

#### `initGenesis`

`initGenesis` is a helper method which initializes the genesis block from given bytes and puts into the state.

```go title="timestampvm/vm.go"
// Initializes Genesis if required
func (vm *VM) initGenesis(genesisData []byte) error {
	stateInitialized, err := vm.state.IsInitialized()
	if err != nil {
		return err
	}

	// if state is already initialized, skip init genesis.
	if stateInitialized {
		return nil
	}

	if len(genesisData) > dataLen {
		return errBadGenesisBytes
	}

	// genesisData is a byte slice but each block contains an byte array
	// Take the first [dataLen] bytes from genesisData and put them in an array
	var genesisDataArr [dataLen]byte
	copy(genesisDataArr[:], genesisData)

	// Create the genesis block
	// Timestamp of genesis block is 0. It has no parent.
	genesisBlock, err := vm.NewBlock(ids.Empty, 0, genesisDataArr, time.Unix(0, 0))
	if err != nil {
		log.Error("error while creating genesis block: %v", err)
		return err
	}

	// Put genesis block to state
	if err := vm.state.PutBlock(genesisBlock); err != nil {
		log.Error("error while saving genesis block: %v", err)
		return err
	}

	// Accept the genesis block
	// Sets [vm.lastAccepted] and [vm.preferred]
	if err := genesisBlock.Accept(); err != nil {
		return fmt.Errorf("error accepting genesis block: %w", err)
	}

	// Mark this vm's state as initialized, so we can skip initGenesis in further restarts
	if err := vm.state.SetInitialized(); err != nil {
		return fmt.Errorf("error while setting db to initialized: %w", err)
	}

	// Flush VM's database to underlying db
	return vm.state.Commit()
}
```

#### CreateHandlers

Registered handlers defined in `Service`. See [below](/docs/virtual-machines/golang-vms/simple-golang-vm#api) for more on APIs.

```go title="timestampvm/vm.go"
// CreateHandlers returns a map where:
// Keys: The path extension for this blockchain's API (empty in this case)
// Values: The handler for the API
// In this case, our blockchain has only one API, which we name timestamp,
// and it has no path extension, so the API endpoint:
// [Node IP]/ext/bc/[this blockchain's ID]
// See API section in documentation for more information
func (vm *VM) CreateHandlers() (map[string]*common.HTTPHandler, error) {
	server := rpc.NewServer()
	server.RegisterCodec(json.NewCodec(), "application/json")
	server.RegisterCodec(json.NewCodec(), "application/json;charset=UTF-8")
    // Name is "timestampvm"
	if err := server.RegisterService(&Service{vm: vm}, Name); err != nil {
		return nil, err
	}

	return map[string]*common.HTTPHandler{
		"": {
			Handler: server,
		},
	}, nil
}
```

#### CreateStaticHandlers

Registers static handlers defined in `StaticService`. See [below](/docs/virtual-machines/golang-vms/simple-golang-vm#static-api) for more on static APIs.

```go title="timestampvm/vm.go"
// CreateStaticHandlers returns a map where:
// Keys: The path extension for this VM's static API
// Values: The handler for that static API
func (vm *VM) CreateStaticHandlers() (map[string]*common.HTTPHandler, error) {
	server := rpc.NewServer()
	server.RegisterCodec(json.NewCodec(), "application/json")
	server.RegisterCodec(json.NewCodec(), "application/json;charset=UTF-8")
	if err := server.RegisterService(&StaticService{}, Name); err != nil {
		return nil, err
	}

	return map[string]*common.HTTPHandler{
		"": {
			LockOptions: common.NoLock,
			Handler:     server,
		},
	}, nil
}
```

#### BuildBock

`BuildBlock` builds a new block and returns it. This is mainly requested by the consensus engine.

```go title="timestampvm/vm.go"
// BuildBlock returns a block that this vm wants to add to consensus
func (vm *VM) BuildBlock() (snowman.Block, error) {
	if len(vm.mempool) == 0 { // There is no block to be built
		return nil, errNoPendingBlocks
	}

	// Get the value to put in the new block
	value := vm.mempool[0]
	vm.mempool = vm.mempool[1:]

	// Notify consensus engine that there are more pending data for blocks
	// (if that is the case) when done building this block
	if len(vm.mempool) > 0 {
		defer vm.NotifyBlockReady()
	}

	// Gets Preferred Block
	preferredBlock, err := vm.getBlock(vm.preferred)
	if err != nil {
		return nil, fmt.Errorf("couldn't get preferred block: %w", err)
	}
	preferredHeight := preferredBlock.Height()

	// Build the block with preferred height
	newBlock, err := vm.NewBlock(vm.preferred, preferredHeight+1, value, time.Now())
	if err != nil {
		return nil, fmt.Errorf("couldn't build block: %w", err)
	}

	// Verifies block
	if err := newBlock.Verify(); err != nil {
		return nil, err
	}
	return newBlock, nil
}
```

#### NotifyBlockReady

`NotifyBlockReady` is a helper method that can send messages to the consensus engine through `toEngine` channel.

```go title="timestampvm/vm.go"
// NotifyBlockReady tells the consensus engine that a new block
// is ready to be created
func (vm *VM) NotifyBlockReady() {
	select {
	case vm.toEngine <- common.PendingTxs:
	default:
		vm.ctx.Log.Debug("dropping message to consensus engine")
	}
}
```

#### GetBlock

`GetBlock` returns the block with the given block ID.

```go title="timestampvm/vm.go"
// GetBlock implements the snowman.ChainVM interface
func (vm *VM) GetBlock(blkID ids.ID) (snowman.Block, error) { return vm.getBlock(blkID) }

func (vm *VM) getBlock(blkID ids.ID) (*Block, error) {
	// If block is in memory, return it.
	if blk, exists := vm.verifiedBlocks[blkID]; exists {
		return blk, nil
	}

	return vm.state.GetBlock(blkID)
}
```

#### `proposeBlock`

This method adds a piece of data to the mempool and notifies the consensus layer of the blockchain that a new block is ready to be built and voted on. This is called by API method `ProposeBlock`, which we'll see later.

```go title="timestampvm/vm.go"
// proposeBlock appends [data] to [p.mempool].
// Then it notifies the consensus engine
// that a new block is ready to be added to consensus
// (namely, a block with data [data])
func (vm *VM) proposeBlock(data [dataLen]byte) {
    vm.mempool = append(vm.mempool, data)
    vm.NotifyBlockReady()
}
```

#### ParseBlock

Parse a block from its byte representation.

```go title="timestampvm/vm.go"
// ParseBlock parses [bytes] to a snowman.Block
// This function is used by the vm's state to unmarshal blocks saved in state
// and by the consensus layer when it receives the byte representation of a block
// from another node
func (vm *VM) ParseBlock(bytes []byte) (snowman.Block, error) {
	// A new empty block
	block := &Block{}

	// Unmarshal the byte repr. of the block into our empty block
	_, err := Codec.Unmarshal(bytes, block)
	if err != nil {
		return nil, err
	}

	// Initialize the block
	block.Initialize(bytes, choices.Processing, vm)

	if blk, err := vm.getBlock(block.ID()); err == nil {
		// If we have seen this block before, return it with the most up-to-date
		// info
		return blk, nil
	}

	// Return the block
	return block, nil
}
```

#### NewBlock

`NewBlock` creates a new block with given block parameters.

```go title="timestampvm/vm.go"
// NewBlock returns a new Block where:
// - the block's parent is [parentID]
// - the block's data is [data]
// - the block's timestamp is [timestamp]
func (vm *VM) NewBlock(parentID ids.ID, height uint64, data [dataLen]byte, timestamp time.Time) (*Block, error) {
	block := &Block{
		PrntID: parentID,
		Hght:   height,
		Tmstmp: timestamp.Unix(),
		Dt:     data,
	}

	// Get the byte representation of the block
	blockBytes, err := Codec.Marshal(CodecVersion, block)
	if err != nil {
		return nil, err
	}

	// Initialize the block by providing it with its byte representation
	// and a reference to this VM
	block.Initialize(blockBytes, choices.Processing, vm)
	return block, nil
}
```

#### SetPreference

`SetPreference` implements the `block.ChainVM`. It sets the preferred block ID.

```go title="timestampvm/vm.go"
// SetPreference sets the block with ID [ID] as the preferred block
func (vm *VM) SetPreference(id ids.ID) error {
	vm.preferred = id
	return nil
}
```

#### Other Functions

These functions needs to be implemented for `block.ChainVM`. Most of them are just blank functions returning `nil`.

```go title="timestampvm/vm.go"
// Bootstrapped marks this VM as bootstrapped
func (vm *VM) Bootstrapped() error { return nil }

// Bootstrapping marks this VM as bootstrapping
func (vm *VM) Bootstrapping() error { return nil }

// Returns this VM's version
func (vm *VM) Version() (string, error) {
	return Version.String(), nil
}

func (vm *VM) Connected(id ids.ShortID, nodeVersion version.Application) error {
	return nil // noop
}

func (vm *VM) Disconnected(id ids.ShortID) error {
	return nil // noop
}

// This VM doesn't (currently) have any app-specific messages
func (vm *VM) AppGossip(nodeID ids.ShortID, msg []byte) error {
	return nil
}

// This VM doesn't (currently) have any app-specific messages
func (vm *VM) AppRequest(nodeID ids.ShortID, requestID uint32, time time.Time, request []byte) error {
	return nil
}

// This VM doesn't (currently) have any app-specific messages
func (vm *VM) AppResponse(nodeID ids.ShortID, requestID uint32, response []byte) error {
	return nil
}

// This VM doesn't (currently) have any app-specific messages
func (vm *VM) AppRequestFailed(nodeID ids.ShortID, requestID uint32) error {
	return nil
}

// Health implements the common.VM interface
func (vm *VM) HealthCheck() (interface{}, error) { return nil, nil }
```

### Factory

VMs should implement the `Factory` interface. `New` method in the interface returns a new VM instance.

```go title="timestampvm/factory.go"
var _ vms.Factory = &Factory{}

// Factory ...
type Factory struct{}

// New ...
func (f *Factory) New(*snow.Context) (interface{}, error) { return &VM{}, nil }
```

### Static API

A VM may have a static API, which allows clients to call methods that do not query or update the state of a particular blockchain, but rather apply to the VM as a whole. This is analogous to static methods in computer programming. AvalancheGo uses [Gorilla's RPC library](https://www.gorillatoolkit.org/pkg/rpc) to implement HTTP APIs. `StaticService` implements the static API for our VM.

```go title="timestampvm/static_service.go"
// StaticService defines the static API for the timestamp vm
type StaticService struct{}
```

#### Encode

For each API method, there is:

- A struct that defines the method's arguments
- A struct that defines the method's return values
- A method that implements the API method, and is parameterized on the above 2 structs

This API method encodes a string to its byte representation using a given encoding scheme. It can be used to encode data that is then put in a block and proposed as the next block for this chain.

```go title="timestampvm/static_service.go"
// EncodeArgs are arguments for Encode
type EncodeArgs struct {
    Data     string              `json:"data"`
    Encoding formatting.Encoding `json:"encoding"`
    Length   int32               `json:"length"`
}

// EncodeReply is the reply from Encoder
type EncodeReply struct {
    Bytes    string              `json:"bytes"`
    Encoding formatting.Encoding `json:"encoding"`
}

// Encoder returns the encoded data
func (ss *StaticService) Encode(_ *http.Request, args *EncodeArgs, reply *EncodeReply) error {
    if len(args.Data) == 0 {
        return fmt.Errorf("argument Data cannot be empty")
    }
    var argBytes []byte
    if args.Length > 0 {
        argBytes = make([]byte, args.Length)
        copy(argBytes, args.Data)
    } else {
        argBytes = []byte(args.Data)
    }

    bytes, err := formatting.EncodeWithChecksum(args.Encoding, argBytes)
    if err != nil {
        return fmt.Errorf("couldn't encode data as string: %s", err)
    }
    reply.Bytes = bytes
    reply.Encoding = args.Encoding
    return nil
}
```

#### Decode

This API method is the inverse of `Encode`.

```go title="timestampvm/static_service.go"
// DecoderArgs are arguments for Decode
type DecoderArgs struct {
    Bytes    string              `json:"bytes"`
    Encoding formatting.Encoding `json:"encoding"`
}

// DecoderReply is the reply from Decoder
type DecoderReply struct {
    Data     string              `json:"data"`
    Encoding formatting.Encoding `json:"encoding"`
}

// Decoder returns the Decoded data
func (ss *StaticService) Decode(_ *http.Request, args *DecoderArgs, reply *DecoderReply) error {
    bytes, err := formatting.Decode(args.Encoding, args.Bytes)
    if err != nil {
        return fmt.Errorf("couldn't Decode data as string: %s", err)
    }
    reply.Data = string(bytes)
    reply.Encoding = args.Encoding
    return nil
}
```

### API

A VM may also have a non-static HTTP API, which allows clients to query and update the blockchain's state. `Service`'s declaration is:

```go title="timestampvm/service.go"
// Service is the API service for this VM
type Service struct{ vm *VM }
```

Note that this struct has a reference to the VM, so it can query and update state.

This VM's API has two methods. One allows a client to get a block by its ID. The other allows a client to propose the next block of this blockchain. The blockchain ID in the endpoint changes, since every blockchain has an unique ID.

#### `timestampvm.getBlock`

Get a block by its ID. If no ID is provided, get the latest block.

##### `getBlock` Signature

```
timestampvm.getBlock({id: string}) ->
    {
        id: string,
        data: string,
        timestamp: int,
        parentID: string
    }
```

- `id` is the ID of the block being retrieved. If omitted from arguments, gets the latest block
- `data` is the base 58 (with checksum) representation of the block's 32 byte payload
- `timestamp` is the Unix timestamp when this block was created
- `parentID` is the block's parent

##### `getBlock` Example Call

```bash
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "timestampvm.getBlock",
    "params":{
        "id":"xqQV1jDnCXDxhfnNT7tDBcXeoH2jC3Hh7Pyv4GXE1z1hfup5K"
    },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/sw813hGSWH8pdU9uzaYy9fCtYFfY7AjDd2c9rm64SbApnvjmk
```

##### `getBlock` Example Response

```json
{
  "jsonrpc": "2.0",
  "result": {
    "timestamp": "1581717416",
    "data": "11111111111111111111111111111111LpoYY",
    "id": "xqQV1jDnCXDxhfnNT7tDBcXeoH2jC3Hh7Pyv4GXE1z1hfup5K",
    "parentID": "22XLgiM5dfCwTY9iZnVk8ZPuPe3aSrdVr5Dfrbxd3ejpJd7oef"
  },
  "id": 1
}
```

##### `getBlock` Implementation

```go title="timestampvm/service.go"
// GetBlockArgs are the arguments to GetBlock
type GetBlockArgs struct {
	// ID of the block we're getting.
	// If left blank, gets the latest block
	ID *ids.ID `json:"id"`
}

// GetBlockReply is the reply from GetBlock
type GetBlockReply struct {
	Timestamp json.Uint64 `json:"timestamp"` // Timestamp of most recent block
	Data      string      `json:"data"`      // Data in the most recent block. Base 58 repr. of 5 bytes.
	ID        ids.ID      `json:"id"`        // String repr. of ID of the most recent block
	ParentID  ids.ID      `json:"parentID"`  // String repr. of ID of the most recent block's parent
}

// GetBlock gets the block whose ID is [args.ID]
// If [args.ID] is empty, get the latest block
func (s *Service) GetBlock(_ *http.Request, args *GetBlockArgs, reply *GetBlockReply) error {
	// If an ID is given, parse its string representation to an ids.ID
	// If no ID is given, ID becomes the ID of last accepted block
	var (
		id  ids.ID
		err error
	)

	if args.ID == nil {
		id, err = s.vm.state.GetLastAccepted()
		if err != nil {
			return errCannotGetLastAccepted
		}
	} else {
		id = *args.ID
	}

	// Get the block from the database
	block, err := s.vm.getBlock(id)
	if err != nil {
		return errNoSuchBlock
	}

	// Fill out the response with the block's data
	reply.ID = block.ID()
	reply.Timestamp = json.Uint64(block.Timestamp().Unix())
	reply.ParentID = block.Parent()
	data := block.Data()
	reply.Data, err = formatting.EncodeWithChecksum(formatting.CB58, data[:])

	return err
}
```

#### `timestampvm.proposeBlock`

Propose the next block on this blockchain.

##### `proposeBlock` Signature

```go
timestampvm.proposeBlock({data: string}) -> {success: bool}
```

- `data` is the base 58 (with checksum) representation of the proposed block's 32 byte payload.

##### `proposeBlock` Example Call

```bash
curl -X POST --data '{
    "jsonrpc": "2.0",
    "method": "timestampvm.proposeBlock",
    "params":{
        "data":"SkB92YpWm4Q2iPnLGCuDPZPgUQMxajqQQuz91oi3xD984f8r"
    },
    "id": 1
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/sw813hGSWH8pdU9uzaYy9fCtYFfY7AjDd2c9rm64SbApnvjmk
```

###### `proposeBlock` Example Response

```json
{
  "jsonrpc": "2.0",
  "result": {
    "Success": true
  },
  "id": 1
}
```

##### `proposeBlock` Implementation

```go title="timestampvm/service.go"
// ProposeBlockArgs are the arguments to ProposeValue
type ProposeBlockArgs struct {
    // Data for the new block. Must be base 58 encoding (with checksum) of 32 bytes.
    Data string
}

// ProposeBlockReply is the reply from function ProposeBlock
type ProposeBlockReply struct{
    // True if the operation was successful
    Success bool
}

// ProposeBlock is an API method to propose a new block whose data is [args].Data.
// [args].Data must be a string repr. of a 32 byte array
func (s *Service) ProposeBlock(_ *http.Request, args *ProposeBlockArgs, reply *ProposeBlockReply) error {
	bytes, err := formatting.Decode(formatting.CB58, args.Data)
	if err != nil || len(bytes) != dataLen {
		return errBadData
	}

	var data [dataLen]byte         // The data as an array of bytes
	copy(data[:], bytes[:dataLen]) // Copy the bytes in dataSlice to data

	s.vm.proposeBlock(data)
	reply.Success = true
	return nil
}
```

### Plugin

In order to make this VM compatible with `go-plugin`, we need to define a `main` package and method, which serves our VM over gRPC so that AvalancheGo can call its methods. `main.go`'s contents are:

```go title="main/main.go"
func main() {
    log.Root().SetHandler(log.LvlFilterHandler(log.LvlDebug, log.StreamHandler(os.Stderr, log.TerminalFormat())))
    plugin.Serve(&plugin.ServeConfig{
        HandshakeConfig: rpcchainvm.Handshake,
        Plugins: map[string]plugin.Plugin{
            "vm": rpcchainvm.New(&timestampvm.VM{}),
        },

        // A non-nil value here enables gRPC serving for this plugin...
        GRPCServer: plugin.DefaultGRPCServer,
    })
}
```

Now AvalancheGo's `rpcchainvm` can connect to this plugin and calls its methods.

### Executable Binary

This VM has a [build script](https://github.com/ava-labs/timestampvm/blob/v1.2.1/scripts/build.sh) that builds an executable of this VM (when invoked, it runs the `main` method from above.)

The path to the executable, as well as its name, can be provided to the build script via arguments. For example:

```bash
./scripts/build.sh ../avalanchego/build/plugins timestampvm
```

If no argument is given, the path defaults to a binary named with default VM ID: `$GOPATH/src/github.com/ava-labs/avalanchego/build/plugins/tGas3T58KzdjLHhBDMnH2TvrddhqTji5iZAMZ3RXs2NLpSnhH`

This name `tGas3T58KzdjLHhBDMnH2TvrddhqTji5iZAMZ3RXs2NLpSnhH` is the CB58 encoded 32 byte identifier for the VM. For the timestampvm, this is the string "timestamp" zero-extended in a 32 byte array and encoded in CB58.

### VM Aliases

Each VM has a predefined, static ID. For instance, the default ID of the TimestampVM is: `tGas3T58KzdjLHhBDMnH2TvrddhqTji5iZAMZ3RXs2NLpSnhH`.

It's possible to give an alias for these IDs. For example, we can alias `TimestampVM` by creating a JSON file at `~/.avalanchego/configs/vms/aliases.json` with:

<Callout type="warn">
The name of the VM binary is also its static ID and should not be changed manually. Changing the name of the VM binary will result in AvalancheGo failing to start the VM. To reference a VM by another name, define a VM alias as described below.
</Callout>

```json
{
  "tGas3T58KzdjLHhBDMnH2TvrddhqTji5iZAMZ3RXs2NLpSnhH": [
    "timestampvm",
    "timestamp"
  ]
}
```

### Installing a VM

AvalancheGo searches for and registers plugins under the `plugins` [directory](/docs/nodes/configure/configs-flags#--plugin-dir-string).

To install the virtual machine onto your node, you need to move the built virtual machine binary under this directory. Virtual machine executable names must be either a full virtual machine ID (encoded in CB58), or a VM alias.

Copy the binary into the plugins directory.

```bash
cp -n <path to your binary> $GOPATH/src/github.com/ava-labs/avalanchego/build/plugins/
```

#### Node Is Not Running

If your node isn't running yet, you can install all virtual machines under your `plugin` directory by starting the node.

#### Node Is Already Running

Load the binary with the `loadVMs` API.

```bash
curl -sX POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin.loadVMs",
    "params" :{}
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/admin
```

Confirm the response of `loadVMs` contains the newly installed virtual machine `tGas3T58KzdjLHhBDMnH2TvrddhqTji5iZAMZ3RXs2NLpSnhH`. You'll see this virtual machine as well as any others that weren't already installed previously in the response.

```json
{
  "jsonrpc": "2.0",
  "result": {
    "newVMs": {
      "tGas3T58KzdjLHhBDMnH2TvrddhqTji5iZAMZ3RXs2NLpSnhH": [
        "timestampvm",
        "timestamp"
      ],
      "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ": []
    }
  },
  "id": 1
}
```

Now, this VM's static API can be accessed at endpoints `/ext/vm/timestampvm` and `/ext/vm/timestamp`. For more details about VM configs, see [here](/docs/nodes/configure/configs-flags#virtual-machine-vm-configs).

In this tutorial, we used the VM's ID as the executable name to simplify the process. However, AvalancheGo would also accept `timestampvm` or `timestamp` since those are registered aliases in previous step.

## Wrapping Up

That's it! That's the entire implementation of a VM which defines a blockchain-based timestamp server.

In this tutorial, we learned:

- The `block.ChainVM` interface, which all VMs that define a linear chain must implement
- The `snowman.Block` interface, which all blocks that are part of a linear chain must implement
- The `rpcchainvm` type, which allows blockchains to run in their own processes.
- An actual implementation of `block.ChainVM` and `snowman.Block`.

# Installing Your VM (/docs/virtual-machines/rust-vms/installing-vm)

---
title: Installing Your VM
description: Learn how to install your VM on your node.
---

AvalancheGo searches for and registers VM plugins under the `plugins` [directory](/docs/nodes/configure/configs-flags#--plugin-dir-string).

To install the virtual machine onto your node, you need to move the built virtual machine binary under this directory. Virtual machine executable names must be either a full virtual machine ID (encoded in CB58), or a VM alias.

Copy the binary into the plugins directory.

```bash
cp -n <path to your binary> $GOPATH/src/github.com/ava-labs/avalanchego/build/plugins/
```

## Node Is Not Running

If your node isn't running yet, you can install all virtual machines under your `plugin` directory by starting the node.

## Node Is Already Running

Load the binary with the `loadVMs` API.

```bash
curl -sX POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"admin.loadVMs",
    "params" :{}
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/admin
```

Confirm the response of `loadVMs` contains the newly installed virtual machine `tGas3T58KzdjcJ32c6GpePhtqo9rrHJ1oR9wFBtCcMgaosthX`. You'll see this virtual machine as well as any others that weren't already installed previously in the response.

```json
{
  "jsonrpc": "2.0",
  "result": {
    "newVMs": {
      "tGas3T58KzdjcJ32c6GpePhtqo9rrHJ1oR9wFBtCcMgaosthX": [
        "timestampvm-rs",
        "timestamp-rs"
      ],
      "spdxUxVJQbX85MGxMHbKw1sHxMnSqJ3QBzDyDYEP3h6TLuxqQ": []
    }
  },
  "id": 1
}
```

Now, this VM's static API can be accessed at endpoints `/ext/vm/timestampvm-rs` and `/ext/vm/timestamp-rs`. For more details about VM configs, see [here](/docs/nodes/configure/configs-flags#virtual-machine-vm-configs).

In this tutorial, we used the VM's ID as the executable name to simplify the process. However, AvalancheGo would also accept `timestampvm-rs` or `timestamp-rs` since those are registered aliases in previous step.

# Introduction to Avalanche-RS (/docs/virtual-machines/rust-vms/intro-avalanche-rs)

---
title: Introduction to Avalanche-RS
description: Learn how to write a simple virtual machine in Rust using Avalanche-RS.
---

Since Rust is a language which we can write and implement Proto interfaces, this implies that we can also use Rust to write VMs which can then be deployed on Avalanche.

However, rather than build Rust-based from the ground-up, we can utilize Avalanche-RS, a developer toolkit comprised of powerful building blocks and primitive types which allow us to focus exclusively on the business logic of our VM rather than working on low-level logic.

## Structure of Avalanche-RS

Although Avalanche-RS is currently primarily used to build Rust-based VMs, Avalanche-RS actually consists of three different frameworks; as per the [GitHub](https://github.com/ava-labs/avalanche-rs) description of the Avalanche-RS repository, the three frameworks are as follows:

- Core: framework for core networking components for a P2P Avalanche node
- Avalanche-Consensus: a Rust implementation of the novel Avalanche consensus protocol
- Avalanche-Types: implements foundational types used in Avalanche and provides an SDK for building Rust-based VMs

As the above might make it obvious, the Avalanche-Types crate is the main framework that one would use to build Rust-based VMs.

## Documentation

For the most up-to-date information regarding the Avalache-Types library, please refer to the associated [crates.io](https://crates.io/crates/avalanche-types) page for the Avalanche-Types crate.

# Setting Up Your Environment (/docs/virtual-machines/rust-vms/setting-up-environment)

---
title: Setting Up Your Environment
description: Learn how to set up your environment to build a Rust VM.
---

In this section, we will focus on getting set up with the Rust environment necessary to build with the `avalanche-types` crates (recall that `avalanche-types` contains the SDK we want to use to build our Rust VM).

## Installing Rust

First and foremost, we will need to have Rust installed locally. If you do not have Rust installed, you can install `rustup` (the tool that manages your Rust installation) [here](https://www.rust-lang.org/tools/install).

## Adding `avalanche-types` to Your Project

Once you have Rust installed and are ready to build, you will want to add the Avalanche-Types crate to your project. Below is a baseline example of how you can do this:

```toml title="Cargo.toml"
[dependencies]
avalanche-types = "0.1.4"
```

However, if you want to use the [TimestampVM](https://github.com/ava-labs/timestampvm-rs) as a reference for your project, a more appropriate import would be the following:

```toml title="Cargo.toml"
[dependencies]
avalanche-types = { version = "0.1.4", features = ["subnet", "codec_base64"] } 
```


# APIs (/docs/virtual-machines/timestamp-vm/apis)

---
title: APIs
description: Learn how to interact with TimestampVM.
---

Throughout this case study, we have been focusing of the functionality of the TimestampVM. However, one thing we haven't discussed is how external users can interact with an instance of TimestampVM.

Without a way for users to interact with TimestampVM, the blockchain itself will be stagnant. In this section, we will go over the two types of APIs used in TimestampVM:

- Static APIs
- Chain APIs

## Precursor: Static and Instance Methods

When understanding the static and chain APIs used in TimestampVM, a good way to think about these APIs is to compare them to static and instance methods in object-oriented programming. That is,

- **Static Methods**: functions which belong to the class itself, and not any instance of the class
- **Instance Methods**: functions which belong to the instance of a class

## Static APIs

We can think of the static APIs in TimestampVM as functions which call the VM and are not associated with any specific instance of the TimestampVM. Within TimestampVM, we have just one static API function - the ping function:

```rust title="timestampvm/src/api/static_handlers.rs"
/// Defines static handler RPCs for this VM.
#[rpc]
pub trait Rpc {
    #[rpc(name = "ping", alias("timestampvm.ping"))]
    fn ping(&self) -> BoxFuture<Result<crate::api::PingResponse>>;
}
```

## Chain APIs

In contrast to the static API, the chain API of TimestampVM is much more rich in the sense that we have functions with read from and write to an instance of TimestampVM. In this case, we have four functions defined in the chain API:

- `ping`: when called, this function pings an instance of TimestampVM
- `propose_Block`: write function which passes a block to TimestampVM for consideration to be appended to 	the blockchain
- `last_accepted`: read function which returns 	the last accepted block (that is, 	the block at 	the tip	of 	the blockchain)
- `get_block`: read	function	which fetches		the requested	block	

We can see 	the functions included in the chain API here:

```rust title="timestampvm/src/api/chain_handlers.rs"
/// Defines RPCs specific to the chain.
#[rpc]
pub	trait	Rpc {
    /// Pings		th	e VM.
    #[rpc(name = "ping", alias("timestampvm.ping"))]
	fn	ping(&self) -> BoxFuture<Result<PingResponse>>;

    /// Proposes th	e arbitrary data.
    #[rpc(name = "proposeBlock", alias("timestampvm.proposeBlock"))]
	fn	propose_block(&self,args:ProposeBlockArgs)->BoxFuture<Result<ProposeBlockResponse>>;

   /// Fetches th	e last accepted	block.
   #[rpc(name="lastAccepted",alias("timestampvm.lastAccepted"))] 
   fn	last_accepted(&self)->BoxFuture<Result<LastAcceptedResponse>>;

   /// Fetches th	e block.
   #[rpc(name="getBlock",alias("timestampvm.getBlock"))] 
   fn	get_block(&self,args:GetBlockArgs)->BoxFutur e <Result<GetBl ock Response>>;
}
```

# Blocks (/docs/virtual-machines/timestamp-vm/blocks)

---
title: Blocks
descscription: Learn about the Block data structure in TimestampVM.
---

In this section, we will examine the Block data structure. In contrast to the design choice of the TimestampVM state (which was mostly in control of the implementers), blocks in TimestampVM must adhere to the SnowmanVM Block Interface.

## SnowmanVM.Block Interface

TimestampVM is designed to be used in tandem with the Snowman Consensus Engine. In particular, this relationship is defined by the usage of blocks - TimestampVM will produce blocks which the Snowman Consensus Engine will use and eventually mark as accepted or rejected. Therefore, the Snowman Consensus Engine requires for all blocks to have the following interface:

```go
type Block interface {
	choices.Decidable

	// Parent returns the ID of this block's parent.
	Parent() ids.ID

	// Verify that the state transition this block would make if accepted is
	// valid. If the state transition is invalid, a non-nil error should be
	// returned.
	//
	// It is guaranteed that the Parent has been successfully verified.
	//
	// If nil is returned, it is guaranteed that either Accept or Reject will be
	// called on this block, unless the VM is shut down.
	Verify(context.Context) error

	// Bytes returns the binary representation of this block.
	//
	// This is used for sending blocks to peers. The bytes should be able to be
	// parsed into the same block on another node.
	Bytes() []byte

	// Height returns the height of this block in the chain.
	Height() uint64

	// Time this block was proposed at. This value should be consistent across
	// all nodes. If this block hasn't been successfully verified, any value can
	// be returned. If this block is the last accepted block, the timestamp must
	// be returned correctly. Otherwise, accepted blocks can return any value.
	Timestamp() time.Time
}
```

## Implementing the Block Data Structure

With the above in mind, we now examine the block data structure:

```rust
/// Represents a block, specific to `Vm` (crate::vm::Vm).
#[serde_as]
#[derive(Serialize, Deserialize, Clone, Derivative, Default)]
#[derivative(Debug, PartialEq, Eq)]
pub struct Block {
    /// The block Id of the parent block.
    parent_id: ids::Id,
    /// This block's height.
    /// The height of the genesis block is 0.
    height: u64,
    /// Unix second when this block was proposed.
    timestamp: u64,
    /// Arbitrary data.
    #[serde_as(as = "Hex0xBytes")]
    data: Vec<u8>,

    /// Current block status.
    #[serde(skip)]
    status: choices::status::Status,
    /// This block's encoded bytes.
    #[serde(skip)]
    bytes: Vec<u8>,
    /// Generated block Id.
    #[serde(skip)]
    id: ids::Id,

    /// Reference to the Vm state manager for blocks.
    #[derivative(Debug = "ignore", PartialEq = "ignore")]
    #[serde(skip)]
    state: state::State,
}
```

Notice above that many of the fields of the `Block` struct store the information required to implement the `Snowman.Block` interface we saw previously. Tying the concept of Blocks back to the VM State, notice the last field `state` within the `Block` struct. This is where the `Block` struct stores a copy of the `State` struct from the previous section (and since each field of the `State` struct is wrapped in an `Arc` pointer, this implies that `Block` is really just storing a reference to both the `db` and `verified_blocks` data structures).

## `Block` Functions

In this section, we examine some of the functions associated with the `Block` struct:

### `verify`

This function verifies that a block is valid and stores it in memory. Note that a verified block does not mean that it has been accepted - rather, a verified block is eligible to be accepted.

```rust
/// Verifies [`Block`](Block) properties (e.g., heights),
/// and once verified, records it to the `State` (crate::state::State).
/// # Errors
/// Can fail if the parent block can't be retrieved.
pub async fn verify(&mut self) -> io::Result<()> {
    if self.height == 0 && self.parent_id == ids::Id::empty() {
        log::debug!(
            "block {} has an empty parent Id since it's a genesis block -- skipping verify",
            self.id
        );
        self.state.add_verified(&self.clone()).await;
        return Ok(());
    }

    // if already exists in database, it means it's already accepted
    // thus no need to verify once more
    if self.state.get_block(&self.id).await.is_ok() {
        log::debug!("block {} already verified", self.id);
        return Ok(());
    }

    let prnt_blk = self.state.get_block(&self.parent_id).await?;

    // ensure the height of the block is immediately following its parent
    if prnt_blk.height != self.height - 1 {
        return Err(Error::new(
            ErrorKind::InvalidData,
            format!(
                "parent block height {} != current block height {} - 1",
                prnt_blk.height, self.height
            ),
        ));
    }

    // ensure block timestamp is after its parent
    if prnt_blk.timestamp > self.timestamp {
        return Err(Error::new(
            ErrorKind::InvalidData,
            format!(
                "parent block timestamp {} > current block timestamp {}",
                prnt_blk.timestamp, self.timestamp
            ),
        ));
    }

    let one_hour_from_now = Utc::now() + Duration::hours(1);
    let one_hour_from_now = one_hour_from_now
        .timestamp()
        .try_into()
        .expect("failed to convert timestamp from i64 to u64");

    // ensure block timestamp is no more than an hour ahead of this nodes time
    if self.timestamp >= one_hour_from_now {
        return Err(Error::new(
            ErrorKind::InvalidData,
            format!(
                "block timestamp {} is more than 1 hour ahead of local time",
                self.timestamp
            ),
        ));
    }

    // add newly verified block to memory
    self.state.add_verified(&self.clone()).await;
    Ok(())
}
```

### `reject`

When called by the Snowman Consensus Engine, this tells the VM that the particular block has been rejected.

```rust
/// Mark this [`Block`](Block) rejected and updates `State` (crate::state::State) accordingly.
/// # Errors
/// Returns an error if the state can't be updated.
pub async fn reject(&mut self) -> io::Result<()> {
    self.set_status(choices::status::Status::Rejected);

    // only decided blocks are persistent -- no reorg
    self.state.write_block(&self.clone()).await?;

    self.state.remove_verified(&self.id()).await;
    Ok(())
}
```

### `accept`

When called by the Snowman Consensus Engine, this tells the VM that the particular block has been rejected.

```rust
/// Mark this [`Block`](Block) accepted and updates `State` (crate::state::State) accordingly.
/// # Errors
/// Returns an error if the state can't be updated.
pub async fn accept(&mut self) -> io::Result<()> {
    self.set_status(choices::status::Status::Accepted);

    // only decided blocks are persistent -- no reorg
    self.state.write_block(&self.clone()).await?;
    self.state.set_last_accepted_block(&self.id()).await?;

    self.state.remove_verified(&self.id()).await;
    Ok(())
}
```


# Architecture of TimestampVM (/docs/virtual-machines/timestamp-vm/defining-vm-itself)

---
title: Architecture of TimestampVM
description: After examining several of the data structures and functionalities that TimestampVM relies on, it is time that we examine the architecture of the TimestampVM itself. In addition, we will look at some data structures that TimestampVM utilizes.
---

## Aside: SnowmanVM

In addition to blocks having to adhere to the `Snowman.Block` interface, VMs which interact with the Snowman Consensus Engine must also implement the `SnowmanVM` interface. In the context of a Rust-based VM, this means that we must satisfy the `ChainVM` trait in `avalanche-types`:

```rust title="avalanche-types/src/subnet/rpc/snowman/block.rs"
/// ref. <https://pkg.go.dev/github.com/ava-labs/avalanchego/snow/engine/snowman/block#ChainVm>
#[tonic::async_trait]
pub trait ChainVm: CommonVm + BatchedChainVm + Getter + Parser {
    type Block: snowman::Block;

    /// Attempt to create a new block from ChainVm data
    /// Returns either a block or an error
    async fn build_block(&self) -> Result<<Self as ChainVm>::Block>;

    /// Issues a transaction to the chain
    async fn issue_tx(&self) -> Result<<Self as ChainVm>::Block>;

    /// Notify the Vm of the currently preferred block.
    async fn set_preference(&self, id: Id) -> Result<()>;

    /// Returns ID of last accepted block.
    async fn last_accepted(&self) -> Result<Id>;

}
```

## Defining TimestampVM

Below is definition of VM struct which represents TimestampVM:

```rust title="timestampvm/src/vm/mod.rs"
pub struct Vm<A> {
   /// Maintains Vm-specific states.
   pub state: Arc<RwLock<State>>,

   pub app_sender: Option<A>,

   /// A queue not yet proposed into a block.
   pub mempool: Arc<RwLock<VecDeque<Vec<u8>>>>,
}
```

We see following three fields:

- `state`: represents state of VM. Note different than earlier seen State structure.
- `app_sender`: channel for receiving and sending requests by our VM
- `mempool`: where proposed blocks are kept before being processed.

We now examine the `state` data structure mentioned earlier:

```rust title="timestampvm/src/vm/mod.rs"
/// Represents VM-specific states.
/// Defined separately for interior mutability in [`Vm`](vm).
/// Protected with 'Arc' and 'RwLock'.
pub struct State {
  pub ctx : Option<Context<ValidatorStateClient>>,
  pub version : Version,
  pub genesis : Genesis,

  // Persistent Vm state representation 
  pub state : Option<state::State>,
  
  // Preferred block Id 
  pub preferred : ids::Id,
  
  // Channel for messages to snowman consensus engine 
  pub bootstrapped : bool,
}
```

Relationship between State and state - contains alongside other fields relevant to Snowman consensus algorithm.

# Introduction (/docs/virtual-machines/timestamp-vm/introduction)

---
title: Introduction
description: Learn about the TimestampVM Virtual Machine.
---

To really get an understanding of how one can use the `avalanche-types` library to build a Rust-based VM, we will look at [TimeStampVM](https://github.com/ava-labs/timestampvm-rs/tree/main), a basic VM which utilizes the `avalanche-types` library.

## Idea of TimestampVM

In contrast to complex VMs like the EVM which provide a general-purpose computing environment, TimestampVM is _much, much_ simpler. In fact, we can describe the goal of TimestampVM in two bullet points:

- To store the timestamp when each block was appended to the blockchain
- To store arbitrary payloads of data (within each block)

Even though the above seems quite simple, this still requires us to define and build out an architecture to support such functionalities. In this case study, we will look at the following pieces of the architecture that define TimestampVM:

- State
- Blocks
- API
- The VM itself

# State (/docs/virtual-machines/timestamp-vm/state)

---
title: State
description: Learn about the state within the context of TimestampVM.
---

Blockchains can be defined as follows:

> A linked-list where each list element consists of a block

Implementations of blockchains, while adhering to the functionality above from a white-box perspective, are defined much more like databases than regular linked lists themselves. In fact, this is what TimestampVM utilizes! By utilizing a general database, TimestampVM is able to store blocks (and thus, store its blockchain) while also being able to store additional data such as pending blocks.

## State Definition

Below is the definition of the `State` struct which is used to maintain the state of the TimestampVM:

```rust
/// Manages block and chain states for this Vm, both in-memory and persistent.
#[derive(Clone)]
pub struct State {
    pub db: Arc<RwLock<Box<dyn subnet::rpc::database::Database + Send + Sync>>>,

    /// Maps block Id to Block.
    /// Each element is verified but not yet accepted/rejected (e.g., preferred).
    pub verified_blocks: Arc<RwLock<HashMap<ids::Id, Block>>>,
}
```

`State` in this context acts like the database of TimestampVM. Within `State`, we are managing two different data structures:

- `db`: a byte-based mapping which maps bytes to bytes. This is where finalized (that is, accepted blocks are stored)
- `verified_blocks`: a hashmap which maps block numbers to their respective blocks. This is where all verified, but pending blocks are stored

While one could have guessed the functionalities of `db` and `verified_blocks` from their respective types `subnet::rpc::database::Database + Send + Sync` and `HashMap<ids::Id, Block>`, it is not immediately clear why we are wrapping these fields with Read/Write locks and Arc pointers. However, as we'll see soon when we examine the Block data structure, blocks need access to the VM state so they can add themselves to state. This is due to the `SetPrefernce` function of SnowmanVM interface, which states:

> `Set Preference`
> 
> The VM implements the function SetPreference(blkID ids.ID) to allow the consensus engine to notify the VM which block is currently preferred to be accepted. The VM should use this information to set the head of its blockchain. Most importantly, when the consensus engine calls BuildBlock, the VM should be sure to build on top of the block that is the most recently set preference.
> 
> Note: SetPreference will always be called with a block that has no verified children.

Therefore, when building a Rust-based VM (or a VM in any supported language), the VM itself is only responsible for tracking the ID of the most recent finalized block; blocks bear the responsibility of storing themselves in VM state. As a result, we will need to wrap the `db` and `verified_blocks` fields with the following:

- An `Arc` pointer so that whenever we clone the `State` structure, the cloned versions of `db` and `verified_blocks` are still pointing to the same data structures in memory. This allows for multiple Blocks to share the same `db` and `verified_blocks`
- A read/write lock (that is, `RwLock`) so that we safely utilize concurrency in our VM

## `State` Functions

Below are the functions associated with the `State` struct:

```rust title="timestampvm/src/state/mod.rs"
impl State {
    /// Persists the last accepted block Id to state.
    /// # Errors
    /// Fails if the db can't be updated
    pub async fn set_last_accepted_block(&self, blk_id: &ids::Id) -> io::Result<()> {
        let mut db = self.db.write().await;
        db.put(LAST_ACCEPTED_BLOCK_KEY, &blk_id.to_vec())
            .await
            .map_err(|e| {
                Error::new(
                    ErrorKind::Other,
                    format!("failed to put last accepted block: {e:?}"),
                )
            })
    }

    /// Returns "true" if there's a last accepted block found.
    /// # Errors
    /// Fails if the db can't be read
    pub async fn has_last_accepted_block(&self) -> io::Result<bool> {
        let db = self.db.read().await;
        match db.has(LAST_ACCEPTED_BLOCK_KEY).await {
            Ok(found) => Ok(found),
            Err(e) => Err(Error::new(
                ErrorKind::Other,
                format!("failed to load last accepted block: {e}"),
            )),
        }
    }

    /// Returns the last accepted block Id from state.
    /// # Errors
    /// Can fail if the db can't be read
    pub async fn get_last_accepted_block_id(&self) -> io::Result<ids::Id> {
        let db = self.db.read().await;
        match db.get(LAST_ACCEPTED_BLOCK_KEY).await {
            Ok(d) => Ok(ids::Id::from_slice(&d)),
            Err(e) => {
                if subnet::rpc::errors::is_not_found(&e) {
                    return Ok(ids::Id::empty());
                }
                Err(e)
            }
        }
    }

    /// Adds a block to "`verified_blocks`".
    pub async fn add_verified(&mut self, block: &Block) {
        let blk_id = block.id();
        log::info!("verified added {blk_id}");

        let mut verified_blocks = self.verified_blocks.write().await;
        verified_blocks.insert(blk_id, block.clone());
    }

    /// Removes a block from "`verified_blocks`".
    pub async fn remove_verified(&mut self, blk_id: &ids::Id) {
        let mut verified_blocks = self.verified_blocks.write().await;
        verified_blocks.remove(blk_id);
    }

    /// Returns "true" if the block Id has been already verified.
    pub async fn has_verified(&self, blk_id: &ids::Id) -> bool {
        let verified_blocks = self.verified_blocks.read().await;
        verified_blocks.contains_key(blk_id)
    }

    /// Writes a block to the state storage.
    /// # Errors
    /// Can fail if the block fails to serialize or if the db can't be updated
    pub async fn write_block(&mut self, block: &Block) -> io::Result<()> {
        let blk_id = block.id();
        let blk_bytes = block.to_vec()?;

        let mut db = self.db.write().await;

        let blk_status = BlockWithStatus {
            block_bytes: blk_bytes,
            status: block.status(),
        };
        let blk_status_bytes = blk_status.encode()?;

        db.put(&block_with_status_key(&blk_id), &blk_status_bytes)
            .await
            .map_err(|e| Error::new(ErrorKind::Other, format!("failed to put block: {e:?}")))
    }

    /// Reads a block from the state storage using the `block_with_status_key`.
    /// # Errors
    /// Can fail if the block is not found in the state storage, or if the block fails to deserialize
    pub async fn get_block(&self, blk_id: &ids::Id) -> io::Result<Block> {
        // check if the block exists in memory as previously verified.
        let verified_blocks = self.verified_blocks.read().await;
        if let Some(b) = verified_blocks.get(blk_id) {
            return Ok(b.clone());
        }

        let db = self.db.read().await;

        let blk_status_bytes = db.get(&block_with_status_key(blk_id)).await?;
        let blk_status = BlockWithStatus::from_slice(blk_status_bytes)?;

        let mut blk = Block::from_slice(&blk_status.block_bytes)?;
        blk.set_status(blk_status.status);

        Ok(blk)
    }
}
```

The functions above are called will be called by both blocks and the VM itself.

# Get metrics for EVM chains (/docs/api-reference/metrics-api/chain-metrics/getEvmChainMetrics)

---
title: Get metrics for EVM chains
full: true
_openapi:
  method: GET
  route: /v2/chains/{chainId}/metrics/{metric}
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          EVM chain metrics are available for all Avalanche L1s on _Mainnet_ and
          _Fuji_ (testnet). You can request metrics by EVM chain ID. See the
          `/chains` endpoint for all supported chains.


          All metrics are updated several times every hour. Each metric data
          point has a `value` and `timestamp` (Unix timestamp in seconds). All
          metric values include data within the duration of the associated
          timestamp plus the requested `timeInterval`. All timestamps are fixed
          to the hour. When requesting a timeInterval of **day**, **week**, or
          **month**, the timestamp will be 0:00 UTC of the day, Monday of the
          week, or first day of the month, respectively. The latest data point
          in any response may change on each update.


          ### Metrics


          <ins>activeAddresses</ins>: The number of distinct addresses seen
          within the selected `timeInterval` starting at the timestamp.
          Addresses counted are those that appear in the “from” and “to” fields
          of a transaction or ERC20/ERC721/ERC1155 transfer log event.


          <ins>activeSenders</ins>: This metric follows the same structure as
          activeAddresses, but instead only counts addresses that appear in the
          “from” field of the respective transaction or transfer log event.


          <ins>cumulativeTxCount</ins>: The cumulative transaction count from
          genesis up until 24 hours after the timestamp. This aggregation can be
          considered a “rolling sum” of the transaction count metric (txCount).
          Only `timeInterval=day` supported.


          <ins>cumulativeAddresses</ins>: The cumulative count of unique
          addresses from genesis up until 24 hours after the timestamp.
          Addresses counted are those that appear in the “from” and “to” fields
          of a transaction or ERC20/ERC721/ERC1155 transfer log event. Only
          `timeInterval=day` supported.


          <ins>cumulativeContracts</ins>: The cumulative count of contracts
          created from genesis up until the timestamp.  Contracts are counted by
          looking for the CREATE, CREATE2, and CREATE3 call types in all
          transaction traces (aka internal transactions). Only
          `timeInterval=day` supported.


          <ins>cumulativeDeployers</ins>: The cumulative count of unique
          contract deployers from genesis up until 24 hours after the timestamp.
          Deployers counted are those that appear in the “from” field of
          transaction traces with the CREATE, CREATE2, and CREATE3 call types.
          Only `timeInterval=day` supported.


          <ins>contracts</ins>: The count of contracts created within the
          requested timeInterval starting at the timestamp. Contracts are
          counted by looking for the CREATE, CREATE2, and CREATE3 call types in
          all transaction traces (aka internal transactions). Only
          `timeInterval=day` supported.


          <ins>deployers</ins>: The count of unique deployers within the
          requested timeInterval starting at the timestamp. Deployers counted
          are those that appear in the “from” field of transaction traces with
          the CREATE, CREATE2, and CREATE3 call types. Only `timeInterval=day`
          supported.


          <ins>gasUsed</ins>: The amount of gas used by transactions within the
          requested timeInterval starting at the timestamp.


          <ins>txCount</ins>: The amount of transactions within the requested
          timeInterval starting at the timestamp.


          <ins>avgGps</ins>: The average Gas used Per Second (GPS) within the
          day beginning at the timestamp.  The average is calculated by taking
          the sum of gas used by all blocks within the day and dividing it by
          the time interval between the last block of the previous day and the
          last block of the day that begins at the timestamp.  Only
          `timeInterval=day` supported.


          <ins>maxGps</ins>: The max Gas used Per Second (GPS)  measured within
          the day beginning at the timestamp. Each GPS data point is calculated
          using the gas used in a single block divided by the time since the
          last block. Only `timeInterval=day` supported.


          <ins>avgTps</ins>: The average Transactions Per Second (TPS) within
          the day beginning at the timestamp. The average is calculated by
          taking the sum of transactions within the day and dividing it by the
          time interval between the last block of the previous day and the last
          block of the day that begins at the timestamp. Only `timeInterval=day`
          supported.


          <ins>maxTps</ins>: The max Transactions Per Second (TPS) measured
          within the day beginning at the timestamp. Each TPS data point is
          calculated by taking the number of transactions in a single block and
          dividing it by the time since the last block. Only `timeInterval=day`
          supported.


          <ins>avgGasPrice</ins>: The average gas price within the day beginning
          at the timestamp. The gas price used is the price reported in
          transaction receipts. Only `timeInterval=day` supported.


          <ins>maxGasPrice</ins>: The max gas price seen within the day
          beginning at the timestamp. The gas price used is the price reported
          in transaction receipts. Only `timeInterval=day` supported.


          <ins>feesPaid</ins>: The sum of transaction fees paid within the day
          beginning at the timestamp. The fee is calculated as the gas used
          multiplied by the gas price as reported in all transaction receipts.
          Only `timeInterval=day` supported.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

EVM chain metrics are available for all Avalanche L1s on _Mainnet_ and _Fuji_ (testnet). You can request metrics by EVM chain ID. See the `/chains` endpoint for all supported chains.

All metrics are updated several times every hour. Each metric data point has a `value` and `timestamp` (Unix timestamp in seconds). All metric values include data within the duration of the associated timestamp plus the requested `timeInterval`. All timestamps are fixed to the hour. When requesting a timeInterval of **day**, **week**, or **month**, the timestamp will be 0:00 UTC of the day, Monday of the week, or first day of the month, respectively. The latest data point in any response may change on each update.

### Metrics

<ins>activeAddresses</ins>: The number of distinct addresses seen within the selected `timeInterval` starting at the timestamp. Addresses counted are those that appear in the “from” and “to” fields of a transaction or ERC20/ERC721/ERC1155 transfer log event.

<ins>activeSenders</ins>: This metric follows the same structure as activeAddresses, but instead only counts addresses that appear in the “from” field of the respective transaction or transfer log event.

<ins>cumulativeTxCount</ins>: The cumulative transaction count from genesis up until 24 hours after the timestamp. This aggregation can be considered a “rolling sum” of the transaction count metric (txCount). Only `timeInterval=day` supported.

<ins>cumulativeAddresses</ins>: The cumulative count of unique addresses from genesis up until 24 hours after the timestamp. Addresses counted are those that appear in the “from” and “to” fields of a transaction or ERC20/ERC721/ERC1155 transfer log event. Only `timeInterval=day` supported.

<ins>cumulativeContracts</ins>: The cumulative count of contracts created from genesis up until the timestamp.  Contracts are counted by looking for the CREATE, CREATE2, and CREATE3 call types in all transaction traces (aka internal transactions). Only `timeInterval=day` supported.

<ins>cumulativeDeployers</ins>: The cumulative count of unique contract deployers from genesis up until 24 hours after the timestamp. Deployers counted are those that appear in the “from” field of transaction traces with the CREATE, CREATE2, and CREATE3 call types. Only `timeInterval=day` supported.

<ins>contracts</ins>: The count of contracts created within the requested timeInterval starting at the timestamp. Contracts are counted by looking for the CREATE, CREATE2, and CREATE3 call types in all transaction traces (aka internal transactions). Only `timeInterval=day` supported.

<ins>deployers</ins>: The count of unique deployers within the requested timeInterval starting at the timestamp. Deployers counted are those that appear in the “from” field of transaction traces with the CREATE, CREATE2, and CREATE3 call types. Only `timeInterval=day` supported.

<ins>gasUsed</ins>: The amount of gas used by transactions within the requested timeInterval starting at the timestamp.

<ins>txCount</ins>: The amount of transactions within the requested timeInterval starting at the timestamp.

<ins>avgGps</ins>: The average Gas used Per Second (GPS) within the day beginning at the timestamp.  The average is calculated by taking the sum of gas used by all blocks within the day and dividing it by the time interval between the last block of the previous day and the last block of the day that begins at the timestamp.  Only `timeInterval=day` supported.

<ins>maxGps</ins>: The max Gas used Per Second (GPS)  measured within the day beginning at the timestamp. Each GPS data point is calculated using the gas used in a single block divided by the time since the last block. Only `timeInterval=day` supported.

<ins>avgTps</ins>: The average Transactions Per Second (TPS) within the day beginning at the timestamp. The average is calculated by taking the sum of transactions within the day and dividing it by the time interval between the last block of the previous day and the last block of the day that begins at the timestamp. Only `timeInterval=day` supported.

<ins>maxTps</ins>: The max Transactions Per Second (TPS) measured within the day beginning at the timestamp. Each TPS data point is calculated by taking the number of transactions in a single block and dividing it by the time since the last block. Only `timeInterval=day` supported.

<ins>avgGasPrice</ins>: The average gas price within the day beginning at the timestamp. The gas price used is the price reported in transaction receipts. Only `timeInterval=day` supported.

<ins>maxGasPrice</ins>: The max gas price seen within the day beginning at the timestamp. The gas price used is the price reported in transaction receipts. Only `timeInterval=day` supported.

<ins>feesPaid</ins>: The sum of transaction fees paid within the day beginning at the timestamp. The fee is calculated as the gas used multiplied by the gas price as reported in all transaction receipts. Only `timeInterval=day` supported.

<APIPage document={"./public/openapi/popsicle.json"} operations={[{"path":"/v2/chains/{chainId}/metrics/{metric}","method":"get"}]} webhooks={[]} hasHead={false} />

# Get rolling window metrics for EVM chains (/docs/api-reference/metrics-api/chain-metrics/getEvmChainRollingWindowMetrics)

---
title: Get rolling window metrics for EVM chains
full: true
_openapi:
  method: GET
  route: /v2/chains/{chainId}/rollingWindowMetrics/{metric}
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Gets the rolling window metrics for an EVM chain for the last hour,
          day, week, month, 90 days, year, and all time. Active addresses/active
          senders only support last hour, day, and week.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Gets the rolling window metrics for an EVM chain for the last hour, day, week, month, 90 days, year, and all time. Active addresses/active senders only support last hour, day, and week.

<APIPage document={"./public/openapi/popsicle.json"} operations={[{"path":"/v2/chains/{chainId}/rollingWindowMetrics/{metric}","method":"get"}]} webhooks={[]} hasHead={false} />

# Get ICM summary metrics (/docs/api-reference/metrics-api/chain-metrics/getICMSummary)

---
title: Get ICM summary metrics
full: true
_openapi:
  method: GET
  route: /v2/icm/summary
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Get rolling window ICM message counts (last hour, day, month, 90 days,
          year, all time).


          Use filters (`srcBlockchainId`, `destBlockchainId`, `network`)  to
          select data, and the `groupBy` parameter for aggregation level.


          ### Examples:

            - **Specific pair**:   `?srcBlockchainId=...&destBlockchainId=...`

            - **From one source (aggregated)**: `?srcBlockchainId=...`

            - **From one source (by destination)**:   `?srcBlockchainId=...&groupBy=destBlockchainId`

            - **To one destination (aggregated)**: `?destBlockchainId=...`

            - **To one destination (by source)**:   `?destBlockchainId=...&groupBy=srcBlockchainId`

            - **Network total**: `?network=mainnet`

            - **Network breakdown**:   `?network=mainnet&groupBy=srcBlockchainId,destBlockchainId`.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Get rolling window ICM message counts (last hour, day, month, 90 days, year, all time).

Use filters (`srcBlockchainId`, `destBlockchainId`, `network`)  to select data, and the `groupBy` parameter for aggregation level.

### Examples:

  - **Specific pair**:   `?srcBlockchainId=...&destBlockchainId=...`

  - **From one source (aggregated)**: `?srcBlockchainId=...`

  - **From one source (by destination)**:   `?srcBlockchainId=...&groupBy=destBlockchainId`

  - **To one destination (aggregated)**: `?destBlockchainId=...`

  - **To one destination (by source)**:   `?destBlockchainId=...&groupBy=srcBlockchainId`

  - **Network total**: `?network=mainnet`

  - **Network breakdown**:   `?network=mainnet&groupBy=srcBlockchainId,destBlockchainId`.

<APIPage document={"./public/openapi/popsicle.json"} operations={[{"path":"/v2/icm/summary","method":"get"}]} webhooks={[]} hasHead={false} />

# Get ICM timeseries metrics (/docs/api-reference/metrics-api/chain-metrics/getICMTimeseries)

---
title: Get ICM timeseries metrics
full: true
_openapi:
  method: GET
  route: /v2/icm/timeseries
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Get historical ICM message counts with flexible grouping.


          Use filters (`srcBlockchainId`, `destBlockchainId`, `network`)  to
          select data, and the `groupBy` parameter for aggregation level.


          ### Examples:

            - **Specific pair**:   `?srcBlockchainId=...&destBlockchainId=...`

            - **From one source (aggregated)**: `?srcBlockchainId=...`

            - **From one source (by destination)**:   `?srcBlockchainId=...&groupBy=destBlockchainId`

            - **To one destination (aggregated)**: `?destBlockchainId=...`

            - **To one destination (by source)**:   `?destBlockchainId=...&groupBy=srcBlockchainId`

            - **Network total**: `?network=mainnet`

            - **Network breakdown**:   `?network=mainnet&groupBy=srcBlockchainId,destBlockchainId`.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Get historical ICM message counts with flexible grouping.

Use filters (`srcBlockchainId`, `destBlockchainId`, `network`)  to select data, and the `groupBy` parameter for aggregation level.

### Examples:

  - **Specific pair**:   `?srcBlockchainId=...&destBlockchainId=...`

  - **From one source (aggregated)**: `?srcBlockchainId=...`

  - **From one source (by destination)**:   `?srcBlockchainId=...&groupBy=destBlockchainId`

  - **To one destination (aggregated)**: `?destBlockchainId=...`

  - **To one destination (by source)**:   `?destBlockchainId=...&groupBy=srcBlockchainId`

  - **Network total**: `?network=mainnet`

  - **Network breakdown**:   `?network=mainnet&groupBy=srcBlockchainId,destBlockchainId`.

<APIPage document={"./public/openapi/popsicle.json"} operations={[{"path":"/v2/icm/timeseries","method":"get"}]} webhooks={[]} hasHead={false} />

# Get staking metrics for a given subnet (/docs/api-reference/metrics-api/chain-metrics/getStakingMetrics)

---
title: Get staking metrics for a given subnet
full: true
_openapi:
  method: GET
  route: /v2/networks/{network}/metrics/{metric}
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Gets staking metrics for a given subnet.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Gets staking metrics for a given subnet.

<APIPage document={"./public/openapi/popsicle.json"} operations={[{"path":"/v2/networks/{network}/metrics/{metric}","method":"get"}]} webhooks={[]} hasHead={false} />

# Get chain information for supported blockchain (/docs/api-reference/metrics-api/evm-chains/getChain)

---
title: Get chain information for supported blockchain
full: true
_openapi:
  method: GET
  route: /v2/chains/{chainId}
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Get chain information for Metrics API supported blockchain.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Get chain information for Metrics API supported blockchain.

<APIPage document={"./public/openapi/popsicle.json"} operations={[{"path":"/v2/chains/{chainId}","method":"get"}]} webhooks={[]} hasHead={false} />

# Get a list of supported blockchains (/docs/api-reference/metrics-api/evm-chains/listChains)

---
title: Get a list of supported blockchains
full: true
_openapi:
  method: GET
  route: /v2/chains
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Get a list of Metrics API supported blockchains.  This endpoint is
          paginated and supports a maximum page size of 10000.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Get a list of Metrics API supported blockchains.  This endpoint is paginated and supports a maximum page size of 10000.

<APIPage document={"./public/openapi/popsicle.json"} operations={[{"path":"/v2/chains","method":"get"}]} webhooks={[]} hasHead={false} />

# Get the health of the service (/docs/api-reference/metrics-api/health-check/metrics-health-check)

---
title: Get the health of the service
full: true
_openapi:
  method: GET
  route: /v2/health-check
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Check the health of the service.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Check the health of the service.

<APIPage document={"./public/openapi/popsicle.json"} operations={[{"path":"/v2/health-check","method":"get"}]} webhooks={[]} hasHead={false} />

# Get metric values with given nodeId and timestamp range (/docs/api-reference/metrics-api/l1-validator-metrics/getMetricsByNodeId)

---
title: Get metric values with given nodeId and timestamp range
full: true
_openapi:
  method: GET
  route: /v2/validator/{nodeId}/metrics/{metric}
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Get given metric values for a given nodeId with or without a timestamp
          range.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Get given metric values for a given nodeId with or without a timestamp range.

<APIPage document={"./public/openapi/popsicle.json"} operations={[{"path":"/v2/validator/{nodeId}/metrics/{metric}","method":"get"}]} webhooks={[]} hasHead={false} />

# Get metric values with given subnetId and timestamp range (/docs/api-reference/metrics-api/l1-validator-metrics/getMetricsBySubnetId)

---
title: Get metric values with given subnetId and timestamp range
full: true
_openapi:
  method: GET
  route: /v2/subnet/{subnetId}/metrics/{metric}
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Get given metric values for a given subnetId with or without a
          timestamp range.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Get given metric values for a given subnetId with or without a timestamp range.

<APIPage document={"./public/openapi/popsicle.json"} operations={[{"path":"/v2/subnet/{subnetId}/metrics/{metric}","method":"get"}]} webhooks={[]} hasHead={false} />

# Get metric values with given validationId and timestamp range (/docs/api-reference/metrics-api/l1-validator-metrics/getMetricsByValidationId)

---
title: Get metric values with given validationId and timestamp range
full: true
_openapi:
  method: GET
  route: /v2/validation/{l1ValidationId}/metrics/{metric}
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Get given metric values for a given validationId with or without a
          timestamp range.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Get given metric values for a given validationId with or without a timestamp range.

<APIPage document={"./public/openapi/popsicle.json"} operations={[{"path":"/v2/validation/{l1ValidationId}/metrics/{metric}","method":"get"}]} webhooks={[]} hasHead={false} />

# Get given metric for all validators (/docs/api-reference/metrics-api/l1-validator-metrics/getTotalL1ValidatorMetrics)

---
title: Get given metric for all validators
full: true
_openapi:
  method: GET
  route: /v2/validators/metrics/{metric}
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Get given metric's value for all validators.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Get given metric's value for all validators.

<APIPage document={"./public/openapi/popsicle.json"} operations={[{"path":"/v2/validators/metrics/{metric}","method":"get"}]} webhooks={[]} hasHead={false} />

# Composite query (/docs/api-reference/metrics-api/looking-glass/compositeQueryV1)

---
title: Composite query
full: true
_openapi:
  method: POST
  route: /v1/lookingGlass/compositeQuery
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Composite query to get list of addresses from multiple subqueries.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Composite query to get list of addresses from multiple subqueries.

<APIPage document={"./public/openapi/popsicle.json"} operations={[{"path":"/v1/lookingGlass/compositeQuery","method":"post"}]} webhooks={[]} hasHead={false} />

# Composite query (/docs/api-reference/metrics-api/looking-glass/compositeQueryV2)

---
title: Composite query
full: true
_openapi:
  method: POST
  route: /v2/lookingGlass/compositeQuery
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Composite query to get list of addresses from multiple subqueries.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Composite query to get list of addresses from multiple subqueries.

<APIPage document={"./public/openapi/popsicle.json"} operations={[{"path":"/v2/lookingGlass/compositeQuery","method":"post"}]} webhooks={[]} hasHead={false} />

# Get addresses by balance over time (/docs/api-reference/metrics-api/looking-glass/getAddressesByBalanceOverTime)

---
title: Get addresses by balance over time
full: true
_openapi:
  method: GET
  route: /v2/chains/{chainId}/contracts/{address}/balances
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Get list of addresses and their latest balances that have held more
          than a certain threshold of a given token during the specified time
          frame.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Get list of addresses and their latest balances that have held more than a certain threshold of a given token during the specified time frame.

<APIPage document={"./public/openapi/popsicle.json"} operations={[{"path":"/v2/chains/{chainId}/contracts/{address}/balances","method":"get"}]} webhooks={[]} hasHead={false} />

# Get addresses by BTCb bridged balance (/docs/api-reference/metrics-api/looking-glass/getAddressesByBtcbBridged)

---
title: Get addresses by BTCb bridged balance
full: true
_openapi:
  method: GET
  route: /v2/chains/43114/btcb/bridged:getAddresses
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Get list of addresses and their net bridged amounts that have bridged
          more than a certain threshold.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Get list of addresses and their net bridged amounts that have bridged more than a certain threshold.

<APIPage document={"./public/openapi/popsicle.json"} operations={[{"path":"/v2/chains/43114/btcb/bridged:getAddresses","method":"get"}]} webhooks={[]} hasHead={false} />

# Get NFT holders by contract address (/docs/api-reference/metrics-api/looking-glass/getNftHoldersByContractAddress)

---
title: Get NFT holders by contract address
full: true
_openapi:
  method: GET
  route: /v2/chains/{chainId}/contracts/{address}/nfts:listHolders
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Get list of NFT holders and number of NFTs held by contract address.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Get list of NFT holders and number of NFTs held by contract address.

<APIPage document={"./public/openapi/popsicle.json"} operations={[{"path":"/v2/chains/{chainId}/contracts/{address}/nfts:listHolders","method":"get"}]} webhooks={[]} hasHead={false} />

# Get addresses running validators during a given time frame (/docs/api-reference/metrics-api/looking-glass/getValidatorsByDateRange)

---
title: Get addresses running validators during a given time frame
full: true
_openapi:
  method: GET
  route: /v2/subnets/{subnetId}/validators:getAddresses
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Get list of addresses and AddValidatorTx timestamps set to receive
          awards for validation periods during the specified time frame.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Get list of addresses and AddValidatorTx timestamps set to receive awards for validation periods during the specified time frame.

<APIPage document={"./public/openapi/popsicle.json"} operations={[{"path":"/v2/subnets/{subnetId}/validators:getAddresses","method":"get"}]} webhooks={[]} hasHead={false} />

# Track ERC-20 Transfers (/docs/api-reference/webhook-api/tutorials/erc20transfer)

---
title: Track ERC-20 Transfers
description: How to track ERC-20 transfers with the Webhooks API
icon: Coins
---

In a smart contract, events serve as notifications of specific occurrences, like transactions, or changes in ownership. Each event is uniquely identified by its event signature, which is calculated using the keccak 256 hash of the event name and its input argument types.

For example, for an ERC-20 transfer event, the event signature is determined by taking the hash of `Transfer(address,address,uint256)`. To compute this hash yourself, you can use an online `keccak-256` converter and you’ll see that the hexadecimal representation of Transfer(address,address,uint256) is 0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef. For a full list of signatures check [https://www.4byte.directory/event-signatures/](https://www.4byte.directory/event-signatures/).

Take into consideration that the Transfer event for ERC-20 and ERC-721 tokens is similar. Here is the Transfer event prototype on each standard:

* **ERC20**:\
  `event Transfer(address indexed _from, address indexed _to, uint256 _value);`
* **ERC721**:\
  `event Transfer(address indexed _from, address indexed _to, uint256 indexed _tokenId);`

These two signatures are indeed the same when you hash them to identify `Transfer` events. The example below illustrates how to set up filtering to receive transfer events.

In this example, we will monitor all the USDT transfers on the C-chain. If we go to any block explorer, select a USDT transaction, and look at `Topic 0` from the transfer event, we can get the signature.

<img src="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/function-signature.png?fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=86336e01db1fbfa22e5c313f371defdb" data-og-width="2746" width="2746" data-og-height="694" height="694" data-path="images/function-signature.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/function-signature.png?w=280&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=86be3ca19e0ca7931285fb669af8cdb5 280w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/function-signature.png?w=560&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=bf86f3f2cebace8a07ffa511a824abb5 560w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/function-signature.png?w=840&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=36762aaa05508745908e07fb8c166715 840w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/function-signature.png?w=1100&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=21f6a095afce08def0633554fdff81c9 1100w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/function-signature.png?w=1650&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=874fdd1d396c9ca39cae06db51efd042 1650w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/function-signature.png?w=2500&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=464f87dad439c35894a5f9dff10bef3d 2500w" />

With the event signature, we can create the webhook as follows:

```bash
curl --location '<https://glacier-api.avax.network/v1/webhooks'>
--header 'x-glacier-api-key: <YOUR_API_KEY'
--header 'Content-Type: application/json'
--data '{
   "url": "https://webhook.site/30eb3703-04f0-4a01-8903-fe3f5afb78bc",
   "chainId": "43114",
   "eventType": "address_activity",
   "metadata": {
       "addresses": ["0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7"],
       "eventSignatures": [
           "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
        ]
   },
   "name": "USDT",
   "description": "USDT"
}'
```

Once the the webhook is created we start receiving the events:

```json
{
  "webhookId": "401da7d9-d6d7-46c8-b431-72ff1e1543f4",
  "eventType": "address_activity",
  "messageId": "bc9732db-2430-4296-afc3-c51267beb14a",
  "event": {
    "transaction": {
      "blockHash": "0x2a47bebed93db4a21cc8339980f004cc67f17d0dff4a368001e450e7be2edaa0",
      "blockNumber": "45396106",
      "from": "0x737F6b0b8A04e8462d0fC7076451298F0dA9a972",
      "gas": "80000",
      "gasPrice": "52000000000",
      "maxFeePerGas": "52000000000",
      "maxPriorityFeePerGas": "2000000000",
      "txHash": "0xfd91150d236ec5c3b1ee325781affad5b0b4d7eb0187c84c220ab115eaa563e8",
      "txStatus": "1",
      "input": "0xa9059cbb00000000000000000000000040e832c3df9562dfae5a86a4849f27f687a9b46b00000000000000000000000000000000000000000000000000000000c68b2a69",
      "nonce": "2",
      "to": "0x9702230a8ea53601f5cd2dc00fdbc13d4df4a8c7",
      "transactionIndex": 2,
      "value": "0",
      "type": 2,
      "chainId": "43114",
      "receiptCumulativeGasUsed": "668508",
      "receiptGasUsed": "44038",
      "receiptEffectiveGasPrice": "27000000000",
      "receiptRoot": "0xe5b018c29a77c8a92c4ea2f2d7e58820283041a52e14a0620d90d13b881e1ee3",
      "erc20Transfers": [
        {
          "transactionHash": "0xfd91150d236ec5c3b1ee325781affad5b0b4d7eb0187c84c220ab115eaa563e8",
          "type": "ERC20",
          "from": "0x737F6b0b8A04e8462d0fC7076451298F0dA9a972",
          "to": "0x40E832C3Df9562DfaE5A86A4849F27F687A9B46B",
          "value": "3331009129",
          "blockTimestamp": 1715621840,
          "logIndex": 0,
          "erc20Token": {
            "address": "0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7",
            "name": "TetherToken",
            "symbol": "USDt",
            "decimals": 6,
            "valueWithDecimals": "3331.009129"
          }
        }
      ],
      "erc721Transfers": [],
      "erc1155Transfers": [],
      "internalTransactions": [
        {
          "from": "0x737F6b0b8A04e8462d0fC7076451298F0dA9a972",
          "to": "0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7",
          "internalTxType": "CALL",
          "value": "0",
          "gasUsed": "44038",
          "gasLimit": "80000",
          "transactionHash": "0xfd91150d236ec5c3b1ee325781affad5b0b4d7eb0187c84c220ab115eaa563e8"
        },
        {
          "from": "0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7",
          "to": "0xBA2a995Bd4ab9e605454cCEf88169352cd5F75A6",
          "internalTxType": "DELEGATECALL",
          "value": "0",
          "gasUsed": "15096",
          "gasLimit": "50301",
          "transactionHash": "0xfd91150d236ec5c3b1ee325781affad5b0b4d7eb0187c84c220ab115eaa563e8"
        }
      ],
      "blockTimestamp": 1715621840
    },
    "logs": [
      {
        "address": "0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7",
        "topic0": "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
        "topic1": "0x000000000000000000000000737f6b0b8a04e8462d0fc7076451298f0da9a972",
        "topic2": "0x00000000000000000000000040e832c3df9562dfae5a86a4849f27f687a9b46b",
        "topic3": null,
        "data": "0x00000000000000000000000000000000000000000000000000000000c68b2a69",
        "transactionIndex": 2,
        "logIndex": 19,
        "removed": false
      }
    ]
  }
}
```

# Track ERC-721 Transfers (/docs/api-reference/webhook-api/tutorials/erc721transfer)

---
title: Track ERC-721 Transfers
description: How to track ERC-721 transfers with the Webhooks API
icon: Wallpaper
---

In this tutorial, we build upon the previous in which we tracked ERC20 transfers. To monitor NFT transfers, we will utilize the event signature. If you wish to receive a notification every time a Dokyo NFT is transferred, you can use an expression similar to the following:

```bash
curl --location 'https://glacier-api.avax.network/v1/webhooks' \
--header 'x-glacier-api-key: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "url": "https://webhook.site/961a0d1b-a7ed-42fd-9eab-d7e4c7eb1227",
    "chainId": "43114",
    "eventType": "address_activity",
    "metadata": {
        "addresses": ["0x54C800d2331E10467143911aabCa092d68bF4166"],
        "includeInternalTxs": false,
        "includeLogs": true,
        "eventSignatures": [
           "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
        ]

    },
    "name": "Dokyo NFT",
    "description": "Dokyo NFT"
}'
```

Whenever an NFT is transferred you’ll receive a payload like this:

```json
{
  "webhookId": "6d1bd383-aa8d-47b5-b793-da6d8a115fde",
  "eventType": "address_activity",
  "messageId": "6a364b45-47a2-45af-97c3-0ddc2e87ad36",
  "event": {
    "transaction": {
      "blockHash": "0x30da6a8887bf2c26b7921a1501abd6e697529427e4a4f52a9d4fc163a2344b46",
      "blockNumber": "42649820",
      "from": "0x0000333883f313AD709f583D0A3d2E18a44EF29b",
      "gas": "245004",
      "gasPrice": "30000000000",
      "maxFeePerGas": "30000000000",
      "maxPriorityFeePerGas": "30000000000",
      "txHash": "0x2f1a9e2b8719536997596d878f21b70f2ce0901287aa3480d923e7ffc68ac3bc",
      "txStatus": "1",
      "input": "0xafde1b3c0000000000000000000000000…0000000000000000000000000000000000",
      "nonce": "898",
      "to": "0x398baa6ffc99126671ab6be565856105a6118a40",
      "transactionIndex": 0,
      "value": "0",
      "type": 0,
      "chainId": "43114",
      "receiptCumulativeGasUsed": "163336",
      "receiptGasUsed": "163336",
      "receiptEffectiveGasPrice": "30000000000",
      "receiptRoot": "0xdf05c214cee5ff908744e13a3b2879fdba01c9c7f95073670cb23ed735126178",
      "contractAddress": "0x0000000000000000000000000000000000000000",
      "blockTimestamp": 1709930290
    },
    "logs": [
      {
        "address": "0xB31f66AA3C1e785363F0875A1B74E27b85FD66c7",
        "topic0": "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
        "topic1": "0x0000000000000000000000008cdd7a500f21455361cf1c2e01c0525ce92481b2",
        "topic2": "0x0000000000000000000000000000333883f313ad709f583d0a3d2e18a44ef29b",
        "topic3": null,
        "data": "0x000000000000000000000000000000000000000000000001a6c5c6f4f4f6d060",
        "transactionIndex": 0,
        "logIndex": 0,
        "removed": false
      },
      {
        "address": "0x54C800d2331E10467143911aabCa092d68bF4166",
        "topic0": "0x8c5be1e5ebec7d5bd14f71427d1e84f3dd0314c0f7b2291e5b200ac8c7c3b925",
        "topic1": "0x0000000000000000000000000000333883f313ad709f583d0a3d2e18a44ef29b",
        "topic2": "0x0000000000000000000000000000000000000000000000000000000000000000",
        "topic3": "0x0000000000000000000000000000000000000000000000000000000000001350",
        "data": "0x",
        "transactionIndex": 0,
        "logIndex": 1,
        "removed": false
      },
      {
        "address": "0x54C800d2331E10467143911aabCa092d68bF4166",
        "topic0": "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
        "topic1": "0x0000000000000000000000000000333883f313ad709f583d0a3d2e18a44ef29b",
        "topic2": "0x0000000000000000000000008cdd7a500f21455361cf1c2e01c0525ce92481b2",
        "topic3": "0x0000000000000000000000000000000000000000000000000000000000001350",
        "data": "0x",
        "transactionIndex": 0,
        "logIndex": 2,
        "removed": false
      },
      {
        "address": "0xB31f66AA3C1e785363F0875A1B74E27b85FD66c7",
        "topic0": "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
        "topic1": "0x0000000000000000000000008cdd7a500f21455361cf1c2e01c0525ce92481b2",
        "topic2": "0x00000000000000000000000087f45335268512cc5593d435e61df4d75b07d2a2",
        "topic3": null,
        "data": "0x000000000000000000000000000000000000000000000000087498758a04efb0",
        "transactionIndex": 0,
        "logIndex": 3,
        "removed": false
      },
      {
        "address": "0xB31f66AA3C1e785363F0875A1B74E27b85FD66c7",
        "topic0": "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef",
        "topic1": "0x0000000000000000000000008cdd7a500f21455361cf1c2e01c0525ce92481b2",
        "topic2": "0x000000000000000000000000610512654af4fa883bb727afdff2dd78b65342b7",
        "topic3": null,
        "data": "0x000000000000000000000000000000000000000000000000021d261d62813bec",
        "transactionIndex": 0,
        "logIndex": 4,
        "removed": false
      },
      {
        "address": "0x398BAa6FFc99126671Ab6be565856105a6118A40",
        "topic0": "0x50273fa02273cceea9cf085b42de5c8af60624140168bd71357db833535877af",
        "topic1": null,
        "topic2": null,
        "topic3": null,
        "data": "0x0000000000009911a89f400000000000000000000…0000010",
        "transactionIndex": 0,
        "logIndex": 5,
        "removed": false
      }
    ]
  }
}
```

# Monitoring multiple addresses (/docs/api-reference/webhook-api/tutorials/monitor-multiple-addresses)

---
title: Monitoring multiple addresses
description: How to monitor multiple addresses with the Webhooks API
icon: BookUser
---

A single webhook can monitor multiple addresses, you don't need to create one webhook per address.

<Callout>In the free plan, you add up to 5 addresses per webhook. If you need more than that you can upgrade your plan.</Callout>

### Creating the webhook

Let's start by creating a new webhook to monitor all USDC and USDT activity:

```bash
curl --location 'https://glacier-api.avax.network/v1/webhooks' \
--header 'x-glacier-api-key: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "url": "https://webhook.site/4eb31e6c-a088-4dcb-9a5d-e9341624b584",
    "chainId": "43114",
    "eventType": "address_activity",
    "includeInternalTxs": true,
    "includeLogs": true,
    "metadata": {
        "addresses": [
            "0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7",
            "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E"
            ]
    },
    "name": "Tokens",
    "description": "Track tokens"
}
```

It returns the following:

```json
{
    "id": "401da7d9-d6d7-46c8-b431-72ff1e1543f4",
    "eventType": "address_activity",
    "chainId": "43114",
    "metadata": {
        "addresses": [
            "0x9702230A8Ea53601f5cD2dc00fDBc13d4dF4A8c7",
            "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E"
        ]
    },
    "includeInternalTxs": true,
    "includeLogs": true,
    "url": "https://webhook.site/4eb31e6c-a088-4dcb-9a5d-e9341624b584",
    "status": "active",
    "createdAt": 1715621587726,
    "name": "Tokens",
    "description": "Track tokens"
}
```

### Adding addresses to monitor

With the webhook `id` we can add more addresses. In this case, let's add the contract addresses for JOE and PNG:

```bash
curl --location --request PATCH 'https://glacier-api.avax.network/v1/webhooks/401da7d9-d6d7-46c8-b431-72ff1e1543f4/addresses' \
--header 'x-glacier-api-key: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
  "addresses": [
            "0x6e84a6216eA6dACC71eE8E6b0a5B7322EEbC0fDd",
            "0x60781C2586D68229fde47564546784ab3fACA982"
  ]
}
```

Following that, we will begin to receive events from the four smart contracts integrated into the webhook: USDC, USDT, JOE, and PNG.

### Deleting addresses

To remove addresses, simply send an array:

```bash
curl --location --request DELETE 'https://glacier-api.avax.network/v1/webhooks/401da7d9-d6d7-46c8-b431-72ff1e1543f4/addresses' \
--header 'x-glacier-api-key: <YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data '{
  "addresses": [
    "0x735D8f3B6A5d2c96D0405230c50Eaf96794FbB88"
  ]
}
```

# Send Push Notifications (/docs/api-reference/webhook-api/tutorials/push)

---
title: Send Push Notifications
description: How to send push notifications with the Webhooks API
icon: Bell
---
In this tutorial, we'll explore how to send push notifications to a user's wallet whenever they receive a transaction containing tokens. It's a handy way to keep users informed about their account activity.

We'll be using [OneSignal](https://onesignal.com) for sending push notifications, but you can also achieve similar functionality with other services like [Firebase Cloud Messaging](https://firebase.google.com/docs/cloud-messaging) or [AWS Pinpoint](https://aws.amazon.com/pinpoint/).

### Step 1 - OneSignal Setup

The first step is to create a free account in [OneSignal](https://onesignal.com). For this example, we are going to use Web push but it works similarly for mobile.

To get started, the first step is to create a free account on OneSignal. Once you've signed up and logged in, we'll proceed to create a new OneSignal App.

For this example, we'll focus on using Web push notifications, but keep in mind that the process is quite similar for mobile apps.

Create a new OneSignal App and select Web. Once your app is created, you'll be provided with an App ID and API Key. Keep these credentials handy as we'll need them later to integrate OneSignal with our code.

<img src="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/new-onesignal-app.png?fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=a1655c7c6c7612674e58cc51c47667fd" data-og-width="1884" width="1884" data-og-height="1624" height="1624" data-path="images/new-onesignal-app.png" data-optimize="true" data-opv="3" />

Next, click on Configure Your Platform and select Web, select Code Custom, and set the site URL `http://localhost:3000` and enable both toggles for local development.

<img src="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-web-configuration.png?fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=d0f8b0e5a0bb760a6d6da6326cf7588d" data-og-width="2572" width="2572" data-og-height="2432" height="2432" data-path="images/onesignal-web-configuration.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-web-configuration.png?w=280&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=75dbc845a08b371e8a780c03239e9bb6 280w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-web-configuration.png?w=560&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=31d057925a5ee7840ac49688d81513a5 560w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-web-configuration.png?w=840&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=5b3ce1c389d8ca65e0ee1c0027140f11 840w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-web-configuration.png?w=1100&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=942e156dc7ddbf45ff8e3129a90dc936 1100w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-web-configuration.png?w=1650&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=c094e4046674e6e8db902ffa76b8b330 1650w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-web-configuration.png?w=2500&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=bd1f699c0bb61fa6baf0f34b36ae4f13 2500w" />

This will generate a code snippet to add to your code. Download the OneSignal SDK files and copy them to the top-level root of your directory.

<img src="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onsignal-snippet.png?fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=1de37f66dbd19b46f75a938a4a37323a" data-og-width="2572" width="2572" data-og-height="2784" height="2784" data-path="images/onsignal-snippet.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onsignal-snippet.png?w=280&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=fcc0aa943efd60ff4ad161dfe6efdc7b 280w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onsignal-snippet.png?w=560&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=8752058899bfd0b54f48fce57448826d 560w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onsignal-snippet.png?w=840&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=c3d93c31a409cfff91f736ef7faf2680 840w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onsignal-snippet.png?w=1100&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=2dbb1217d71dfcf635133884ce531a3f 1100w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onsignal-snippet.png?w=1650&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=01375f360ded2e7c815de9d64aaa2ce9 1650w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onsignal-snippet.png?w=2500&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=34330c9282acb58554756d97ffae3500 2500w" />

### Step 2 - Frontend Setup

In a real-world scenario, your architecture typically involves customers signing up for subscriptions within your Web or Mobile App. To ensure these notifications are sent out, your app needs to register with a push notification provider such as OneSignal.

To maintain privacy and security, we'll be using a hash of the wallet address as the `externalID` instead of directly sharing the addresses with OneSignal. This `externalID` will then be mapped to an address in our database. So, when our backend receives a webhook for a specific address, it can retrieve the corresponding `externalID` and send a push notification accordingly.
<img src="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-architecture.png?fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=5e450fcdbb76408198d570d06198256f" alt="OneSignal Architecture" data-og-width="1396" width="1396" data-og-height="1072" height="1072" data-path="images/onesignal-architecture.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-architecture.png?w=280&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=3056807946d72d2eee495f4f969668eb 280w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-architecture.png?w=560&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=f3388e86a7f2f107c97dec83dc6c2948 560w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-architecture.png?w=840&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=19b7ea6c2660a372ef1ca682f4dac6d4 840w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-architecture.png?w=1100&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=44e4c4514a393398e94a16ac41931906 1100w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-architecture.png?w=1650&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=1ca2f7c9374450eb657853998ce8caa1 1650w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-architecture.png?w=2500&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=d03d911305eb93c6ec6e6553e787e3de 2500w" />

For the sake of simplicity in our demonstration, we'll present a basic scenario where our frontend app retrieves the wallet address and registers it with OneSignal. Additionally, we'll simulate a database using an array within the code. Download the [sample code](https://github.com/javiertc/webhookdemo) and you'll see `client/index.html` with this content.

```html
<html>
<head>
  <script src="https://cdn.jsdelivr.net/npm/web3@latest/dist/web3.min.js"></script>
  <script src="https://cdn.onesignal.com/sdks/web/v16/OneSignalSDK.page.js" defer></script>
  <script>
    window.OneSignalDeferred = window.OneSignalDeferred || [];
    OneSignalDeferred.push(function(OneSignal) {
      OneSignal.init({
        appId: "a63e0a25-186c-40a7-8fce-9c0fde324400",
        safari_web_id: "web.onesignal.auto.67fef31a-7360-4fd8-9645-1463ac233cef",
        notifyButton: {
          enable: false,
        },
        allowLocalhostAsSecureOrigin: true,
      });
    });

    window.connect = async function() {
      try {
        if (!window.ethereum) {
          throw new Error("Avalanche wallet not detected");
        }
        const accounts = await window.ethereum.request({ method: "eth_requestAccounts" });
        window.web3 = new Web3(window.ethereum);

        //Create externalID based on the address
        const externalID = web3.utils.sha3(accounts[0].toLowerCase()).slice(2);
        console.log("externalID:", externalID);

        OneSignal.login(externalID);
        OneSignal.Notifications.requestPermission();
      } catch (error) {
        console.error("Error connecting to Avalanche wallet:", error.message);
      }
    };
  </script>
</head>
<body>
  <h1>Avalanche push notifications</h1>
  <button onclick="window.connect()">Connect</button>
</body>
</html>
```

Run the project using Nodejs.

```bash
npm install express axios path body-parser dotenv
node app.js
```

Open a Chrome tab and type `http://localhost:3000`, you should see something like this. Then click on Connect and accept receiving push notifications. If you are using MacOS, check in **System Settings** > **Notifications** that you have enabled notifications for the browser.

<img src="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-connect.png?fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=ae7af57911b5c970833a39974df1d50b" data-og-width="2216" width="2216" data-og-height="1144" height="1144" data-path="images/onesignal-connect.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-connect.png?w=280&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=b5d75487527b3671f395986c2125407d 280w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-connect.png?w=560&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=23b8447cb83d9d9eb4a8be31fe9d89ee 560w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-connect.png?w=840&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=b5fb06deb480000404eb86e4826b9e40 840w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-connect.png?w=1100&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=c2a18635bca4f3f4d4822654ab1bc863 1100w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-connect.png?w=1650&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=c0c81768ee7b3962210d98c130dc4405 1650w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-connect.png?w=2500&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=10a4a54aa32fdfb14e1c420af48d106a 2500w" />

If everything runs correctly your browser should be registered in OneSignal. To check go to **Audience** > **Subscriptions** and verify that your browser is registered.

<img src="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-subscription.png?fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=27e8e9430e32f1761a976686c8d28bcb" data-og-width="2075" width="2075" data-og-height="1312" height="1312" data-path="images/onesignal-subscription.png" data-optimize="true" data-opv="3" />

### Step 3 - Backend Setup

Now, let's configure the backend to manage webhook events and dispatch notifications based on the incoming data. Here's the step-by-step process:

1. **Transaction Initiation:** When someone starts a transaction with your wallet as the destination, the webhooks detect the transaction and generate an event.
2. **Event Triggering:** The backend receives the event triggered by the transaction, containing the destination address.
3. **ExternalID Retrieval:** Using the received address, the backend retrieves the corresponding `externalID` associated with that wallet.
4. **Notification Dispatch:** The final step involves sending a notification through OneSignal, utilizing the retrieved `externalID`.
   <img src="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-backend.png?fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=f9f4ba254762a15eb3adb32c02a8dca5" alt="OneSignal Backend" data-og-width="2305" width="2305" data-og-height="1072" height="1072" data-path="images/onesignal-backend.png" data-optimize="true" data-opv="3" srcset="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-backend.png?w=280&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=aa990f7f2274c7a8d354ba9673d5b805 280w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-backend.png?w=560&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=0547ba77ae5a9d2c1c8b74f7e2dd0703 560w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-backend.png?w=840&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=fb40164003e26bfdb5662fe4aaf5aee5 840w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-backend.png?w=1100&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=4e4a87b57e62617efdb3fc8d834b50ee 1100w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-backend.png?w=1650&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=48537241c64e0dc7f3a33de9bbff0587 1650w, https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-backend.png?w=2500&fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=380a39b72d033ec6dc00f783bea413cc 2500w" />

#### 3.1 - Use Ngrok to tunnel the traffic to localhost

If we want to test the webhook in our computer and we are behind a proxy/NAT device or a firewall we need a tool like Ngrok. Glacier will trigger the webhook and make a POST to the Ngrok cloud, then the request is forwarded to your local Ngrok client who in turn forwards it to the Node.js app listening on port 3000.
Go to [https://ngrok.com/](https://ngrok.com/) create a free account, download the binary, and connect to your account. Create a Node.js app with Express and paste the following code to receive the webhook:

To start an HTTP tunnel forwarding to your local port 3000 with Ngrok, run this next:

```bash
./ngrok http 3000
```

You should see something like this:

```
ngrok                                                                                                                                                                           (Ctrl+C to quit)

Take our ngrok in production survey! https://forms.gle/aXiBFWzEA36DudFn6

Session Status                online
Account                       javier.toledo@avalabs.org (Plan: Free)
Version                       3.8.0
Region                        United States (us)
Latency                       48ms
Web Interface                 http://127.0.0.1:4040
Forwarding                    https://c902-2600-1700-5220-11a0-813c-d5ac-d72c-f7fd.ngrok-free.app -> http://localhost:3000

Connections                   ttl     opn     rt1     rt5     p50     p90
                              33      0       0.00    0.00    5.02    5.05

HTTP Requests
-------------
```

#### 3.2 - Create the webhook

The webhook can be created using the [Avacloud Dashboard](https://app.avacloud.io/) or Glacier API. For convenience, we are going to use cURL. For that copy the forwarding URL generated by Ngrok and append the `/callbackpath` and our address.

```bash
curl --location 'https://glacier-api-dev.avax.network/v1/webhooks' \
--header 'x-glacier-api-key: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
    "url": " https://c902-2600-1700-5220-11a0-813c-d5ac-d72c-f7fd.ngrok-free.app/callback",
    "chainId": "43113",
    "eventType": "address_activity",
    "includeInternalTxs": true,
    "includeLogs": true,
    "metadata": {
        "addresses": ["0x8ae323046633A07FB162043f28Cea39FFc23B50A"]
    },
    "name": "My wallet",
    "description": "My wallet"
}'
```

<Callout> Don't forget to add your API Key. If you don't have one go to the [Avacloud Dashboard](https://app.avacloud.io/) and create a new one. </Callout>

#### 3.3 - The backend

To run the backend we need to add the environment variables in the root of your project. For that create an `.env` file with the following values:

```
PORT=3000
ONESIGNAL_API_KEY=<YOUR_ONESIGNAL_API_KEY>
APP_ID=<YOUR_ONESIGNAL_APP_ID>
```

<Callout> To get the APP ID from OneSignal go to **Settings** > **Keys and IDs** </Callout>

Since we are simulating the connection to a database to retrieve the externalID, we need to add the wallet address and the OneSignal externalID to the myDB array.

```javascript
//simulating a DB
const myDB = [
    { name: 'wallet1', address: '0x8ae323046633A07FB162043f28Cea39FFc23B50A', externalID: '9c96e91d40c7a44c763fb55960e12293afbcfaf6228860550b0c1cc09cd40ac3' },
    { name: 'wallet2', address: '0x1f83eC80D755A87B31553f670070bFD897c40CE0', externalID: '0xd39d39c99305c6df2446d5cc3d584dc1eb041d95ac8fb35d4246f1d2176bf330' }
];
```

The code handles a webhook event triggered when a wallet receives a transaction, performs a lookup in the simulated "database" using the receiving address to retrieve the corresponding OneSignal `externalID`, and then sends an instruction to OneSignal to dispatch a notification to the browser, with OneSignal ultimately delivering the web push notification to the browser.

```javascript
require('dotenv').config();
const axios = require('axios');
const express = require('express');
const bodyParser = require('body-parser');
const path = require('path');

const app = express();
const port = process.env.PORT || 3000;

//  Serve static website
app.use(bodyParser.json());
app.use(express.static(path.join(__dirname, './client')));

//simulating a DB
const myDB = [
    { name: 'wallet1', address: '0x8ae323046633A07FB162043f28Cea39FFc23B50A', externalID: '9c96e91d40c7a44c763fb55960e12293afbcfaf6228860550b0c1cc09cd40ac3' },
    { name: 'wallet2', address: '0x1f83eC80D755A87B31553f670070bFD897c40CE0', externalID: '0xd39d39c99305c6df2446d5cc3d584dc1eb041d95ac8fb35d4246f1d2176bf330' }
];

app.post('/callback', async (req, res) => {
    const { body } = req;
    try {
        res.sendStatus(200);
        handleTransaction(body.event.transaction).catch(error => {
            console.error('Error processing transaction:', error);
        });
    } catch (error) {
        console.error('Error processing transaction:', error);
        res.status(500).json({ error: 'Internal server error' });
    }
});

// Handle transaction
async function handleTransaction(transaction) {
    console.log('*****Transaction:', transaction);
    const notifications = [];

    const erc20Transfers = transaction?.erc20Transfers || [];
    for (const transfer of erc20Transfers) {
        const externalID = await getExternalID(transfer.to);
        const { symbol, valueWithDecimals } = transfer.erc20Token;
        notifications.push({
            type: transfer.type,
            sender: transfer.from,
            receiver: transfer.to,
            amount: valueWithDecimals,
            token: symbol,
            externalID
        });
    }

    if (transaction?.networkToken) {
        const { tokenSymbol, valueWithDecimals } = transaction.networkToken;
        const externalID = await getExternalID(transaction.to);
        notifications.push({
            sender: transaction.from,
            receiver: transaction.to,
            amount: valueWithDecimals,
            token: tokenSymbol,
            externalID
        });
    }

    if (notifications.length > 0) {
        sendNotifications(notifications);
    }
}

//connect to DB and return externalID
async function getExternalID(address) {
    const entry = myDB.find(entry => entry.address.toLowerCase() === address.toLowerCase());
    return entry ? entry.externalID : null;
}

// Send notifications
async function sendNotifications(notifications) {
    for (const notification of notifications) {
        try {
            const data = {
                include_aliases: { external_id: [notification.externalID.toLowerCase()] },
                target_channel: 'push',
                isAnyWeb: true,
                contents: { en: `You've received ${notification.amount} ${notification.token}` },
                headings: { en: 'Core wallet' },
                name: 'Notification',
                app_id: process.env.APP_ID
            };
            console.log('data:', data);
            const response = await axios.post('https://onesignal.com/api/v1/notifications', data, {
                headers: {
                    Authorization: `Bearer ${process.env.ONESIGNAL_API_KEY}`,
                    'Content-Type': 'application/json'
                }
            });
            console.log('Notification sent:', response.data);
        } catch (error) {
            console.error('Error sending notification:', error);
            // Optionally, implement retry logic here
        }
    }
}

// Start the server
app.listen(port, () => {
    console.log(`App listening at http://localhost:${port}`);
});
```

You can now start your backend server by running:

```shell
node app.js
```

Send AVAX from another wallet to the wallet being monitored by the webhook and you should receive a notification with the amount of Avax received. You can try it with any other ERC20 token as well.

<img src="https://mintcdn.com/avalabs-47ea3976/0zR1yC86HIu3y3oi/images/onesignal-notification.png?fit=max&auto=format&n=0zR1yC86HIu3y3oi&q=85&s=f261c49d1063073f38ddea236294c085" data-og-width="1892" width="1892" data-og-height="1195" height="1195" data-path="images/onesignal-notification.png" data-optimize="true" data-opv="3" />

### Conclusion

In this tutorial, we've set up a frontend to connect to the Core wallet and enable push notifications using OneSignal. We've also implemented a backend to handle webhook events and send notifications based on the received data. By integrating the frontend with the backend, users can receive real-time notifications for blockchain events.

# Add addresses to EVM activity webhook (/docs/api-reference/webhook-api/webhooks/addAddressesToWebhook)

---
title: Add addresses to EVM activity webhook
full: true
_openapi:
  method: PATCH
  route: /v1/webhooks/{id}/addresses
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Add addresses to webhook. Only valid for EVM activity webhooks.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Add addresses to webhook. Only valid for EVM activity webhooks.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/webhooks/{id}/addresses","method":"patch"}]} webhooks={[]} hasHead={false} />

# Create a webhook (/docs/api-reference/webhook-api/webhooks/createWebhook)

---
title: Create a webhook
full: true
_openapi:
  method: POST
  route: /v1/webhooks
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Create a new webhook.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Create a new webhook.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/webhooks","method":"post"}]} webhooks={[]} hasHead={false} />

# Deactivate a webhook (/docs/api-reference/webhook-api/webhooks/deactivateWebhook)

---
title: Deactivate a webhook
full: true
_openapi:
  method: DELETE
  route: /v1/webhooks/{id}
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Deactivates a webhook by ID.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Deactivates a webhook by ID.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/webhooks/{id}","method":"delete"}]} webhooks={[]} hasHead={false} />

# Generate or rotate a shared secret (/docs/api-reference/webhook-api/webhooks/generateOrRotateSharedSecret)

---
title: Generate or rotate a shared secret
full: true
_openapi:
  method: POST
  route: /v1/webhooks:generateOrRotateSharedSecret
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Generates a new shared secret or rotate an existing one.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Generates a new shared secret or rotate an existing one.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/webhooks:generateOrRotateSharedSecret","method":"post"}]} webhooks={[]} hasHead={false} />

# List adresses by EVM activity webhooks (/docs/api-reference/webhook-api/webhooks/getAddressesFromWebhook)

---
title: List adresses by EVM activity webhooks
full: true
_openapi:
  method: GET
  route: /v1/webhooks/{id}/addresses
  toc: []
  structuredData:
    headings: []
    contents:
      - content: List adresses by webhook. Only valid for EVM activity webhooks.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

List adresses by webhook. Only valid for EVM activity webhooks.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/webhooks/{id}/addresses","method":"get"}]} webhooks={[]} hasHead={false} />

# Get a shared secret (/docs/api-reference/webhook-api/webhooks/getSharedSecret)

---
title: Get a shared secret
full: true
_openapi:
  method: GET
  route: /v1/webhooks:getSharedSecret
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Get a previously generated shared secret.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Get a previously generated shared secret.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/webhooks:getSharedSecret","method":"get"}]} webhooks={[]} hasHead={false} />

# Get a webhook by ID (/docs/api-reference/webhook-api/webhooks/getWebhook)

---
title: Get a webhook by ID
full: true
_openapi:
  method: GET
  route: /v1/webhooks/{id}
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Retrieves a webhook by ID.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Retrieves a webhook by ID.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/webhooks/{id}","method":"get"}]} webhooks={[]} hasHead={false} />

# List webhooks (/docs/api-reference/webhook-api/webhooks/listWebhooks)

---
title: List webhooks
full: true
_openapi:
  method: GET
  route: /v1/webhooks
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Lists webhooks for the user.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Lists webhooks for the user.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/webhooks","method":"get"}]} webhooks={[]} hasHead={false} />

# Remove addresses from EVM activity  webhook (/docs/api-reference/webhook-api/webhooks/removeAddressesFromWebhook)

---
title: Remove addresses from EVM activity  webhook
full: true
_openapi:
  method: DELETE
  route: /v1/webhooks/{id}/addresses
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Remove addresses from webhook. Only valid for EVM activity webhooks.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Remove addresses from webhook. Only valid for EVM activity webhooks.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/webhooks/{id}/addresses","method":"delete"}]} webhooks={[]} hasHead={false} />

# Update a webhook (/docs/api-reference/webhook-api/webhooks/updateWebhook)

---
title: Update a webhook
full: true
_openapi:
  method: PATCH
  route: /v1/webhooks/{id}
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Updates an existing webhook.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Updates an existing webhook.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/webhooks/{id}","method":"patch"}]} webhooks={[]} hasHead={false} />

# Get AVAX supply information (/docs/api-reference/data-api/avax-supply/getAvaxSupply)

---
title: Get AVAX supply information
full: true
_openapi:
  method: GET
  route: /v1/avax/supply
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Get AVAX supply information that includes  total supply, circulating
          supply, total p burned, total c burned,  total x burned, total staked,
          total locked, total rewards,  and last updated.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Get AVAX supply information that includes  total supply, circulating supply, total p burned, total c burned,  total x burned, total staked, total locked, total rewards,  and last updated.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/avax/supply","method":"get"}]} webhooks={[]} hasHead={false} />

# Get logs for requests made by client (/docs/api-reference/data-api/data-api-usage-metrics/getApiLogs)

---
title: Get logs for requests made by client
full: true
_openapi:
  method: GET
  route: /v1/apiLogs
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Gets logs for requests made by client over a specified time interval
          for a specific organization.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Gets logs for requests made by client over a specified time interval for a specific organization.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/apiLogs","method":"get"}]} webhooks={[]} hasHead={false} />

# Get usage metrics for the Data API (/docs/api-reference/data-api/data-api-usage-metrics/getApiUsageMetrics)

---
title: Get usage metrics for the Data API
full: true
_openapi:
  method: GET
  route: /v1/apiUsageMetrics
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Gets metrics for Data API usage over a specified time interval
          aggregated at the specified time-duration granularity.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Gets metrics for Data API usage over a specified time interval aggregated at the specified time-duration granularity.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/apiUsageMetrics","method":"get"}]} webhooks={[]} hasHead={false} />

# Get usage metrics for the Primary Network RPC (/docs/api-reference/data-api/data-api-usage-metrics/getPrimaryNetworkRpcUsageMetrics)

---
title: Get usage metrics for the Primary Network RPC
full: true
_openapi:
  method: GET
  route: /v1/primaryNetworkRpcUsageMetrics
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Gets metrics for public Primary Network RPC usage over  a specified
          time interval aggregated at the specified  time-duration granularity.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Gets metrics for public Primary Network RPC usage over  a specified time interval aggregated at the specified  time-duration granularity.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/primaryNetworkRpcUsageMetrics","method":"get"}]} webhooks={[]} hasHead={false} />

# Get usage metrics for the Subnet RPC (/docs/api-reference/data-api/data-api-usage-metrics/getSubnetRpcUsageMetrics)

---
title: Get usage metrics for the Subnet RPC
full: true
_openapi:
  method: GET
  route: /v1/subnetRpcUsageMetrics
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Gets metrics for public Subnet RPC usage over a specified time
          interval aggregated at the specified time-duration granularity.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Gets metrics for public Subnet RPC usage over a specified time interval aggregated at the specified time-duration granularity.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/subnetRpcUsageMetrics","method":"get"}]} webhooks={[]} hasHead={false} />

# Get native token balance (/docs/api-reference/data-api/evm-balances/getNativeBalance)

---
title: Get native token balance
full: true
_openapi:
  method: GET
  route: /v1/chains/{chainId}/addresses/{address}/balances:getNative
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Gets native token balance of a wallet address.


          Balance at a given block can be retrieved with the `blockNumber`
          parameter.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Gets native token balance of a wallet address.

Balance at a given block can be retrieved with the `blockNumber` parameter.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/chains/{chainId}/addresses/{address}/balances:getNative","method":"get"}]} webhooks={[]} hasHead={false} />

# List collectible (ERC-721/ERC-1155) balances (/docs/api-reference/data-api/evm-balances/listCollectibleBalances)

---
title: List collectible (ERC-721/ERC-1155) balances
full: true
_openapi:
  method: GET
  route: /v1/chains/{chainId}/addresses/{address}/balances:listCollectibles
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Lists ERC-721 and ERC-1155 token balances of a wallet address.


          Balance for a specific contract can be retrieved with the
          `contractAddress` parameter.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Lists ERC-721 and ERC-1155 token balances of a wallet address.

Balance for a specific contract can be retrieved with the `contractAddress` parameter.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/chains/{chainId}/addresses/{address}/balances:listCollectibles","method":"get"}]} webhooks={[]} hasHead={false} />

# List ERC-1155 balances (/docs/api-reference/data-api/evm-balances/listErc1155Balances)

---
title: List ERC-1155 balances
full: true
_openapi:
  method: GET
  route: /v1/chains/{chainId}/addresses/{address}/balances:listErc1155
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Lists ERC-1155 token balances of a wallet address.


          Balance at a given block can be retrieved with the `blockNumber`
          parameter.


          Balance for a specific contract can be retrieved with the
          `contractAddress` parameter.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Lists ERC-1155 token balances of a wallet address.

Balance at a given block can be retrieved with the `blockNumber` parameter.

Balance for a specific contract can be retrieved with the `contractAddress` parameter.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/chains/{chainId}/addresses/{address}/balances:listErc1155","method":"get"}]} webhooks={[]} hasHead={false} />

# List ERC-20 balances (/docs/api-reference/data-api/evm-balances/listErc20Balances)

---
title: List ERC-20 balances
full: true
_openapi:
  method: GET
  route: /v1/chains/{chainId}/addresses/{address}/balances:listErc20
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Lists ERC-20 token balances of a wallet address.


          Balance at a given block can be retrieved with the `blockNumber`
          parameter.


          Balance for specific contracts can be retrieved with the
          `contractAddresses` parameter.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Lists ERC-20 token balances of a wallet address.

Balance at a given block can be retrieved with the `blockNumber` parameter.

Balance for specific contracts can be retrieved with the `contractAddresses` parameter.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/chains/{chainId}/addresses/{address}/balances:listErc20","method":"get"}]} webhooks={[]} hasHead={false} />

# List ERC-721 balances (/docs/api-reference/data-api/evm-balances/listErc721Balances)

---
title: List ERC-721 balances
full: true
_openapi:
  method: GET
  route: /v1/chains/{chainId}/addresses/{address}/balances:listErc721
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Lists ERC-721 token balances of a wallet address.


          Balance for a specific contract can be retrieved with the
          `contractAddress` parameter.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Lists ERC-721 token balances of a wallet address.

Balance for a specific contract can be retrieved with the `contractAddress` parameter.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/chains/{chainId}/addresses/{address}/balances:listErc721","method":"get"}]} webhooks={[]} hasHead={false} />

# Get block (/docs/api-reference/data-api/evm-blocks/getBlock)

---
title: Get block
full: true
_openapi:
  method: GET
  route: /v1/chains/{chainId}/blocks/{blockId}
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Gets the details of an individual block on the EVM-compatible chain.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Gets the details of an individual block on the EVM-compatible chain.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/chains/{chainId}/blocks/{blockId}","method":"get"}]} webhooks={[]} hasHead={false} />

# List latest blocks (/docs/api-reference/data-api/evm-blocks/getLatestBlocks)

---
title: List latest blocks
full: true
_openapi:
  method: GET
  route: /v1/chains/{chainId}/blocks
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Lists the latest indexed blocks on the EVM-compatible chain sorted in
          descending order by block timestamp.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Lists the latest indexed blocks on the EVM-compatible chain sorted in descending order by block timestamp.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/chains/{chainId}/blocks","method":"get"}]} webhooks={[]} hasHead={false} />

# List latest blocks across all supported EVM chains (/docs/api-reference/data-api/evm-blocks/listLatestBlocksAllChains)

---
title: List latest blocks across all supported EVM chains
full: true
_openapi:
  method: GET
  route: /v1/blocks
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Lists the most recent blocks from all supported  EVM-compatible
          chains. The results can be filtered by network.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Lists the most recent blocks from all supported  EVM-compatible chains. The results can be filtered by network.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/blocks","method":"get"}]} webhooks={[]} hasHead={false} />

# Get chain information (/docs/api-reference/data-api/evm-chains/getChainInfo)

---
title: Get chain information
full: true
_openapi:
  method: GET
  route: /v1/chains/{chainId}
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Gets chain information for the EVM-compatible chain if supported by
          AvaCloud.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Gets chain information for the EVM-compatible chain if supported by AvaCloud.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/chains/{chainId}","method":"get"}]} webhooks={[]} hasHead={false} />

# List all chains associated with a given address (/docs/api-reference/data-api/evm-chains/listAddressChains)

---
title: List all chains associated with a given address
full: true
_openapi:
  method: GET
  route: /v1/address/{address}/chains
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Lists the chains where the specified address has  participated in
          transactions or ERC token transfers,  either as a sender or receiver.
          The data is refreshed every 15  minutes.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Lists the chains where the specified address has  participated in transactions or ERC token transfers,  either as a sender or receiver. The data is refreshed every 15  minutes.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/address/{address}/chains","method":"get"}]} webhooks={[]} hasHead={false} />

# List chains (/docs/api-reference/data-api/evm-chains/supportedChains)

---
title: List chains
full: true
_openapi:
  method: GET
  route: /v1/chains
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Lists the AvaCloud supported EVM-compatible chains. Filterable by
          network.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Lists the AvaCloud supported EVM-compatible chains. Filterable by network.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/chains","method":"get"}]} webhooks={[]} hasHead={false} />

# Get contract metadata (/docs/api-reference/data-api/evm-contracts/getContractMetadata)

---
title: Get contract metadata
full: true
_openapi:
  method: GET
  route: /v1/chains/{chainId}/addresses/{address}
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Gets metadata about the contract at the given address.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Gets metadata about the contract at the given address.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/chains/{chainId}/addresses/{address}","method":"get"}]} webhooks={[]} hasHead={false} />

# Get deployment transaction (/docs/api-reference/data-api/evm-transactions/getDeploymentTransaction)

---
title: Get deployment transaction
full: true
_openapi:
  method: GET
  route: /v1/chains/{chainId}/contracts/{address}/transactions:getDeployment
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          If the address is a smart contract, returns the transaction in which
          it was deployed.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

If the address is a smart contract, returns the transaction in which it was deployed.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/chains/{chainId}/contracts/{address}/transactions:getDeployment","method":"get"}]} webhooks={[]} hasHead={false} />

# Get transaction (/docs/api-reference/data-api/evm-transactions/getTransaction)

---
title: Get transaction
full: true
_openapi:
  method: GET
  route: /v1/chains/{chainId}/transactions/{txHash}
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Gets the details of a single transaction.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Gets the details of a single transaction.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/chains/{chainId}/transactions/{txHash}","method":"get"}]} webhooks={[]} hasHead={false} />

# List transactions for a block (/docs/api-reference/data-api/evm-transactions/getTransactionsForBlock)

---
title: List transactions for a block
full: true
_openapi:
  method: GET
  route: /v1/chains/{chainId}/blocks/{blockId}/transactions
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Lists the transactions that occured in a given block.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Lists the transactions that occured in a given block.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/chains/{chainId}/blocks/{blockId}/transactions","method":"get"}]} webhooks={[]} hasHead={false} />

# List deployed contracts (/docs/api-reference/data-api/evm-transactions/listContractDeployments)

---
title: List deployed contracts
full: true
_openapi:
  method: GET
  route: /v1/chains/{chainId}/contracts/{address}/deployments
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Lists all contracts deployed by the given address.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Lists all contracts deployed by the given address.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/chains/{chainId}/contracts/{address}/deployments","method":"get"}]} webhooks={[]} hasHead={false} />

# List ERC-1155 transfers (/docs/api-reference/data-api/evm-transactions/listErc1155Transactions)

---
title: List ERC-1155 transfers
full: true
_openapi:
  method: GET
  route: /v1/chains/{chainId}/addresses/{address}/transactions:listErc1155
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Lists ERC-1155 transfers for an address. Filterable by block range.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Lists ERC-1155 transfers for an address. Filterable by block range.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/chains/{chainId}/addresses/{address}/transactions:listErc1155","method":"get"}]} webhooks={[]} hasHead={false} />

# List ERC-20 transfers (/docs/api-reference/data-api/evm-transactions/listErc20Transactions)

---
title: List ERC-20 transfers
full: true
_openapi:
  method: GET
  route: /v1/chains/{chainId}/addresses/{address}/transactions:listErc20
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Lists ERC-20 transfers for an address. Filterable by block range.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Lists ERC-20 transfers for an address. Filterable by block range.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/chains/{chainId}/addresses/{address}/transactions:listErc20","method":"get"}]} webhooks={[]} hasHead={false} />

# List ERC-721 transfers (/docs/api-reference/data-api/evm-transactions/listErc721Transactions)

---
title: List ERC-721 transfers
full: true
_openapi:
  method: GET
  route: /v1/chains/{chainId}/addresses/{address}/transactions:listErc721
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Lists ERC-721 transfers for an address. Filterable by block range.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Lists ERC-721 transfers for an address. Filterable by block range.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/chains/{chainId}/addresses/{address}/transactions:listErc721","method":"get"}]} webhooks={[]} hasHead={false} />

# List internal transactions (/docs/api-reference/data-api/evm-transactions/listInternalTransactions)

---
title: List internal transactions
full: true
_openapi:
  method: GET
  route: /v1/chains/{chainId}/addresses/{address}/transactions:listInternals
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Returns a list of internal transactions for an address and chain.
          Filterable by block range.


          Note that the internal transactions list only contains `CALL` or
          `CALLCODE` transactions with a non-zero value and
          `CREATE`/`CREATE2`/`CREATE3` transactions. To get a complete list of
          internal transactions use the `debug_` prefixed RPC methods on an
          archive node.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Returns a list of internal transactions for an address and chain. Filterable by block range.

Note that the internal transactions list only contains `CALL` or `CALLCODE` transactions with a non-zero value and `CREATE`/`CREATE2`/`CREATE3` transactions. To get a complete list of internal transactions use the `debug_` prefixed RPC methods on an archive node.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/chains/{chainId}/addresses/{address}/transactions:listInternals","method":"get"}]} webhooks={[]} hasHead={false} />

# List latest transactions (/docs/api-reference/data-api/evm-transactions/listLatestTransactions)

---
title: List latest transactions
full: true
_openapi:
  method: GET
  route: /v1/chains/{chainId}/transactions
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Lists the latest transactions. Filterable by status.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Lists the latest transactions. Filterable by status.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/chains/{chainId}/transactions","method":"get"}]} webhooks={[]} hasHead={false} />

# List the latest transactions across all supported EVM chains (/docs/api-reference/data-api/evm-transactions/listLatestTransactionsAllChains)

---
title: List the latest transactions across all supported EVM chains
full: true
_openapi:
  method: GET
  route: /v1/transactions
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Lists the most recent transactions from all supported EVM-compatible 
          chains. The results can be filtered based on transaction status.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Lists the most recent transactions from all supported EVM-compatible  chains. The results can be filtered based on transaction status.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/transactions","method":"get"}]} webhooks={[]} hasHead={false} />

# List native transactions (/docs/api-reference/data-api/evm-transactions/listNativeTransactions)

---
title: List native transactions
full: true
_openapi:
  method: GET
  route: /v1/chains/{chainId}/addresses/{address}/transactions:listNative
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Lists native transactions for an address. Filterable by block range.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Lists native transactions for an address. Filterable by block range.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/chains/{chainId}/addresses/{address}/transactions:listNative","method":"get"}]} webhooks={[]} hasHead={false} />

# List transactions (/docs/api-reference/data-api/evm-transactions/listTransactions)

---
title: List transactions
full: true
_openapi:
  method: GET
  route: /v1/chains/{chainId}/addresses/{address}/transactions
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Returns a list of transactions where the given wallet address had an
          on-chain interaction for the given chain. The ERC-20 transfers,
          ERC-721 transfers, ERC-1155, and internal transactions returned are
          only those where the input address had an interaction. Specifically,
          those lists only inlcude entries where the input address was the
          sender (`from` field) or the receiver (`to` field) for the
          sub-transaction. Therefore the transactions returned from this list
          may not be complete representations of the on-chain data. For a
          complete view of a transaction use the
          `/chains/:chainId/transactions/:txHash` endpoint.


          Filterable by block ranges.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Returns a list of transactions where the given wallet address had an on-chain interaction for the given chain. The ERC-20 transfers, ERC-721 transfers, ERC-1155, and internal transactions returned are only those where the input address had an interaction. Specifically, those lists only inlcude entries where the input address was the sender (`from` field) or the receiver (`to` field) for the sub-transaction. Therefore the transactions returned from this list may not be complete representations of the on-chain data. For a complete view of a transaction use the `/chains/:chainId/transactions/:txHash` endpoint.

Filterable by block ranges.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/chains/{chainId}/addresses/{address}/transactions","method":"get"}]} webhooks={[]} hasHead={false} />

# List ERC transfers (/docs/api-reference/data-api/evm-transactions/listTransfers)

---
title: List ERC transfers
full: true
_openapi:
  method: GET
  route: /v1/chains/{chainId}/tokens/{address}/transfers
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Lists ERC transfers for an ERC-20, ERC-721, or ERC-1155 contract
          address.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Lists ERC transfers for an ERC-20, ERC-721, or ERC-1155 contract address.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/chains/{chainId}/tokens/{address}/transfers","method":"get"}]} webhooks={[]} hasHead={false} />

# Get the health of the service (/docs/api-reference/data-api/health-check/data-health-check)

---
title: Get the health of the service
full: true
_openapi:
  method: GET
  route: /v1/health-check
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Check the health of the service.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Check the health of the service.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/health-check","method":"get"}]} webhooks={[]} hasHead={false} />

# Get an ICM message (/docs/api-reference/data-api/interchain-messaging/getIcmMessage)

---
title: Get an ICM message
full: true
_openapi:
  method: GET
  route: /v1/icm/messages/{messageId}
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Gets an ICM message by teleporter message ID.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Gets an ICM message by teleporter message ID.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/icm/messages/{messageId}","method":"get"}]} webhooks={[]} hasHead={false} />

# List ICM messages (/docs/api-reference/data-api/interchain-messaging/listIcmMessages)

---
title: List ICM messages
full: true
_openapi:
  method: GET
  route: /v1/icm/messages
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Lists ICM messages. Ordered by timestamp in descending order.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Lists ICM messages. Ordered by timestamp in descending order.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/icm/messages","method":"get"}]} webhooks={[]} hasHead={false} />

# List ICM messages by address (/docs/api-reference/data-api/interchain-messaging/listIcmMessagesByAddress)

---
title: List ICM messages by address
full: true
_openapi:
  method: GET
  route: /v1/icm/addresses/{address}/messages
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Lists ICM messages by address. Ordered by timestamp in descending
          order.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Lists ICM messages by address. Ordered by timestamp in descending order.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/icm/addresses/{address}/messages","method":"get"}]} webhooks={[]} hasHead={false} />

# Get token details (/docs/api-reference/data-api/nfts/getTokenDetails)

---
title: Get token details
full: true
_openapi:
  method: GET
  route: /v1/chains/{chainId}/nfts/collections/{address}/tokens/{tokenId}
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Gets token details for a specific token of an NFT contract.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Gets token details for a specific token of an NFT contract.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/chains/{chainId}/nfts/collections/{address}/tokens/{tokenId}","method":"get"}]} webhooks={[]} hasHead={false} />

# List tokens (/docs/api-reference/data-api/nfts/listTokens)

---
title: List tokens
full: true
_openapi:
  method: GET
  route: /v1/chains/{chainId}/nfts/collections/{address}/tokens
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Lists tokens for an NFT contract.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Lists tokens for an NFT contract.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/chains/{chainId}/nfts/collections/{address}/tokens","method":"get"}]} webhooks={[]} hasHead={false} />

# Reindex NFT metadata (/docs/api-reference/data-api/nfts/reindexNft)

---
title: Reindex NFT metadata
full: true
_openapi:
  method: POST
  route: /v1/chains/{chainId}/nfts/collections/{address}/tokens/{tokenId}:reindex
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Triggers reindexing of token metadata for an NFT token. Reindexing can
          only be called once per hour for each NFT token.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Triggers reindexing of token metadata for an NFT token. Reindexing can only be called once per hour for each NFT token.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/chains/{chainId}/nfts/collections/{address}/tokens/{tokenId}:reindex","method":"post"}]} webhooks={[]} hasHead={false} />

# Get operation (/docs/api-reference/data-api/operations/getOperationResult)

---
title: Get operation
full: true
_openapi:
  method: GET
  route: /v1/operations/{operationId}
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Gets operation details for the given operation id.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Gets operation details for the given operation id.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/operations/{operationId}","method":"get"}]} webhooks={[]} hasHead={false} />

# Create transaction export operation (/docs/api-reference/data-api/operations/postTransactionExportJob)

---
title: Create transaction export operation
full: true
_openapi:
  method: POST
  route: /v1/operations/transactions:export
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Trigger a transaction export operation with given parameters.


          The transaction export operation runs asynchronously in the
          background. The status of the job can be retrieved from the
          `/v1/operations/:operationId` endpoint using the `operationId`
          returned from this endpoint.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Trigger a transaction export operation with given parameters.

The transaction export operation runs asynchronously in the background. The status of the job can be retrieved from the `/v1/operations/:operationId` endpoint using the `operationId` returned from this endpoint.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/operations/transactions:export","method":"post"}]} webhooks={[]} hasHead={false} />

# Get asset details (/docs/api-reference/data-api/primary-network/getAssetDetails)

---
title: Get asset details
full: true
_openapi:
  method: GET
  route: /v1/networks/{network}/blockchains/{blockchainId}/assets/{assetId}
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Gets asset details corresponding to the given asset id on the X-Chain.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Gets asset details corresponding to the given asset id on the X-Chain.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/networks/{network}/blockchains/{blockchainId}/assets/{assetId}","method":"get"}]} webhooks={[]} hasHead={false} />

# Get blockchain details by ID (/docs/api-reference/data-api/primary-network/getBlockchainById)

---
title: Get blockchain details by ID
full: true
_openapi:
  method: GET
  route: /v1/networks/{network}/blockchains/{blockchainId}
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Get details of the blockchain registered on the network.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Get details of the blockchain registered on the network.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/networks/{network}/blockchains/{blockchainId}","method":"get"}]} webhooks={[]} hasHead={false} />

# Get chain interactions for addresses (/docs/api-reference/data-api/primary-network/getChainIdsForAddresses)

---
title: Get chain interactions for addresses
full: true
_openapi:
  method: GET
  route: /v1/networks/{network}/addresses:listChainIds
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Returns Primary Network chains that each address has touched in the
          form of an address mapped array. If an address has had any on-chain
          interaction for a chain, that chain's chain id will be returned.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Returns Primary Network chains that each address has touched in the form of an address mapped array. If an address has had any on-chain interaction for a chain, that chain's chain id will be returned.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/networks/{network}/addresses:listChainIds","method":"get"}]} webhooks={[]} hasHead={false} />

# Get network details (/docs/api-reference/data-api/primary-network/getNetworkDetails)

---
title: Get network details
full: true
_openapi:
  method: GET
  route: /v1/networks/{network}
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Gets network details such as validator and delegator stats.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Gets network details such as validator and delegator stats.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/networks/{network}","method":"get"}]} webhooks={[]} hasHead={false} />

# Get single validator details (/docs/api-reference/data-api/primary-network/getSingleValidatorDetails)

---
title: Get single validator details
full: true
_openapi:
  method: GET
  route: /v1/networks/{network}/validators/{nodeId}
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          List validator details for a single validator.  Filterable by
          validation status.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

List validator details for a single validator.  Filterable by validation status.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/networks/{network}/validators/{nodeId}","method":"get"}]} webhooks={[]} hasHead={false} />

# Get Subnet details by ID (/docs/api-reference/data-api/primary-network/getSubnetById)

---
title: Get Subnet details by ID
full: true
_openapi:
  method: GET
  route: /v1/networks/{network}/subnets/{subnetId}
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Get details of the Subnet registered on the network.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Get details of the Subnet registered on the network.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/networks/{network}/subnets/{subnetId}","method":"get"}]} webhooks={[]} hasHead={false} />

# List blockchains (/docs/api-reference/data-api/primary-network/listBlockchains)

---
title: List blockchains
full: true
_openapi:
  method: GET
  route: /v1/networks/{network}/blockchains
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Lists all blockchains registered on the network.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Lists all blockchains registered on the network.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/networks/{network}/blockchains","method":"get"}]} webhooks={[]} hasHead={false} />

# List delegators (/docs/api-reference/data-api/primary-network/listDelegators)

---
title: List delegators
full: true
_openapi:
  method: GET
  route: /v1/networks/{network}/delegators
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Lists details for delegators.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Lists details for delegators.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/networks/{network}/delegators","method":"get"}]} webhooks={[]} hasHead={false} />

# List L1 validators (/docs/api-reference/data-api/primary-network/listL1Validators)

---
title: List L1 validators
full: true
_openapi:
  method: GET
  route: /v1/networks/{network}/l1Validators
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Lists details for L1 validators. By default, returns details for all
          active L1 validators. Filterable by validator node ids, subnet id, and
          validation id.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Lists details for L1 validators. By default, returns details for all active L1 validators. Filterable by validator node ids, subnet id, and validation id.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/networks/{network}/l1Validators","method":"get"}]} webhooks={[]} hasHead={false} />

# List subnets (/docs/api-reference/data-api/primary-network/listSubnets)

---
title: List subnets
full: true
_openapi:
  method: GET
  route: /v1/networks/{network}/subnets
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Lists all subnets registered on the network.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Lists all subnets registered on the network.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/networks/{network}/subnets","method":"get"}]} webhooks={[]} hasHead={false} />

# List validators (/docs/api-reference/data-api/primary-network/listValidators)

---
title: List validators
full: true
_openapi:
  method: GET
  route: /v1/networks/{network}/validators
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Lists details for validators. By default, returns details for all
          validators.  The nodeIds parameter supports substring matching.
          Filterable by validation status, delegation capacity, time remaining,
          fee percentage, uptime performance, and subnet id.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Lists details for validators. By default, returns details for all validators.  The nodeIds parameter supports substring matching. Filterable by validation status, delegation capacity, time remaining, fee percentage, uptime performance, and subnet id.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/networks/{network}/validators","method":"get"}]} webhooks={[]} hasHead={false} />

# Get balances (/docs/api-reference/data-api/primary-network-balances/getBalancesByAddresses)

---
title: Get balances
full: true
_openapi:
  method: GET
  route: /v1/networks/{network}/blockchains/{blockchainId}/balances
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Gets primary network balances for one of the Primary Network chains
          for the supplied addresses.


          C-Chain balances returned are only the shared atomic memory balance.
          For EVM balance, use the
          `/v1/chains/:chainId/addresses/:addressId/balances:getNative`
          endpoint.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Gets primary network balances for one of the Primary Network chains for the supplied addresses.

C-Chain balances returned are only the shared atomic memory balance. For EVM balance, use the `/v1/chains/:chainId/addresses/:addressId/balances:getNative` endpoint.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/networks/{network}/blockchains/{blockchainId}/balances","method":"get"}]} webhooks={[]} hasHead={false} />

# Get block (/docs/api-reference/data-api/primary-network-blocks/getBlockById)

---
title: Get block
full: true
_openapi:
  method: GET
  route: /v1/networks/{network}/blockchains/{blockchainId}/blocks/{blockId}
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Gets a block by block height or block hash on one of the Primary
          Network chains.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Gets a block by block height or block hash on one of the Primary Network chains.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/networks/{network}/blockchains/{blockchainId}/blocks/{blockId}","method":"get"}]} webhooks={[]} hasHead={false} />

# List latest blocks (/docs/api-reference/data-api/primary-network-blocks/listLatestPrimaryNetworkBlocks)

---
title: List latest blocks
full: true
_openapi:
  method: GET
  route: /v1/networks/{network}/blockchains/{blockchainId}/blocks
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Lists latest blocks on one of the Primary Network chains.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Lists latest blocks on one of the Primary Network chains.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/networks/{network}/blockchains/{blockchainId}/blocks","method":"get"}]} webhooks={[]} hasHead={false} />

# List blocks proposed by node (/docs/api-reference/data-api/primary-network-blocks/listPrimaryNetworkBlocksByNodeId)

---
title: List blocks proposed by node
full: true
_openapi:
  method: GET
  route: /v1/networks/{network}/blockchains/{blockchainId}/nodes/{nodeId}/blocks
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Lists the latest blocks proposed by a given NodeID on one of the
          Primary Network chains.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Lists the latest blocks proposed by a given NodeID on one of the Primary Network chains.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/networks/{network}/blockchains/{blockchainId}/nodes/{nodeId}/blocks","method":"get"}]} webhooks={[]} hasHead={false} />

# List historical rewards (/docs/api-reference/data-api/primary-network-rewards/listHistoricalPrimaryNetworkRewards)

---
title: List historical rewards
full: true
_openapi:
  method: GET
  route: /v1/networks/{network}/rewards
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Lists historical rewards on the Primary Network for the supplied
          addresses.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Lists historical rewards on the Primary Network for the supplied addresses.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/networks/{network}/rewards","method":"get"}]} webhooks={[]} hasHead={false} />

# List pending rewards (/docs/api-reference/data-api/primary-network-rewards/listPendingPrimaryNetworkRewards)

---
title: List pending rewards
full: true
_openapi:
  method: GET
  route: /v1/networks/{network}/rewards:listPending
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Lists pending rewards on the Primary Network for the supplied
          addresses.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Lists pending rewards on the Primary Network for the supplied addresses.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/networks/{network}/rewards:listPending","method":"get"}]} webhooks={[]} hasHead={false} />

# Get transaction (/docs/api-reference/data-api/primary-network-transactions/getTxByHash)

---
title: Get transaction
full: true
_openapi:
  method: GET
  route: /v1/networks/{network}/blockchains/{blockchainId}/transactions/{txHash}
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Gets the details of a single transaction on one of the Primary Network
          chains.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Gets the details of a single transaction on one of the Primary Network chains.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/networks/{network}/blockchains/{blockchainId}/transactions/{txHash}","method":"get"}]} webhooks={[]} hasHead={false} />

# List staking transactions (/docs/api-reference/data-api/primary-network-transactions/listActivePrimaryNetworkStakingTransactions)

---
title: List staking transactions
full: true
_openapi:
  method: GET
  route: /v1/networks/{network}/blockchains/{blockchainId}/transactions:listStaking
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Lists active staking transactions on the P-Chain for the supplied
          addresses.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Lists active staking transactions on the P-Chain for the supplied addresses.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/networks/{network}/blockchains/{blockchainId}/transactions:listStaking","method":"get"}]} webhooks={[]} hasHead={false} />

# List asset transactions (/docs/api-reference/data-api/primary-network-transactions/listAssetTransactions)

---
title: List asset transactions
full: true
_openapi:
  method: GET
  route: >-
    /v1/networks/{network}/blockchains/{blockchainId}/assets/{assetId}/transactions
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Lists asset transactions corresponding to the given asset id on the
          X-Chain.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Lists asset transactions corresponding to the given asset id on the X-Chain.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/networks/{network}/blockchains/{blockchainId}/assets/{assetId}/transactions","method":"get"}]} webhooks={[]} hasHead={false} />

# List latest transactions (/docs/api-reference/data-api/primary-network-transactions/listLatestPrimaryNetworkTransactions)

---
title: List latest transactions
full: true
_openapi:
  method: GET
  route: /v1/networks/{network}/blockchains/{blockchainId}/transactions
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Lists the latest transactions on one of the Primary Network chains.


          Transactions are filterable by addresses, txTypes, and timestamps.
          When querying for latest transactions without an address parameter,
          filtering by txTypes and timestamps is not supported. An address
          filter must be provided to utilize txTypes and timestamp filters.


          For P-Chain, you can fetch all L1 validators related transactions like
          ConvertSubnetToL1Tx, IncreaseL1ValidatorBalanceTx etc. using the
          unique L1 validation ID. These transactions are further filterable by
          txTypes and timestamps as well.


          Given that each transaction may return a large number of UTXO objects,
          bounded only by the maximum transaction size, the query may return
          less transactions than the provided page size. The result will contain
          less results than the page size if the number of utxos contained in
          the resulting transactions reach a performance threshold.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Lists the latest transactions on one of the Primary Network chains.

Transactions are filterable by addresses, txTypes, and timestamps. When querying for latest transactions without an address parameter, filtering by txTypes and timestamps is not supported. An address filter must be provided to utilize txTypes and timestamp filters.

For P-Chain, you can fetch all L1 validators related transactions like ConvertSubnetToL1Tx, IncreaseL1ValidatorBalanceTx etc. using the unique L1 validation ID. These transactions are further filterable by txTypes and timestamps as well.

Given that each transaction may return a large number of UTXO objects, bounded only by the maximum transaction size, the query may return less transactions than the provided page size. The result will contain less results than the page size if the number of utxos contained in the resulting transactions reach a performance threshold.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/networks/{network}/blockchains/{blockchainId}/transactions","method":"get"}]} webhooks={[]} hasHead={false} />

# List UTXOs (/docs/api-reference/data-api/primary-network-utxos/getUtxosByAddresses)

---
title: List UTXOs
full: true
_openapi:
  method: GET
  route: /v1/networks/{network}/blockchains/{blockchainId}/utxos
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Lists UTXOs on one of the Primary Network chains for the supplied
          addresses.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Lists UTXOs on one of the Primary Network chains for the supplied addresses.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/networks/{network}/blockchains/{blockchainId}/utxos","method":"get"}]} webhooks={[]} hasHead={false} />

# List UTXOs v2 - Supports querying for more addresses (/docs/api-reference/data-api/primary-network-utxos/getUtxosByAddressesV2)

---
title: List UTXOs v2 - Supports querying for more addresses
full: true
_openapi:
  method: POST
  route: /v1/networks/{network}/blockchains/{blockchainId}/utxos
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Lists UTXOs on one of the Primary Network chains for the supplied
          addresses. This v2 route supports increased page size and address
          limit.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Lists UTXOs on one of the Primary Network chains for the supplied addresses. This v2 route supports increased page size and address limit.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/networks/{network}/blockchains/{blockchainId}/utxos","method":"post"}]} webhooks={[]} hasHead={false} />

# Get vertex (/docs/api-reference/data-api/primary-network-vertices/getVertexByHash)

---
title: Get vertex
full: true
_openapi:
  method: GET
  route: /v1/networks/{network}/blockchains/{blockchainId}/vertices/{vertexHash}
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Gets a single vertex on the X-Chain.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Gets a single vertex on the X-Chain.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/networks/{network}/blockchains/{blockchainId}/vertices/{vertexHash}","method":"get"}]} webhooks={[]} hasHead={false} />

# List vertices by height (/docs/api-reference/data-api/primary-network-vertices/getVertexByHeight)

---
title: List vertices by height
full: true
_openapi:
  method: GET
  route: /v1/networks/{network}/blockchains/{blockchainId}/vertices:listByHeight
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Lists vertices at the given vertex height on the X-Chain.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Lists vertices at the given vertex height on the X-Chain.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/networks/{network}/blockchains/{blockchainId}/vertices:listByHeight","method":"get"}]} webhooks={[]} hasHead={false} />

# List vertices (/docs/api-reference/data-api/primary-network-vertices/listLatestXChainVertices)

---
title: List vertices
full: true
_openapi:
  method: GET
  route: /v1/networks/{network}/blockchains/{blockchainId}/vertices
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Lists latest vertices on the X-Chain.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Lists latest vertices on the X-Chain.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/networks/{network}/blockchains/{blockchainId}/vertices","method":"get"}]} webhooks={[]} hasHead={false} />

# Aggregate Signatures (/docs/api-reference/data-api/signature-aggregator/aggregateSignatures)

---
title: Aggregate Signatures
full: true
_openapi:
  method: POST
  route: /v1/signatureAggregator/{network}/aggregateSignatures
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Aggregates Signatures for a Warp message from Subnet validators.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Aggregates Signatures for a Warp message from Subnet validators.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/signatureAggregator/{network}/aggregateSignatures","method":"post"}]} webhooks={[]} hasHead={false} />

# Get Aggregated Signatures (/docs/api-reference/data-api/signature-aggregator/getAggregatedSignatures)

---
title: Get Aggregated Signatures
full: true
_openapi:
  method: GET
  route: /v1/signatureAggregator/{network}/aggregateSignatures/{txHash}
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Get Aggregated Signatures for a P-Chain L1 related Warp Message.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Get Aggregated Signatures for a P-Chain L1 related Warp Message.

<APIPage document={"./public/openapi/glacier.json"} operations={[{"path":"/v1/signatureAggregator/{network}/aggregateSignatures/{txHash}","method":"get"}]} webhooks={[]} hasHead={false} />

# ChainDropdown (/docs/builderkit/components/chains/chain-dropdown)

---
title: ChainDropdown
description: "A dropdown component for selecting Avalanche chains with visual chain information."
---

# ChainDropdown

The ChainDropdown component provides a styled dropdown menu for selecting between different Avalanche chains.

## Usage

```tsx
import { ChainDropdown } from '@avalabs/builderkit';

// Basic usage
<ChainDropdown 
  selected={43114}
  list={[43114, 43113]}
  onSelectionChanged={(chainId) => console.log('Selected chain:', chainId)}
/>

// With custom styling
<ChainDropdown 
  selected={43114}
  list={[43114, 43113]}
  onSelectionChanged={handleChainChange}
  className="w-64"
/>
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `selected` | `number` | - | Currently selected chain ID |
| `list` | `number[]` | - | Array of available chain IDs |
| `onSelectionChanged` | `(chain_id: number) => void` | - | Callback when selection changes |
| `className` | `string` | - | Additional CSS classes |

## Features

- Displays chain information using ChainRow component
- Maintains selected state internally
- Styled dropdown with Tailwind CSS
- Uses common Select components for consistent UI
- Automatic chain information lookup

## Examples

### Basic Chain Selection
```tsx
<ChainDropdown 
  selected={43114}
  list={[43114, 43113]}
  onSelectionChanged={handleChainChange}
/>
```

### With Network Switching
```tsx
<ChainDropdown 
  selected={currentChainId}
  list={supportedChainIds}
  onSelectionChanged={async (chainId) => {
    try {
      await switchNetwork(chainId);
    } catch (error) {
      console.error('Failed to switch network:', error);
    }
  }}
/>
```

### Custom Styling
```tsx
<ChainDropdown 
  selected={43114}
  list={[43114, 43113]}
  onSelectionChanged={handleChainChange}
  className="w-full max-w-sm bg-gray-100"
/>
```

### With Chain Filtering
```tsx
<ChainDropdown 
  selected={43114}
  list={chains.filter(id => supportedChains.includes(id))}
  onSelectionChanged={handleChainChange}
/>
```

## Component Structure

The dropdown consists of:
1. **Trigger**: Shows currently selected chain
2. **Content**: List of available chains
3. **Items**: Individual chain rows with icons and names

## Visual States

1. **Default**: Shows selected chain
2. **Open**: Displays list of available chains
3. **Hover**: Highlights chain under cursor
4. **Selected**: Indicates current selection

## Chain Information

The component uses the `useChains` hook to fetch chain information, which includes:
- Chain ID
- Chain name
- Chain icon (via ChainRow component)

## Styling

Default styling includes:
- Primary background color
- Contrasting text color
- Rounded corners
- Proper padding and spacing
- Hover and focus states 

# ChainIcon (/docs/builderkit/components/chains/chain-icon)

---
title: ChainIcon
description: "A component for displaying chain logos based on chain ID."
---

# ChainIcon

The ChainIcon component displays chain logos for Avalanche networks using a standardized path structure.

## Usage

```tsx
import { ChainIcon } from '@avalabs/builderkit';

// Basic usage
<ChainIcon chain_id={43114} />

// With custom styling
<ChainIcon 
  chain_id={43114}
  className="w-8 h-8 rounded-full"
/>
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `chain_id` | `number` | - | Chain ID to display logo for |
| `className` | `string` | - | Additional CSS classes |

## Features

- Displays chain logos from a standardized path structure
- Uses common Icon component for consistent display
- Supports custom styling through className
- Simple and lightweight implementation

## Examples

### Basic Chain Icon
```tsx
<ChainIcon chain_id={43114} />
```

### Custom Size
```tsx
<ChainIcon 
  chain_id={43114}
  className="w-12 h-12"
/>
```

### In a List
```tsx
<div className="flex gap-2">
  <ChainIcon chain_id={43114} />
  <ChainIcon chain_id={43113} />
</div>
```

### With Border
```tsx
<ChainIcon 
  chain_id={43114}
  className="border-2 border-gray-200 rounded-full"
/>
```

## Asset Requirements

The component expects chain logo images to be available at:
```
/chains/logo/{chain_id}.png
```

For example:
```
/chains/logo/43114.png  // Avalanche C-Chain
/chains/logo/43113.png  // Fuji Testnet
```

# ChainRow (/docs/builderkit/components/chains/chain-row)

---
title: ChainRow
description: "A component for displaying chain information in a row layout with icon and name."
---

# ChainRow

The ChainRow component displays chain information in a horizontal layout, combining a chain icon with its name.

## Usage

```tsx
import { ChainRow } from '@avalabs/builderkit';

// Basic usage
<ChainRow 
  chain_id={43114}
  name="Avalanche C-Chain"
/>

// With custom styling
<ChainRow 
  chain_id={43114}
  name="Avalanche C-Chain"
  className="bg-gray-100 p-2 rounded-lg"
/>
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `chain_id` | `number` | - | Chain ID |
| `name` | `string` | - | Chain name |
| `className` | `string` | - | Additional CSS classes |

## Features

- Combines ChainIcon with chain name
- Horizontal layout with proper spacing
- Flexible styling through className
- Simple and lightweight implementation
- Consistent alignment and spacing

## Examples

### Basic Chain Display
```tsx
<ChainRow 
  chain_id={43114}
  name="Avalanche C-Chain"
/>
```

### In a List
```tsx
<div className="flex flex-col gap-2">
  <ChainRow 
    chain_id={43114}
    name="Avalanche C-Chain"
  />
  <ChainRow 
    chain_id={43113}
    name="Fuji Testnet"
  />
</div>
```

### Interactive Row
```tsx
<ChainRow 
  chain_id={43114}
  name="Avalanche C-Chain"
  className="hover:bg-gray-100 cursor-pointer"
/>
```

### With Custom Styling
```tsx
<ChainRow 
  chain_id={43114}
  name="Avalanche C-Chain"
  className="border border-gray-200 rounded-lg p-3 shadow-xs"
/>
```

## Layout Structure

The component uses a flex layout with:
- ChainIcon on the left
- Chain name on the right
- Gap between icon and name
- Center alignment of items

# Collectible (/docs/builderkit/components/collectibles/collectible)

---
title: Collectible
description: "A component for displaying NFT collectibles with metadata and image support."
---

# Collectible

The Collectible component displays NFT collectibles with automatic metadata resolution and image display.

## Usage

```tsx
import { Collectible } from '@avalabs/builderkit';

// Basic usage
<Collectible 
  chain_id={43114}
  address="0x1234567890123456789012345678901234567890"
  token_id={1}
/>

// With custom styling
<Collectible 
  chain_id={43114}
  address="0x1234567890123456789012345678901234567890"
  token_id={1}
  className="border-2 rounded-xl"
/>
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `chain_id` | `number` | - | Chain ID where the NFT exists |
| `address` | `string` | - | NFT contract address |
| `token_id` | `number` | - | Token ID of the NFT |
| `className` | `string` | - | Additional CSS classes |

## Features

- Automatic metadata resolution from IPFS
- Displays NFT image and name
- Shows token ID
- Supports ERC721 standard
- Responsive layout with fixed dimensions
- Loading state handling

## Examples

### Basic NFT Display
```tsx
<Collectible 
  chain_id={43114}
  address="0x1234567890123456789012345678901234567890"
  token_id={1}
/>
```

### In a Grid Layout
```tsx
<div className="grid grid-cols-3 gap-4">
  {nfts.map(nft => (
    <Collectible 
      key={nft.token_id}
      chain_id={nft.chain_id}
      address={nft.address}
      token_id={nft.token_id}
    />
  ))}
</div>
```

### With Custom Styling
```tsx
<Collectible 
  chain_id={43114}
  address="0x1234567890123456789012345678901234567890"
  token_id={1}
  className="shadow-lg hover:shadow-xl transition-shadow"
/>
```

## Component Structure

1. **Container**
   - Fixed width of 120px
   - Rounded corners
   - Border
   - Overflow hidden

2. **Image**
   - Fixed dimensions (120x120)
   - Maintains aspect ratio
   - Centered display

3. **Info Section**
   - White background
   - Token ID display
   - NFT name
   - Proper padding

## Metadata Resolution

The component automatically:
1. Fetches token URI from the contract
2. Resolves IPFS metadata
3. Extracts image URL and name
4. Handles IPFS gateway resolution

# Button (/docs/builderkit/components/control/button)

---
title: Button
description: "A versatile button component that supports multiple states and actions."
---

# Button

The Button component is a versatile control that supports multiple states and actions.

## Usage

```tsx
import { Button } from '@avalabs/builderkit';

// Basic usage
<Button 
  label="Click me"
  action={() => console.log('Button clicked')}
/>

// With loading state
<Button 
  label="Processing..."
  action={() => {}}
  status="loading"
/>

// Disabled state
<Button 
  label="Unavailable"
  action={() => {}}
  status="disabled"
/>
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `label` | `string` | - | Text to display on the button |
| `action` | `() => void` | - | Function to execute when button is clicked |
| `status` | `'idle' \| 'loading' \| 'disabled'` | `'idle'` | Current state of the button |
| `className` | `string` | - | Additional CSS classes |

# ConnectButton (/docs/builderkit/components/control/connect-button)

---
title: ConnectButton
description: "A button component that handles wallet connection functionality."
---

# ConnectButton

The ConnectButton component provides wallet connection functionality with built-in state management.

## Usage

```tsx
import { ConnectButton } from '@avalabs/builderkit';

// Basic usage
<ConnectButton />

// With wallet display
<ConnectButton 
  showConnectedWallet={true}
  checkWrongNetwork={true}
/>
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `showConnectedWallet` | `boolean` | `false` | Show connected wallet address |
| `checkWrongNetwork` | `boolean` | `false` | Enable network validation |
| `className` | `string` | - | Additional CSS classes |

# Address (/docs/builderkit/components/identity/address)

---
title: Address
description: "A component for displaying Ethereum addresses with optional abbreviation."
---

# Address

The Address component displays Ethereum addresses with optional abbreviation and validation.

## Usage

```tsx
import { Address } from '@avalabs/builderkit';

// Basic usage
<Address address="0x1234567890123456789012345678901234567890" />

// With abbreviation
<Address 
  address="0x1234567890123456789012345678901234567890"
  abbreviate={true}
/>

// Using context (inside Identity provider)
<Address abbreviate={true} />
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `address` | `string` | - | The Ethereum address to display (optional if used within Identity context) |
| `abbreviate` | `boolean` | `false` | Whether to show abbreviated address (e.g., 0x1234...5678) |

## Features

- Validates input address using `ethers.isAddress`
- Supports address abbreviation (0x1234...5678)
- Can use address from Identity context if not provided directly
- Throws error for invalid addresses

## Examples

### Basic Display
```tsx
<Address address="0x1234567890123456789012345678901234567890" />
// Output: 0x1234567890123456789012345678901234567890
```

### Abbreviated Display
```tsx
<Address 
  address="0x1234567890123456789012345678901234567890"
  abbreviate={true}
/>
// Output: 0x1234...5678
```

### With Identity Context
```tsx
<Identity address="0x1234567890123456789012345678901234567890">
  <Address abbreviate={true} />
</Identity>
```

## Error Handling

The component will throw an error if:
- No address is provided (either via props or context)
- The provided address is not a valid Ethereum address 

# Domain (/docs/builderkit/components/identity/domain)

---
title: Domain
description: "A component for resolving and displaying Avalanche domain names for Ethereum addresses."
---

# Domain

The Domain component resolves and displays Avalanche domain names for Ethereum addresses, with fallback to abbreviated addresses.

## Usage

```tsx
import { Domain } from '@avalabs/builderkit';

// Basic usage
<Domain address="0x1234567890123456789012345678901234567890" />

// With address fallback
<Domain 
  address="0x1234567890123456789012345678901234567890"
  showAddressIfNotAvailable={true}
/>

// Using context (inside Identity provider)
<Domain showAddressIfNotAvailable={true} />
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `address` | `string` | - | The Ethereum address to resolve domain for (optional if used within Identity context) |
| `showAddressIfNotAvailable` | `boolean` | `false` | Show abbreviated address if no domain is found |

## Features

- Resolves Avalanche domain names using `useAvaxDomain` hook
- Shows loading indicator while resolving
- Optional fallback to abbreviated address display
- Can use address from Identity context if not provided directly
- Validates input addresses

## Examples

### Basic Domain Display
```tsx
<Domain address="0x1234567890123456789012345678901234567890" />
// Output: "mydomain.avax" (if resolved)
// Output: null (if no domain found)
```

### With Address Fallback
```tsx
<Domain 
  address="0x1234567890123456789012345678901234567890"
  showAddressIfNotAvailable={true}
/>
// Output: "mydomain.avax" (if resolved)
// Output: "0x1234...5678" (if no domain found)
```

### With Identity Context
```tsx
<Identity address="0x1234567890123456789012345678901234567890">
  <Domain showAddressIfNotAvailable={true} />
</Identity>
```

## States

1. **Loading**: Shows a loading indicator while resolving the domain
2. **Resolved**: Displays the resolved domain name
3. **Not Found**: 
   - Shows nothing if `showAddressIfNotAvailable` is false
   - Shows abbreviated address if `showAddressIfNotAvailable` is true

## Error Handling

The component will throw an error if:
- No address is provided (either via props or context)
- The provided address is not a valid Ethereum address 

# Identity (/docs/builderkit/components/identity/identity)

---
title: Identity
description: "A context provider component for sharing address information across identity-related components."
---

# Identity

The Identity component provides a context for sharing address information across Address and Domain components.

## Usage

```tsx
import { Identity, Address, Domain } from '@avalabs/builderkit';

// Basic usage
<Identity address="0x1234567890123456789012345678901234567890">
  <Domain showAddressIfNotAvailable={true} />
  <Address abbreviate={true} />
</Identity>
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `address` | `string` | - | The Ethereum address to provide in context |
| `children` | `ReactNode` | - | Child components that will have access to the address context |

## Features

- Provides address context to child components
- Automatically renders a Domain component with address fallback
- Validates input address
- Enables consistent address display across components

## Examples

### Basic Context Provider
```tsx
<Identity address="0x1234567890123456789012345678901234567890">
  <div>
    <p>Domain: <Domain /></p>
    <p>Address: <Address abbreviate={true} /></p>
  </div>
</Identity>
```

### Custom Layout
```tsx
<Identity address="0x1234567890123456789012345678901234567890">
  <div className="flex items-center gap-2">
    <Domain showAddressIfNotAvailable={true} />
    <span>|</span>
    <Address abbreviate={true} />
  </div>
</Identity>
```

## Context Usage

The Identity component provides a context that can be consumed by other components using the `useIdentityContext` hook:

```tsx
import { useIdentityContext } from '@avalabs/builderkit';

function MyComponent() {
  const { address } = useIdentityContext();
  return <div>Current address: {address}</div>;
}
```

## Error Handling

The component will throw an error if:
- No address is provided
- The provided address is invalid 

# AddressInput (/docs/builderkit/components/input/address-input)

---
title: AddressInput
description: "An input component for Ethereum addresses with built-in validation."
---

# AddressInput

The AddressInput component provides a specialized input field for Ethereum addresses with real-time validation.

## Usage

```tsx
import { AddressInput } from '@avalabs/builderkit';
import { Wallet } from 'lucide-react';

// Basic usage
<AddressInput 
  placeholder="Enter address..."
  onChange={(address) => console.log('Valid address:', address)}
/>

// With icon
<AddressInput 
  placeholder="Recipient address"
  icon={<Wallet className="w-4 h-4" />}
  onChange={handleAddressChange}
/>
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `placeholder` | `string` | - | Placeholder text |
| `value` | `string` | `""` | Controlled input value |
| `disabled` | `boolean` | `false` | Whether the input is disabled |
| `icon` | `ReactNode` | - | Optional icon element |
| `onChange` | `(address: string) => void` | - | Called with valid address or empty string |
| `className` | `string` | - | Additional CSS classes |

## Features

- Real-time Ethereum address validation using `viem`
- Visual feedback for invalid addresses
- Only emits valid addresses through onChange
- Optional icon support
- Controlled value management
- Error state styling

## Examples

### Basic Address Input
```tsx
<AddressInput 
  placeholder="Enter Ethereum address"
  onChange={setRecipientAddress}
/>
```

### With Error Handling
```tsx
<AddressInput 
  placeholder="Recipient address"
  onChange={(address) => {
    if (address) {
      handleValidAddress(address);
    } else {
      setError('Please enter a valid address');
    }
  }}
/>
```

### With Custom Styling
```tsx
<AddressInput 
  placeholder="Enter address"
  icon={<Wallet />}
  className="bg-gray-100 rounded-lg"
  onChange={handleAddress}
/>
```

### In a Form
```tsx
<form onSubmit={handleSubmit}>
  <AddressInput 
    placeholder="Recipient"
    value={recipientAddress}
    onChange={setRecipientAddress}
    className="mb-4"
  />
  <button 
    type="submit" 
    disabled={!recipientAddress}
  >
    Send
  </button>
</form>
```

## Validation States

1. **Initial**: No validation indicator
2. **Valid**: No visual feedback (clean state)
3. **Invalid**: Red ring around input
4. **Disabled**: Grayed out appearance

# AmountInput (/docs/builderkit/components/input/amount-input)

---
title: AmountInput
description: "A specialized input component for handling numeric amounts with proper formatting."
---

# AmountInput

The AmountInput component provides a specialized input field for handling numeric amounts with automatic formatting and validation.

## Usage

```tsx
import { AmountInput } from '@avalabs/builderkit';
import { DollarSign } from 'lucide-react';

// Basic usage
<AmountInput 
  type="text"
  placeholder="Enter amount..."
  onChange={(value) => console.log('Amount:', value)}
/>

// With currency icon
<AmountInput 
  type="text"
  placeholder="0.00"
  icon={<DollarSign className="w-4 h-4" />}
  onChange={handleAmountChange}
/>
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `type` | `string` | - | Input type (usually "text") |
| `placeholder` | `string` | - | Placeholder text |
| `value` | `string` | `""` | Controlled input value |
| `disabled` | `boolean` | `false` | Whether the input is disabled |
| `icon` | `ReactNode` | - | Optional icon element |
| `onChange` | `(value: string) => void` | - | Called with formatted amount |
| `className` | `string` | - | Additional CSS classes |

## Features

- Automatic number formatting
- Prevents invalid number inputs
- Handles decimal points appropriately
- Optional icon support
- Controlled value management
- Background color inheritance

## Examples

### Basic Amount Input
```tsx
<AmountInput 
  type="text"
  placeholder="0.00"
  onChange={setAmount}
/>
```

### With Maximum Value
```tsx
<AmountInput 
  type="text"
  placeholder="Enter amount"
  value={amount}
  onChange={(value) => {
    if (parseFloat(value) <= maxAmount) {
      setAmount(value);
    }
  }}
/>
```

### With Currency Symbol
```tsx
<AmountInput 
  type="text"
  placeholder="0.00"
  icon={<span className="text-gray-400">$</span>}
  onChange={handleAmount}
  className="text-right"
/>
```

### In a Form
```tsx
<form onSubmit={handleSubmit}>
  <AmountInput 
    type="text"
    placeholder="Amount to send"
    value={amount}
    onChange={setAmount}
    className="mb-4"
  />
  <button 
    type="submit" 
    disabled={!amount || parseFloat(amount) <= 0}
  >
    Send
  </button>
</form>
```

## Number Formatting

The component uses `parseNumberInput` utility to:
- Allow only numeric input
- Handle decimal points
- Remove leading zeros
- Maintain proper number format

# Input (/docs/builderkit/components/input/input)

---
title: Input
description: "A base input component with icon support and controlled value management."
---

# Input

The Input component provides a base text input with support for icons, controlled values, and custom styling.

## Usage

```tsx
import { Input } from '@avalabs/builderkit';
import { Search } from 'lucide-react';

// Basic usage
<Input 
  type="text"
  placeholder="Enter text..."
  onChange={(value) => console.log('Input value:', value)}
/>

// With icon
<Input 
  type="text"
  placeholder="Search..."
  icon={<Search className="w-4 h-4" />}
  onChange={handleSearch}
/>

// Disabled state
<Input 
  type="text"
  placeholder="Disabled input"
  disabled={true}
/>
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `type` | `string` | - | Input type (e.g., 'text', 'number') |
| `placeholder` | `string` | - | Placeholder text |
| `value` | `any` | `""` | Controlled input value |
| `disabled` | `boolean` | `false` | Whether the input is disabled |
| `icon` | `ReactNode` | - | Optional icon element |
| `onChange` | `(value: any) => void` | - | Value change callback |
| `className` | `string` | - | Additional CSS classes |

## Features

- Controlled input value management
- Optional icon support
- Disabled state handling
- Flexible styling with Tailwind CSS
- Consistent padding and spacing
- Background inheritance for seamless integration

## Examples

### Text Input
```tsx
<Input 
  type="text"
  placeholder="Enter your name"
  onChange={handleNameChange}
  className="border rounded-lg"
/>
```

### Search Input
```tsx
<Input 
  type="text"
  placeholder="Search items..."
  icon={<Search className="text-gray-400" />}
  onChange={handleSearch}
  className="bg-gray-100"
/>
```

### Number Input
```tsx
<Input 
  type="number"
  placeholder="Enter amount"
  value={amount}
  onChange={handleAmountChange}
  className="text-right"
/>
```

### With Validation
```tsx
<Input 
  type="email"
  placeholder="Enter email"
  value={email}
  onChange={handleEmailChange}
  className={isValidEmail ? 'border-green-500' : 'border-red-500'}
/>
```

## Layout Structure

The component uses a flex container with:
- Optional icon on the left
- Full-width input field
- Consistent padding and gap
- Background color inheritance

# MultiChainTokenInput (/docs/builderkit/components/input/multi-chain-token-input)

---
title: MultiChainTokenInput
description: "A token selection component that supports tokens across multiple chains."
---

# MultiChainTokenInput

The MultiChainTokenInput component provides a token selection interface that allows users to select tokens from different chains.

## Usage

```tsx
import { MultiChainTokenInput } from '@avalabs/builderkit';

// Basic usage
<MultiChainTokenInput 
  selected={{ 
    address: "0x1234...", 
    chain_id: 43114,
    symbol: "AVAX" 
  }}
  list={multiChainTokenList}
  onSelectionChanged={(token) => console.log('Selected token:', token)}
  showBalances={true}
/>
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `selected` | `{ address: string, chain_id: number } & Partial<TokenItem>` | - | Currently selected token with chain |
| `list` | `TokenItem[]` | - | Array of tokens across all chains |
| `onSelectionChanged` | `(token: TokenItem) => void` | - | Called when token selection changes |
| `showBalances` | `boolean` | - | Whether to show token balances |
| `className` | `string` | - | Additional CSS classes |

## Features

- Token selection across multiple chains
- Chain selection interface
- Displays token with chain icon
- Shows token balances (optional)
- Searchable token list per chain
- Responsive dialog design

## Examples

### Basic Multi-Chain Selection
```tsx
<MultiChainTokenInput 
  selected={currentToken}
  list={allChainTokens}
  onSelectionChanged={handleTokenChange}
  showBalances={false}
/>
```

### With Balances
```tsx
<MultiChainTokenInput 
  selected={currentToken}
  list={allChainTokens}
  onSelectionChanged={handleTokenChange}
  showBalances={true}
  className="w-full max-w-sm"
/>
```

### In a Cross-Chain Form
```tsx
<form onSubmit={handleBridge}>
  <div className="space-y-4">
    <MultiChainTokenInput 
      selected={sourceToken}
      list={allTokens}
      onSelectionChanged={setSourceToken}
      showBalances={true}
    />
    <MultiChainTokenInput 
      selected={destinationToken}
      list={allTokens.filter(t => t.chain_id !== sourceToken.chain_id)}
      onSelectionChanged={setDestinationToken}
      showBalances={true}
    />
    <button type="submit">
      Bridge
    </button>
  </div>
</form>
```

### Custom Styling
```tsx
<MultiChainTokenInput 
  selected={token}
  list={tokens}
  onSelectionChanged={handleTokenChange}
  showBalances={true}
  className="bg-gray-100 rounded-lg p-2"
/>
```

## Component Structure

1. **Trigger**
   - TokenChip with chain icon
   - Chevron down indicator
   - Click to open dialog

2. **Dialog**
   - Header with back button
   - Chain selection row
   - Search input
   - Chain-specific token list
   - Token balances (if enabled)

## Chain Selection

The component automatically extracts unique chain IDs from the token list and displays them as selectable options:
```tsx
let chains = Array.from(new Set(list.map(t => t.chain_id)));
```

# TokenInput (/docs/builderkit/components/input/token-input)

---
title: TokenInput
description: "A token selection component with a searchable token list and balance display."
---

# TokenInput

The TokenInput component provides a token selection interface with a modal dialog containing a searchable list of tokens.

## Usage

```tsx
import { TokenInput } from '@avalabs/builderkit';

// Basic usage
<TokenInput 
  selected={{ address: "0x1234...", symbol: "AVAX" }}
  chain_id={43114}
  list={tokenList}
  onSelectionChanged={(token) => console.log('Selected token:', token)}
  showBalances={true}
/>
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `selected` | `{ address: string } & Partial<TokenItem>` | - | Currently selected token |
| `chain_id` | `number` | - | Chain ID for the token list |
| `list` | `TokenItem[]` | - | Array of available tokens |
| `onSelectionChanged` | `(token: TokenItem) => void` | - | Called when token selection changes |
| `showBalances` | `boolean` | - | Whether to show token balances |
| `className` | `string` | - | Additional CSS classes |

## Features

- Token selection through modal dialog
- Displays token icon and symbol
- Shows token balances (optional)
- Searchable token list
- Uses TokenChip for selected token display
- Responsive dialog design

## Examples

### Basic Token Selection
```tsx
<TokenInput 
  selected={currentToken}
  chain_id={43114}
  list={availableTokens}
  onSelectionChanged={handleTokenChange}
  showBalances={false}
/>
```

### With Balances
```tsx
<TokenInput 
  selected={currentToken}
  chain_id={43114}
  list={availableTokens}
  onSelectionChanged={handleTokenChange}
  showBalances={true}
  className="w-full max-w-sm"
/>
```

### In a Form
```tsx
<form onSubmit={handleSwap}>
  <div className="space-y-4">
    <TokenInput 
      selected={fromToken}
      chain_id={43114}
      list={tokens}
      onSelectionChanged={setFromToken}
      showBalances={true}
    />
    <TokenInput 
      selected={toToken}
      chain_id={43114}
      list={tokens.filter(t => t.address !== fromToken.address)}
      onSelectionChanged={setToToken}
      showBalances={true}
    />
    <button type="submit">
      Swap
    </button>
  </div>
</form>
```

### Custom Styling
```tsx
<TokenInput 
  selected={token}
  chain_id={43114}
  list={tokens}
  onSelectionChanged={handleTokenChange}
  showBalances={true}
  className="bg-gray-100 rounded-lg p-2"
/>
```

## Component Structure

1. **Trigger**
   - TokenChip showing selected token
   - Chevron down indicator
   - Click to open dialog

2. **Dialog**
   - Header with back button
   - Search input
   - Scrollable token list
   - Token balances (if enabled)

## Token Item Structure

```tsx
type TokenItem = {
  chain_id: number;
  address: string;
  name: string;
  symbol: string;
  balance?: BigNumber;
}
```

# TokenChip (/docs/builderkit/components/tokens/token-chip)

---
title: TokenChip
description: "A compact component for displaying token information with optional chain icon and copy functionality."
---

# TokenChip

The TokenChip component provides a compact way to display token information, including token icon, name, symbol, and optional chain information.

## Usage

```tsx
import { TokenChip } from '@avalabs/builderkit';

// Basic usage
<TokenChip 
  chain_id={43114}
  address="0x1234567890123456789012345678901234567890"
  symbol="AVAX"
  name="Avalanche"
/>

// With chain icon and copy functionality
<TokenChip 
  chain_id={43114}
  address="0x1234567890123456789012345678901234567890"
  symbol="AVAX"
  name="Avalanche"
  showChainIcon={true}
  allowCopyToClipboard={true}
/>
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `chain_id` | `number` | - | Chain ID of the token |
| `address` | `string` | - | Token contract address |
| `symbol` | `string` | - | Token symbol |
| `name` | `string` | - | Token name (optional) |
| `showChainIcon` | `boolean` | `false` | Whether to show chain icon alongside token icon |
| `showName` | `boolean` | `true` | Whether to show token name (if false, shows only symbol) |
| `allowCopyToClipboard` | `boolean` | `false` | Enable copy address to clipboard functionality |
| `className` | `string` | - | Additional CSS classes |

## Features

- Displays token icon with optional chain icon
- Shows token name and/or symbol
- Copy to clipboard functionality with visual feedback
- Flexible layout options
- Tailwind CSS styling support

## Examples

### Basic Token Display
```tsx
<TokenChip 
  chain_id={43114}
  address="0x1234567890123456789012345678901234567890"
  symbol="AVAX"
  name="Avalanche"
/>
```

### With Chain Icon
```tsx
<TokenChip 
  chain_id={43114}
  address="0x1234567890123456789012345678901234567890"
  symbol="AVAX"
  name="Avalanche"
  showChainIcon={true}
/>
```

### Symbol Only
```tsx
<TokenChip 
  chain_id={43114}
  address="0x1234567890123456789012345678901234567890"
  symbol="AVAX"
  name="Avalanche"
  showName={false}
/>
```

### With Copy Functionality
```tsx
<TokenChip 
  chain_id={43114}
  address="0x1234567890123456789012345678901234567890"
  symbol="AVAX"
  name="Avalanche"
  allowCopyToClipboard={true}
/>
```

### Custom Styling
```tsx
<TokenChip 
  chain_id={43114}
  address="0x1234567890123456789012345678901234567890"
  symbol="AVAX"
  name="Avalanche"
  className="bg-gray-100 rounded-lg p-2"
/>
```

## Visual States

1. **Default**: Shows token information with icon
2. **Copy Button**: Shows copy icon when `allowCopyToClipboard` is true
3. **Copy Confirmation**: Shows check icon briefly after copying
4. **Chain Display**: Shows chain icon when `showChainIcon` is true 

# TokenIconWithChain (/docs/builderkit/components/tokens/token-icon-with-chain)

---
title: TokenIconWithChain
description: "A component for displaying token logos with an overlaid chain icon."
---

# TokenIconWithChain

The TokenIconWithChain component displays a token logo with its corresponding chain icon overlaid in the bottom-right corner.

## Usage

```tsx
import { TokenIconWithChain } from '@avalabs/builderkit';

// Basic usage
<TokenIconWithChain 
  chain_id={43114}
  address="0x1234567890123456789012345678901234567890"
/>

// With custom styling
<TokenIconWithChain 
  chain_id={43114}
  address="0x1234567890123456789012345678901234567890"
  className="w-8 h-8"
/>
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `chain_id` | `number` | - | Chain ID of the token |
| `address` | `string` | - | Token contract address |
| `className` | `string` | - | Additional CSS classes (applied to both icons) |

## Features

- Combines TokenIcon with chain logo
- Chain icon is automatically positioned and scaled
- Supports custom styling through className
- Uses consistent icon paths for both token and chain logos
- Responsive layout with Tailwind CSS

## Examples

### Basic Usage
```tsx
<TokenIconWithChain 
  chain_id={43114}
  address="0x1234567890123456789012345678901234567890"
/>
```

### Custom Size
```tsx
<TokenIconWithChain 
  chain_id={43114}
  address="0x1234567890123456789012345678901234567890"
  className="w-12 h-12"
/>
```

### In a Token List
```tsx
<div className="flex gap-4">
  <TokenIconWithChain 
    chain_id={43114}
    address="0x1234567890123456789012345678901234567890"
  />
  <TokenIconWithChain 
    chain_id={43113}
    address="0x5678901234567890123456789012345678901234"
  />
</div>
```

### With Custom Border
```tsx
<TokenIconWithChain 
  chain_id={43114}
  address="0x1234567890123456789012345678901234567890"
  className="border-2 border-gray-200 rounded-full"
/>
```

## Asset Requirements

The component requires two image assets:

1. Token logo at:
```
/tokens/logo/{chain_id}/{address}.png
```

2. Chain logo at:
```
/chains/logo/{chain_id}.png
```

For example:
```
/tokens/logo/43114/0x1234567890123456789012345678901234567890.png
/chains/logo/43114.png
```

## Layout Details

The component uses the following layout structure:
- Main token icon as the primary element
- Chain icon positioned at bottom-right
- Chain icon scaled to 50% of the token icon size
- Chain icon has a white border for visual separation 

# TokenIcon (/docs/builderkit/components/tokens/token-icon)

---
title: TokenIcon
description: "A component for displaying token logos."
---

# TokenIcon

The TokenIcon component displays token logos based on the token's chain ID and contract address.

## Usage

```tsx
import { TokenIcon } from '@avalabs/builderkit';

// Basic usage
<TokenIcon 
  chain_id={43114}
  address="0x1234567890123456789012345678901234567890"
/>

// With custom styling
<TokenIcon 
  chain_id={43114}
  address="0x1234567890123456789012345678901234567890"
  className="w-8 h-8 rounded-full"
/>
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `chain_id` | `number` | - | Chain ID of the token |
| `address` | `string` | - | Token contract address |
| `className` | `string` | - | Additional CSS classes |

## Features

- Displays token logos from a standardized path structure
- Supports custom styling through className
- Uses common Icon component for consistent display
- Follows `/tokens/logo/{chain_id}/{address}.png` path convention

## Examples

### Basic Token Icon
```tsx
<TokenIcon 
  chain_id={43114}
  address="0x1234567890123456789012345678901234567890"
/>
```

### Custom Size
```tsx
<TokenIcon 
  chain_id={43114}
  address="0x1234567890123456789012345678901234567890"
  className="w-12 h-12"
/>
```

### In a List
```tsx
<div className="flex gap-2">
  <TokenIcon 
    chain_id={43114}
    address="0x1234567890123456789012345678901234567890"
  />
  <TokenIcon 
    chain_id={43113}
    address="0x5678901234567890123456789012345678901234"
  />
</div>
```

### With Border
```tsx
<TokenIcon 
  chain_id={43114}
  address="0x1234567890123456789012345678901234567890"
  className="border-2 border-gray-200 rounded-full"
/>
```

## Asset Requirements

The component expects token logo images to be available at:
```
/tokens/logo/{chain_id}/{address}.png
```

For example:
```
/tokens/logo/43114/0x1234567890123456789012345678901234567890.png
``` 

# TokenList (/docs/builderkit/components/tokens/token-list)

---
title: TokenList
description: "A searchable list component for displaying and selecting tokens with optional balance information."
---

# TokenList

The TokenList component provides a searchable list of tokens with support for balance display and token selection.

## Usage

```tsx
import { TokenList } from '@avalabs/builderkit';

// Basic usage
<TokenList 
  chain_id={43114}
  list={[
    {
      chain_id: 43114,
      address: "0x1234567890123456789012345678901234567890",
      name: "Avalanche",
      symbol: "AVAX"
    },
    // ... more tokens
  ]}
  onClick={(address) => console.log('Selected token:', address)}
/>

// With balances and selected token
<TokenList 
  chain_id={43114}
  list={tokens}
  showBalances={true}
  selected={{ address: selectedTokenAddress }}
  onClick={handleTokenSelect}
/>
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `chain_id` | `number` | - | Chain ID for the token list |
| `list` | `TokenItem[]` | - | Array of tokens to display |
| `onClick` | `(address: string) => void` | - | Callback when a token is selected |
| `selected` | `{ address: string }` | - | Currently selected token (optional) |
| `showBalances` | `boolean` | `false` | Whether to show token balances |
| `className` | `string` | - | Additional CSS classes |

## Features

- Search by token name, symbol, or contract address
- Displays token balances (optional)
- Highlights selected token
- Supports token whitelisting
- Responsive scrollable list
- Search input with clear functionality

## Examples

### Basic Token List
```tsx
<TokenList 
  chain_id={43114}
  list={tokens}
  onClick={handleTokenSelect}
/>
```

### With Balances
```tsx
<TokenList 
  chain_id={43114}
  list={tokens}
  showBalances={true}
  onClick={handleTokenSelect}
/>
```

### With Selected Token
```tsx
<TokenList 
  chain_id={43114}
  list={tokens}
  selected={{ address: selectedToken.address }}
  onClick={handleTokenSelect}
  className="max-h-[400px]"
/>
```

## Token Item Structure

Each token in the list should follow this structure:
```tsx
type TokenItem = {
  chain_id: number;
  address: string;
  name: string;
  symbol: string;
  balance?: BigNumber; // Optional, used when showBalances is true
  whitelisted?: boolean; // Optional, for token verification
}
```

## States

1. **Loading**: Shows loading state when fetching balances
2. **Empty Search**: Displays all tokens in the list
3. **Search Results**: Shows filtered tokens based on search input
4. **Selected**: Highlights the currently selected token
5. **Non-whitelisted**: Shows warning for non-whitelisted tokens

## Search Functionality

The component supports searching by:
- Token name
- Token symbol
- Exact contract address

When searching by contract address:
- Must be a valid Ethereum address
- Shows token details if found in the list
- Can show import option for non-whitelisted tokens 

# TokenRow (/docs/builderkit/components/tokens/token-row)

---
title: TokenRow
description: "A component for displaying token information in a row layout with optional balance display."
---

# TokenRow

The TokenRow component displays token information in a row layout, combining a TokenChip with optional balance information.

## Usage

```tsx
import { TokenRow } from '@avalabs/builderkit';

// Basic usage
<TokenRow 
  chain_id={43114}
  address="0x1234567890123456789012345678901234567890"
  name="Avalanche"
  symbol="AVAX"
/>

// With balance and click handler
<TokenRow 
  chain_id={43114}
  address="0x1234567890123456789012345678901234567890"
  name="Avalanche"
  symbol="AVAX"
  balance={new BigNumber("1.234")}
  onClick={() => handleTokenSelect()}
/>
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `chain_id` | `number` | - | Chain ID of the token |
| `address` | `string` | - | Token contract address |
| `name` | `string` | - | Token name |
| `symbol` | `string` | - | Token symbol |
| `balance` | `BigNumber` | - | Token balance (optional) |
| `onClick` | `() => void` | - | Click handler (optional) |
| `className` | `string` | - | Additional CSS classes |

## Features

- Displays token information using TokenChip
- Shows token balance with 3 decimal places
- Supports click interactions
- Flexible styling with Tailwind CSS
- Responsive layout with proper alignment

## Examples

### Basic Display
```tsx
<TokenRow 
  chain_id={43114}
  address="0x1234567890123456789012345678901234567890"
  name="Avalanche"
  symbol="AVAX"
/>
```

### With Balance
```tsx
<TokenRow 
  chain_id={43114}
  address="0x1234567890123456789012345678901234567890"
  name="Avalanche"
  symbol="AVAX"
  balance={new BigNumber("1.234")}
/>
```

### Interactive Row
```tsx
<TokenRow 
  chain_id={43114}
  address="0x1234567890123456789012345678901234567890"
  name="Avalanche"
  symbol="AVAX"
  onClick={() => selectToken("AVAX")}
  className="hover:bg-gray-100 cursor-pointer"
/>
```

### In a List
```tsx
<div className="flex flex-col divide-y">
  <TokenRow 
    chain_id={43114}
    address="0x1234..."
    name="Avalanche"
    symbol="AVAX"
    balance={new BigNumber("1.234")}
  />
  <TokenRow 
    chain_id={43114}
    address="0x5678..."
    name="USD Coin"
    symbol="USDC"
    balance={new BigNumber("100.00")}
  />
</div>
```

## Layout Structure

The component uses a flex layout with:
- Left side: TokenChip (icon, name, and symbol)
- Right side (if balance provided):
  - Token balance (3 decimal places)
  - USD value (currently hardcoded to $0)
- Proper spacing and alignment
- Optional hover and click interactions 

# TransactionButton (/docs/builderkit/components/transaction/transaction-button)

---
title: TransactionButton
description: "A button component that handles blockchain transaction submission with built-in status tracking and notifications."
---

# TransactionButton

The TransactionButton component handles individual transaction submission with built-in status tracking and notifications.

## Usage

```tsx
import { TransactionButton } from '@avalabs/builderkit';

// Basic usage
<TransactionButton
  chain_id={43114}
  title="Send AVAX"
  description="Sending AVAX to recipient"
  data={{
    to: "0x1234...",
    value: "1000000000000000000" // 1 AVAX
  }}
/>

// With callbacks
<TransactionButton
  chain_id={43114}
  title="Stake Tokens"
  description="Staking tokens in the protocol"
  data={stakeData}
  onTransactionSent={(timestamp) => {
    console.log('Transaction sent at:', timestamp);
  }}
  onTransactionConfirmed={(receipt) => {
    console.log('Transaction confirmed:', receipt);
  }}
/>
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `chain_id` | `number` | - | Chain ID for the transaction |
| `title` | `string` | - | Transaction title |
| `description` | `string` | - | Transaction description |
| `data` | `any` | - | Transaction data |
| `onTransactionSent` | `(timestamp: number) => void` | - | Called when transaction is sent |
| `onTransactionConfirmed` | `(receipt: any) => void` | - | Called when transaction is confirmed |
| `className` | `string` | - | Additional CSS classes |

## Features

- Automatic wallet connection handling
- Network switching support
- Transaction status tracking
- Toast notifications with explorer links
- Loading states and error handling

## Examples

### Basic Transaction
```tsx
<TransactionButton
  chain_id={43114}
  title="Send Tokens"
  description="Sending tokens to recipient"
  data={{
    to: recipientAddress,
    value: amount
  }}
/>
```

### With Custom Styling
```tsx
<TransactionButton
  chain_id={43114}
  title="Custom Action"
  description="Performing custom action"
  data={actionData}
  className="bg-purple-600 hover:bg-purple-700"
/>
```

## Component States

1. **Not Connected**
   - Shows "Connect Wallet" button
   - Handles wallet connection

2. **Wrong Network**
   - Shows "Wrong Network" button
   - Handles network switching

3. **Ready**
   - Shows transaction button
   - Enables transaction submission

4. **Processing**
   - Shows loading indicator
   - Tracks transaction status

## Notifications

The component provides toast notifications for:
- Transaction sent
- Transaction confirmed
- Transaction failed

Each notification includes:
- Timestamp
- Transaction explorer link
- Appropriate styling

# TransactionManager (/docs/builderkit/components/transaction/transaction-manager)

---
title: TransactionManager
description: "A component that orchestrates multiple blockchain transactions in sequence."
---

# TransactionManager

The TransactionManager component orchestrates multiple blockchain transactions in sequence, handling the flow between steps and providing status tracking.

## Usage

```tsx
import { TransactionManager } from '@avalabs/builderkit';

// Basic usage
<TransactionManager
  chain_id={43114}
  transactions={[
    {
      title: "Approve Token",
      description: "Approving token for transfer",
      data: approveData
    },
    {
      title: "Transfer Token",
      description: "Transferring tokens to recipient",
      data: transferData
    }
  ]}
  onTransactionSent={(timestamp) => {
    console.log('Step completed at:', timestamp);
  }}
  onTransactionConfirmed={(receipt) => {
    console.log('All transactions completed:', receipt);
  }}
/>
```

## Props

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `chain_id` | `number` | - | Chain ID for the transactions |
| `transactions` | `TransactionProps[]` | - | Array of transactions to process |
| `onTransactionSent` | `(timestamp: number) => void` | - | Called when a step completes |
| `onTransactionConfirmed` | `(receipt: any) => void` | - | Called when all transactions complete |
| `className` | `string` | - | Additional CSS classes |

## Features

- Sequential transaction execution
- Step-by-step progress tracking
- Automatic state management
- Transaction dependency handling
- Consistent error handling
- Status notifications for each step

## Examples

### Token Approval and Transfer
```tsx
<TransactionManager
  chain_id={43114}
  transactions={[
    {
      title: "Step 1: Approve",
      description: "Approve token spending",
      data: approveData
    },
    {
      title: "Step 2: Transfer",
      description: "Transfer tokens to recipient",
      data: transferData
    }
  ]}
/>
```

### Multi-step Protocol Interaction
```tsx
<TransactionManager
  chain_id={43114}
  transactions={[
    {
      title: "Step 1: Approve USDC",
      description: "Approve USDC spending",
      data: approveUsdcData
    },
    {
      title: "Step 2: Approve AVAX",
      description: "Approve AVAX spending",
      data: approveAvaxData
    },
    {
      title: "Step 3: Add Liquidity",
      description: "Add liquidity to pool",
      data: addLiquidityData
    }
  ]}
/>
```

## Transaction Flow

1. **Initialization**
   - Validates transaction array
   - Sets up initial state
   - Prepares first transaction

2. **Step Execution**
   - Processes current transaction
   - Waits for confirmation
   - Updates progress state

3. **Step Transition**
   - Validates completion
   - Moves to next transaction
   - Updates UI state

4. **Completion**
   - Confirms all steps finished
   - Triggers completion callback
   - Resets internal state

# Deploy Custom VM (/docs/tooling/avalanche-cli/create-avalanche-nodes/deploy-custom-vm)

---
title: Deploy Custom VM
description: This page demonstrates how to deploy a custom VM into cloud-based validators using Avalanche-CLI.
---

<Callout title="Note">
Currently, only Fuji network and Devnets are supported.
</Callout>

<Callout type="warn">
ALPHA WARNING: This command is currently in experimental mode. Proceed at your own risk.
</Callout>

## Prerequisites

Before we begin, you will need to have:

- Created a cloud server node as described [here](/docs/tooling/create-avalanche-nodes/run-validators-aws)
- Created a Custom VM, as described [here](/docs/virtual-machines).
- (Ignore for Devnet) Set up a key to be able to pay for transaction Fees, as described [here](/docs/tooling/create-deploy-avalanche-l1s/deploy-on-fuji-testnet).

Currently, only AWS & GCP cloud services are supported.

Deploying the VM[​](#deploying-the-vm "Direct link to heading")
---------------------------------------------------------------

We will be deploying the [MorpheusVM](https://github.com/ava-labs/hypersdk/tree/main/examples/morpheusvm) example built with the HyperSDK.

The following settings will be used:

- Repo url: `https://github.com/ava-labs/hypersdk/`
- Branch Name: `vryx-poc`
- Build Script: `examples/morpheusvm/scripts/build.sh`

<Callout title="Note">
The CLI needs a public repo url in order to be able to download and install the custom VM on cloud.
</Callout>

### Genesis File[​](#genesis-file "Direct link to heading")

The following contents will serve as the chain genesis. They were generated using `morpheus-cli` as shown [here](https://github.com/ava-labs/hypersdk/blob/main/examples/morpheusvm/scripts/run.sh).

Save it into a file with path `<genesisPath>` (for example `~/morpheusvm_genesis.json`):

```bash
{
  "stateBranchFactor":16,
  "minBlockGap":1000,
  "minUnitPrice":[1,1,1,1,1],
  "maxChunkUnits":[1800000,18446744073709551615,18446744073709551615,18446744073709551615,18446744073709551615],
  "epochDuration":60000,
  "validityWindow":59000,
  "partitions":8,
  "baseUnits":1,
  "baseWarpUnits":1024,
  "warpUnitsPerSigner":128,
  "outgoingWarpComputeUnits":1024,
  "storageKeyReadUnits":5,
  "storageValueReadUnits":2,
  "storageKeyAllocateUnits":20,
  "storageValueAllocateUnits":5,
  "storageKeyWriteUnits":10,
  "storageValueWriteUnits":3,
  "customAllocation": [
    {
      "address":"morpheus1qrzvk4zlwj9zsacqgtufx7zvapd3quufqpxk5rsdd4633m4wz2fdjk97rwu",
      "balance":3000000000000000000
    },
    {"address":"morpheus1qryyvfut6td0l2vwn8jwae0pmmev7eqxs2vw0fxpd2c4lr37jj7wvrj4vc3",
      "balance":3000000000000000000
    },
    {"address":"morpheus1qp52zjc3ul85309xn9stldfpwkseuth5ytdluyl7c5mvsv7a4fc76g6c4w4",
      "balance":3000000000000000000
    },
    {"address":"morpheus1qzqjp943t0tudpw06jnvakdc0y8w790tzk7suc92aehjw0epvj93s0uzasn",
      "balance":3000000000000000000
    },
    {"address":"morpheus1qz97wx3vl3upjuquvkulp56nk20l3jumm3y4yva7v6nlz5rf8ukty8fh27r",
      "balance":3000000000000000000
    }
  ]
}
```

Create the Avalanche L1[​](#create-the-avalanche-l1 "Direct link to heading")
-----------------------------------------------------------------

Let's create an Avalanche L1 called `<blockchainName>`, with custom VM binary and genesis.

```bash
avalanche blockchain create <blockchainName>
```

Choose custom

```bash
Use the arrow keys to navigate: ↓ ↑ → ←
? Choose your VM:
    Subnet-EVM
  ▸ Custom
```

Provide path to genesis:

```bash
✗ Enter path to custom genesis: <genesisPath>
```

Provide the source code repo url:

```bash
✗ Source code repository URL: https://github.com/ava-labs/hypersdk/
```

Set the branch and finally set the build script:

```bash
✗ Build script: examples/morpheusvm/scripts/build.sh
```

CLI will generate a locally compiled binary, and then create the Avalanche L1.

```bash
Cloning into ...

Successfully created subnet configuration
```

## Deploy Avalanche L1

For this example, we will deploy the Avalanche L1 and blockchain on Fuji. Run:

```bash
avalanche blockchain deploy <blockchainName>
```

Choose Fuji:

```bash
Use the arrow keys to navigate: ↓ ↑ → ←
? Choose a network to deploy on:
    Local Network
  ▸ Fuji
    Mainnet
```

Use the stored key:

```bash
Use the arrow keys to navigate: ↓ ↑ → ←
? Which key source should be used to pay transaction fees?:
  ▸ Use stored key
    Use ledger
```

Choose `<keyName>` as the key to use to pay the fees:

```bash
Use the arrow keys to navigate: ↓ ↑ → ←
? Which stored key should be used to pay transaction fees?:
  ▸ <keyName>
```

Use the same key as the control key for the Avalanche L1:

```bash
Use the arrow keys to navigate: ↓ ↑ → ←
? How would you like to set your control keys?:
  ▸ Use fee-paying key
    Use all stored keys
    Custom list
```

The successfully creation of our Avalanche L1 and blockchain is confirmed by the following output:

```bash
Your Subnet's control keys: [P-fuji1dlwux652lkflgz79g3nsphjzvl6t35xhmunfk1]
Your subnet auth keys for chain creation: [P-fuji1dlwux652lkflgz79g3nsphjzvl6t35xhmunfk1]
Subnet has been created with ID: RU72cWmBmcXber6ZBPT7R5scFFuVSoFRudcS3vayf3L535ZE3
Now creating blockchain...
+--------------------+----------------------------------------------------+
| DEPLOYMENT RESULTS |                                                    |
+--------------------+----------------------------------------------------+
| Chain Name         | blockchainName                                     |
+--------------------+----------------------------------------------------+
| Subnet ID          | RU72cWmBmcXber6ZBPT7R5scFFuVSoFRudcS3vayf3L535ZE3  |
+--------------------+----------------------------------------------------+
| VM ID              | srEXiWaHq58RK6uZMmUNaMF2FzG7vPzREsiXsptAHk9gsZNvN  |
+--------------------+----------------------------------------------------+
| Blockchain ID      | 2aDgZRYcSBsNoLCsC8qQH6iw3kUSF5DbRHM4sGEqVKwMSfBDRf |
+--------------------+                                                    +
| P-Chain TXID       |                                                    |
+--------------------+----------------------------------------------------+
```

Set the Config Files[​](#set-the-config-files "Direct link to heading")
-----------------------------------------------------------------------

Avalanche-CLI supports uploading the full set of configuration files for a blockchain:

- Genesis File
- Blockchain Config
- Avalanche L1 Config
- Network Upgrades
- AvalancheGo Config

The following example uses all of them, but the user can decide to provide a subset of those.

### AvalancheGo Flags[​](#avalanchego-flags "Direct link to heading")

Save the following content (as defined [here](https://github.com/ava-labs/hypersdk/blob/vryx-poc/examples/morpheusvm/tests/e2e/e2e_test.go))
into a file with path `<avagoFlagsPath>` (for example `~/morpheusvm_avago.json`):

```json
{
  "log-level":"INFO",
  "log-display-level":"INFO",
  "proposervm-use-current-height":true,
  "throttler-inbound-validator-alloc-size":"10737418240",
  "throttler-inbound-at-large-alloc-size":"10737418240",
  "throttler-inbound-node-max-processing-msgs":"1000000",
  "throttler-inbound-node-max-at-large-bytes":"10737418240",
  "throttler-inbound-bandwidth-refill-rate":"1073741824",
  "throttler-inbound-bandwidth-max-burst-size":"1073741824",
  "throttler-inbound-cpu-validator-alloc":"100000",
  "throttler-inbound-cpu-max-non-validator-usage":"100000",
  "throttler-inbound-cpu-max-non-validator-node-usage":"100000",
  "throttler-inbound-disk-validator-alloc":"10737418240000",
  "throttler-outbound-validator-alloc-size":"10737418240",
  "throttler-outbound-at-large-alloc-size":"10737418240",
  "throttler-outbound-node-max-at-large-bytes":"10737418240",
  "consensus-on-accept-gossip-validator-size":"10",
  "consensus-on-accept-gossip-peer-size":"10",
  "network-compression-type":"zstd",
  "consensus-app-concurrency":"128",
  "profile-continuous-enabled":true,
  "profile-continuous-freq":"1m",
  "http-host":"",
  "http-allowed-origins": "*",
  "http-allowed-hosts": "*"
}
```

Then set the Avalanche L1 to use it by executing:

```bash
avalanche blockchain configure blockchainName
```

Select node-config.json:

```bash
Use the arrow keys to navigate: ↓ ↑ → ←
? Which configuration file would you like to provide?:
  ▸ node-config.json
    chain.json
    subnet.json
    per-node-chain.json
```

Provide the path to the AvalancheGo config file:

```bash
✗ Enter the path to your configuration file: <avagoFlagsPath>
```

Finally, choose no:

```bash
Use the arrow keys to navigate: ↓ ↑ → ←
? Would you like to provide the chain.json file as well?:
  ▸ No
    Yes
File ~/.avalanche-cli/subnets/blockchainName/node-config.json successfully written
```

### Blockchain Config[​](#blockchain-config "Direct link to heading")

`morpheus-cli` as shown [here](https://github.com/ava-labs/hypersdk/blob/vryx-poc/examples/morpheusvm/scripts/run.sh).
Save the following content (generated by this [script](https://github.com/ava-labs/hypersdk/blob/vryx-poc/examples/morpheusvm/scripts/run.sh))
in a known file path (for example `~/morpheusvm_chain.json`):

```json
{
  "chunkBuildFrequency": 250,
  "targetChunkBuildDuration": 250,
  "blockBuildFrequency": 100,
  "mempoolSize": 2147483648,
  "mempoolSponsorSize": 10000000,
  "authExecutionCores": 16,
  "precheckCores": 16,
  "actionExecutionCores": 8,
  "missingChunkFetchers": 48,
  "verifyAuth": true,
  "authRPCCores": 48,
  "authRPCBacklog": 10000000,
  "authGossipCores": 16,
  "authGossipBacklog": 10000000,
  "chunkStorageCores": 16,
  "chunkStorageBacklog": 10000000,
  "streamingBacklogSize": 10000000,
  "continuousProfilerDir":"/home/ubuntu/morpheusvm-profiles",
  "logLevel": "INFO"
}
```

Then set the Avalanche L1 to use it by executing:

```bash
avalanche blockchain configure blockchainName
```

Select chain.json:

```bash
Use the arrow keys to navigate: ↓ ↑ → ←
? Which configuration file would you like to provide?:
    node-config.json
  ▸ chain.json
    subnet.json
    per-node-chain.json
```

Provide the path to the blockchain config file:

```bash
✗ Enter the path to your configuration file: ~/morpheusvm_chain.json
```

Finally choose no:

```bash
Use the arrow keys to navigate: ↓ ↑ → ←
? Would you like to provide the subnet.json file as well?:
  ▸ No
    Yes
File ~/.avalanche-cli/subnets/blockchainName/chain.json successfully written
```

### Avalanche L1 Config[​](#avalanche-l1-config "Direct link to heading")

Save the following content (generated by this [script](https://github.com/ava-labs/hypersdk/blob/vryx-poc/examples/morpheusvm/scripts/run.sh))
in a known path (for example `~/morpheusvm_subnet.json`):

```json
{
  "proposerMinBlockDelay": 0,
  "proposerNumHistoricalBlocks": 512
}
```

Then set the Avalanche L1 to use it by executing:

```bash
avalanche blockchain configure blockchainName
```

Select `subnet.json`:

```bash
Use the arrow keys to navigate: ↓ ↑ → ←
? Which configuration file would you like to provide?:
    node-config.json
    chain.json
  ▸ subnet.json
    per-node-chain.json
```

Provide the path to the Avalanche L1 config file:

```bash
✗ Enter the path to your configuration file: ~/morpheusvm_subnet.json
```

Choose no:

```bash
Use the arrow keys to navigate: ↓ ↑ → ←
? Would you like to provide the chain.json file as well?:
  ▸ No
    Yes
File ~/.avalanche-cli/subnets/blockchainName/subnet.json successfully written
```

### Network Upgrades[​](#network-upgrades "Direct link to heading")

Save the following content (currently with no network upgrades) in a known path (for example `~/morpheusvm_upgrades.json`):

Then set the Avalanche L1 to use it by executing:

```bash
avalanche blockchain upgrade import blockchainName
```

Provide the path to the network upgrades file:

```bash
✗ Provide the path to the upgrade file to import: ~/morpheusvm_upgrades.json
```

Deploy Our Custom VM[​](#deploy-our-custom-vm "Direct link to heading")
-----------------------------------------------------------------------

To deploy our Custom VM, run:

```bash
avalanche node sync <clusterName> <blockchainName>
```

```bash
Node(s) successfully started syncing with Subnet!
```

Your custom VM is successfully deployed!

You can also use `avalanche node update blockchain <blockchainName>` to reinstall the binary when the branch is updated, or update the config files.

# Execute SSH Command (/docs/tooling/avalanche-cli/create-avalanche-nodes/execute-ssh-commands)

---
title: Execute SSH Command
description: This page demonstrates how to execute a SSH command on a Cluster or Node managed by Avalanche-CLI
---

<Callout type="warn">
ALPHA WARNING: This command is currently in experimental mode. Proceed at your own risk.
</Callout>

## Prerequisites

Before we begin, you will need to have a cluster managed by CLI, either a [Fuji Cluster using AWS](/docs/tooling/create-avalanche-nodes/run-validators-aws), a [Fuji Cluster using GCP](/docs/tooling/create-avalanche-nodes/run-validators-gcp), or a [Devnet](/docs/tooling/create-avalanche-nodes/setup-devnet),

SSH Warning[​](#ssh-warning "Direct link to heading")
-----------------------------------------------------

Note: An expected warning may be seen when executing the command on a given cluster for the first time:

```bash
Warning: Permanently added 'IP' (ED25519) to the list of known hosts.
```

Get SSH Connection Instructions for All Clusters[​](#get-ssh-connection-instructions-for-all-clusters "Direct link to heading")
-------------------------------------------------------------------------------------------------------------------------------

Just execute `node ssh`:

```bash
avalanche node ssh
Cluster "<clusterName>" (Devnet)
  [i-0cf58a280bf3ef9a1] ssh -o IdentitiesOnly=yes -o StrictHostKeyChecking=no [email protected] -i /home/fm/.ssh/fm-us-east-1-avalanche-cli-us-east-1-kp.pem 
  [i-0e2abd71a586e56b4] ssh -o IdentitiesOnly=yes -o StrictHostKeyChecking=no [email protected] -i /home/fm/.ssh/fm-us-east-1-avalanche-cli-us-east-1-kp.pem 
  [i-027417a4f2ca0a478] ssh -o IdentitiesOnly=yes -o StrictHostKeyChecking=no [email protected] -i /home/fm/.ssh/fm-us-east-1-avalanche-cli-us-east-1-kp.pem 
  [i-0360a867aa295d8a4] ssh -o IdentitiesOnly=yes -o StrictHostKeyChecking=no [email protected] -i /home/fm/.ssh/fm-us-east-1-avalanche-cli-us-east-1-kp.pem 
  [i-0759b102acfd5b585] ssh -o IdentitiesOnly=yes -o StrictHostKeyChecking=no [email protected] -i /home/fm/.ssh/fm-us-east-1-avalanche-cli-us-east-1-kp.pem 
```

Get the AvalancheGo PID for All Nodes in `<clusterName>`[​](#get-the-avalanchego-pid-for-all-nodes-in-clustername "Direct link to heading")
-------------------------------------------------------------------------------------------------------------------------------------------

```bash
avalanche node ssh <clusterName> pgrep avalanchego
[i-0cf58a280bf3ef9a1] ssh -o IdentitiesOnly=yes -o StrictHostKeyChecking=no [email protected] -i /home/fm/.ssh/fm-us-east-1-avalanche-cli-us-east-1-kp.pem pgrep avalanchego
14508

[i-0e2abd71a586e56b4] ssh -o IdentitiesOnly=yes -o StrictHostKeyChecking=no [email protected] -i /home/fm/.ssh/fm-us-east-1-avalanche-cli-us-east-1-kp.pem pgrep avalanchego
14555

[i-027417a4f2ca0a478] ssh -o IdentitiesOnly=yes -o StrictHostKeyChecking=no [email protected] -i /home/fm/.ssh/fm-us-east-1-avalanche-cli-us-east-1-kp.pem pgrep avalanchego
14545

[i-0360a867aa295d8a4] ssh -o IdentitiesOnly=yes -o StrictHostKeyChecking=no [email protected] -i /home/fm/.ssh/fm-us-east-1-avalanche-cli-us-east-1-kp.pem pgrep avalanchego
14531

[i-0759b102acfd5b585] ssh -o IdentitiesOnly=yes -o StrictHostKeyChecking=no [email protected] -i /home/fm/.ssh/fm-us-east-1-avalanche-cli-us-east-1-kp.pem pgrep avalanchego
14555
```

Please note that commands via `ssh` on cluster are executed sequentially by default. It's possible to run command on all nodes at the same time by using `--parallel=true` flag

Get the AvalancheGo Configuration for All Nodes in `<clusterName>`[​](#get-the-avalanchego-configuration-for-all-nodes-in-clustername "Direct link to heading")
---------------------------------------------------------------------------------------------------------------------------------------------------------------

```bash
avalanche node ssh <clusterName> cat /home/ubuntu/.avalanchego/configs/node.json
[i-0cf58a280bf3ef9a1] ssh -o IdentitiesOnly=yes -o StrictHostKeyChecking=no [email protected] -i /home/fm/.ssh/fm-us-east-1-avalanche-cli-us-east-1-kp.pem cat /home/ubuntu/.avalanchego/configs/node.json
{
  "bootstrap-ids": "",
  "bootstrap-ips": "",
  "genesis-file": "/home/ubuntu/.avalanchego/configs/genesis.json",
  "http-allowed-hosts": "*",
  "http-allowed-origins": "*",
  "http-host": "",
  "log-display-level": "info",
  "log-level": "info",
  "network-id": "network-1338",
  "public-ip": "44.219.113.190",
  "track-subnets": "giY8tswWgZmcAWzPkoNrmjjrykited7GJ9799SsFzTiq5a1ML"
}
[i-0e2abd71a586e56b4] ssh -o IdentitiesOnly=yes -o StrictHostKeyChecking=no [email protected] -i /home/fm/.ssh/fm-us-east-1-avalanche-cli-us-east-1-kp.pem cat /home/ubuntu/.avalanchego/configs/node.json
{
  "bootstrap-ids": "NodeID-EzxsrhoumLsQSWxsohfMFrM1rJcaiaBK8",
  "bootstrap-ips": "44.219.113.190:9651",
  "genesis-file": "/home/ubuntu/.avalanchego/configs/genesis.json",
  "http-allowed-hosts": "*",
  "http-allowed-origins": "*",
  "http-host": "",
  "log-display-level": "info",
  "log-level": "info",
  "network-id": "network-1338",
  "public-ip": "3.212.206.161",
  "track-subnets": "giY8tswWgZmcAWzPkoNrmjjrykited7GJ9799SsFzTiq5a1ML"
}
[i-027417a4f2ca0a478] ssh -o IdentitiesOnly=yes -o StrictHostKeyChecking=no [email protected] -i /home/fm/.ssh/fm-us-east-1-avalanche-cli-us-east-1-kp.pem cat /home/ubuntu/.avalanchego/configs/node.json
{
  "bootstrap-ids": "NodeID-EzxsrhoumLsQSWxsohfMFrM1rJcaiaBK8,NodeID-6veKG5dAz1uJvKc7qm7v6wAPDod8hctb9",
  "bootstrap-ips": "44.219.113.190:9651,3.212.206.161:9651",
  "genesis-file": "/home/ubuntu/.avalanchego/configs/genesis.json",
  "http-allowed-hosts": "*",
  "http-allowed-origins": "*",
  "http-host": "",
  "log-display-level": "info",
  "log-level": "info",
  "network-id": "network-1338",
  "public-ip": "54.87.168.26",
  "track-subnets": "giY8tswWgZmcAWzPkoNrmjjrykited7GJ9799SsFzTiq5a1ML"
}
[i-0360a867aa295d8a4] ssh -o IdentitiesOnly=yes -o StrictHostKeyChecking=no [email protected] -i /home/fm/.ssh/fm-us-east-1-avalanche-cli-us-east-1-kp.pem cat /home/ubuntu/.avalanchego/configs/node.json
{
  "bootstrap-ids": "NodeID-EzxsrhoumLsQSWxsohfMFrM1rJcaiaBK8,NodeID-6veKG5dAz1uJvKc7qm7v6wAPDod8hctb9,NodeID-ASseyUweBT82XquiGpmUFjd9QfkUjxiAY",
  "bootstrap-ips": "44.219.113.190:9651,3.212.206.161:9651,54.87.168.26:9651",
  "genesis-file": "/home/ubuntu/.avalanchego/configs/genesis.json",
  "http-allowed-hosts": "*",
  "http-allowed-origins": "*",
  "http-host": "",
  "log-display-level": "info",
  "log-level": "info",
  "network-id": "network-1338",
  "public-ip": "3.225.42.57",
  "track-subnets": "giY8tswWgZmcAWzPkoNrmjjrykited7GJ9799SsFzTiq5a1ML"
}
[i-0759b102acfd5b585] ssh -o IdentitiesOnly=yes -o StrictHostKeyChecking=no [email protected] -i /home/fm/.ssh/fm-us-east-1-avalanche-cli-us-east-1-kp.pem cat /home/ubuntu/.avalanchego/configs/node.json
{
  "bootstrap-ids": "NodeID-EzxsrhoumLsQSWxsohfMFrM1rJcaiaBK8,NodeID-6veKG5dAz1uJvKc7qm7v6wAPDod8hctb9,NodeID-ASseyUweBT82XquiGpmUFjd9QfkUjxiAY,NodeID-LfwbUp9dkhmWTSGffer9kNWNzqUQc2TEJ",
  "bootstrap-ips": "44.219.113.190:9651,3.212.206.161:9651,54.87.168.26:9651,3.225.42.57:9651",
  "genesis-file": "/home/ubuntu/.avalanchego/configs/genesis.json",
  "http-allowed-hosts": "*",
  "http-allowed-origins": "*",
  "http-host": "",
  "log-display-level": "info",
  "log-level": "info",
  "network-id": "network-1338",
  "public-ip": "107.21.158.224",
  "track-subnets": "giY8tswWgZmcAWzPkoNrmjjrykited7GJ9799SsFzTiq5a1ML"
}
```

Executing Command on a Single Node[​](#executing-command-on-a-single-node "Direct link to heading")
---------------------------------------------------------------------------------------------------

As we all know command can be executed on single node similar to the examples above To execute ssh command on a single node, use `<nodeID>`, `<IP>` or `<instanceID>` instead of `<clusterName>` as an argument. For example:

```bash
avalanche node ssh i-0225fc39626b1edd3 <command>
[or]
avalanche node ssh NodeID-9wdKQ3KJU3GqvgFTc4CUYvmefEFe8t6ka <command>
[or]
avalanche node ssh 54.159.59.123 <command>
```

In this case `--parallel=true` flag will be ignored

Opening SSH Shell for `<nodeID>`[​](#opening-ssh-shell-for-nodeid "Direct link to heading")
-------------------------------------------------------------------------------------------

If no command is provided, Avalanche-CLI will open an interactive session for the specified node. For example:

```bash
avalanche node ssh i-0225fc39626b1edd3
[or] 
avalanche node ssh NodeID-9wdKQ3KJU3GqvgFTc4CUYvmefEFe8t6ka
[or]
avalanche node ssh 54.159.59.123
```

Please use `exit` shell command or Ctrl+D to end this session.

# Run Load Test (/docs/tooling/avalanche-cli/create-avalanche-nodes/run-loadtest)

---
title: Run Load Test
description: This page demonstrates how to run load test on an Avalanche L1 deployed on a cluster of cloud-based validators using Avalanche-CLI.
---

## Prerequisites

Before we begin, you will need to have:

- Created an AWS account and have an updated AWS `credentials` file in home directory with [default] profile or set up your GCP account according to [here](/docs/tooling/create-avalanche-nodes/run-validators-gcp)
- Created a cluster of cloud servers with monitoring enabled
- Deployed an Avalanche L1 into the cluster
- Added the cloud servers as validator nodes in the Avalanche L1

## Run Load Test

When the load test command is run, a new cloud server will be created to run the load test. The  
created cloud server is referred by the name `<loadtestName>` and you can use any name of your 
choice.

To start load test, run:

```bash
avalanche node loadtest start <loadtestName> <clusterName> <blockchainName>
```

Next, you will need to provide the load test Git repository URL, load test Git Branch, the command 
to build the load test binary and the command to run the load test binary.

We will use an example of running load test on an Avalanche L1 running custom VM MorpheusVM built with 
[HyperSDK](https://github.com/ava-labs/hypersdk/tree/main/examples/morpheusvm).

The following settings will be used:

- Load Test Repo URL: `https://github.com/ava-labs/hypersdk/`
- Load Test Branch: `vryx-poc`
- Load Test Build Script: `cd /home/ubuntu/hypersdk/examples/morpheusvm; CGO_CFLAGS=\"-O -D__BLST_PORTABLE__\" go build -o ~/simulator ./cmd/morpheus-cli`
- Load Test Run Script: `/home/ubuntu/simulator spam run ed25519 --accounts=10000000 --txs-per-second=100000 --min-capacity=15000 --step-size=1000 --s-zipf=1.0001 --v-zipf=2.7 --conns-per-host=10 --cluster-info=/home/ubuntu/clusterInfo.yaml --private-key=323b1d8f4eed5f0da9da93071b034f2dce9d2d22692c172f3cb252a64ddfafd01b057de320297c29ad0c1f589ea216869cf1938d88c9fbd70d6748323dbf2fa7`

Once the command is run, you will be able to see the logs from the load test in the cluster's 
Grafana URL like the example below:

![Centralized Logs](/images/centralized-logs.png)

## Stop Load Test

To stop the load test process on the load test instance `<loadtestName>` and terminate the load test instance, run:

```bash
avalanche node loadtest stop <loadtestName>
```


# Run Validator on AWS (/docs/tooling/avalanche-cli/create-avalanche-nodes/run-validators-aws)

---
title: Run Validator on AWS
description: This page demonstrates how to deploy Avalanche validators on AWS using just one Avalanche-CLI command.
---

This page demonstrates how to deploy Avalanche validators on AWS using just one Avalanche-CLI command.

<Callout title="Note">
Currently, only Fuji network and Devnets are supported.
</Callout>

<Callout type="warn">
ALPHA WARNING: This command is currently in experimental mode. Proceed at your own risk.
</Callout>

## Prerequisites

Before we begin, you will need to create an AWS account and have an AWS `credentials` file in home directory with \[default\] profile set. More info can be found [here](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html#file-format-creds)

## Create Validators

To create Avalanche validators, run:

```bash
avalanche node create <clusterName>
```

The created nodes will be part of cluster `clusterName` and all avalanche node commands applied to cluster `clusterName` will apply to all nodes in the cluster.

<Callout title="Note">
Please note that running a validator on AWS will incur costs.

Ava Labs is not responsible for the cost incurred from running an Avalanche validator on cloud services via Avalanche-CLI.
</Callout>

Currently, we have set the following specs of the AWS cloud server to a fixed value, but we plan to enable customization in the near future:

- OS Image: `Ubuntu 20.04 LTS (HVM), SSD Volume Type`
- Storage: `1 TB`

Instance type can be specified via `--node-type` parameter or via interactive menu. `c5.2xlarge` is the default(recommended) instance size.

The command will ask which region you want to set up your cloud server in:

```bash
 Which AWS region do you want to set up your node in?: 
  ▸ us-east-1
    us-east-2
    us-west-1
    us-west-2
    Choose custom region (list of regions available at https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html)
```

The command will next ask whether you want to set up monitoring for your nodes.

```bash
  Do you want to set up a separate instance to host monitoring? (This enables you to monitor all your set up instances in one dashboard): 
  ▸ Yes
    No
```

Setting up monitoring on a separate AWS instance enables you to have a centralized Grafana logs and dashboard for all nodes in a cluster, as seen below:

![Centralized Logs](/images/centralized-logs.png)

![Main Dashboard](/images/run-validators1.png)

The separate monitoring AWS instance will have similar specs to the default AWS cloud server, except for its storage, which will be set to 50 GB.

Please note that setting up monitoring on a separate AWS instance will incur additional cost of setting up an additional AWS cloud server.

The command will then ask which Avalanche Go version you would like to install in the cloud server. You can choose `default` (which will install the latest version) or you can enter the name of an Avalanche L1 created with CLI that you plan to be validated by this node (we will get the latest version that is compatible with the deployed Avalanche L1's RPC version).

Once the command has successfully completed, Avalanche-CLI outputs all the created cloud server node IDs as well as the public IP that each node can be reached at.

Avalanche-CLI also outputs the command that you can use to ssh into each cloud server node.

Finally, if monitoring is set up, Avalanche-CLI will also output the Grafana link where the 
centralized dashboards and logs can be accessed.

By the end of successful run of `create` command, Avalanche-CLI would have:

- Installed Avalanche Go in cloud server
- Installed Avalanche CLI in cloud server
- Downloaded the `.pem` private key file to access the cloud server into your local `.ssh` directory. Back up this private key file as you will not be able to ssh into the cloud server node without it (unless `ssh-agent` is used).
- Downloaded `staker.crt` and `staker.key` files to your local `.avalanche-cli` directory so that you can back up your node. More info about node backup can be found [here](/docs/nodes/maintain/backup-restore)
- Started the process of bootstrapping your new Avalanche node to the Primary Network (for non-Devnet only).

Please note that Avalance CLI can be configured to use `ssh-agent` for ssh communication. In this case public key will be read from there and cloud server will be accessible using it. Yubikey hardware can be also used to store private ssh key. Please use official Yubikey documentation, for example \[[https://developers.yubico.com/PGP/SSH\_authentication/](https://developers.yubico.com/PGP/SSH_authentication/)\] for more details.

Check Bootstrap Status[​](#check-bootstrap-status "Direct link to heading")
---------------------------------------------------------------------------

<Callout title="Note">
Ignore for Devnet
</Callout>

Please note that you will have to wait until the nodes have finished bootstrapping before the nodes can be Primary Network or Avalanche L1 Validators. To check whether all the nodes in a cluster have finished bootstrapping, run `avalanche node status <clusterName>`.


# Run Validator on GCP (/docs/tooling/avalanche-cli/create-avalanche-nodes/run-validators-gcp)

---
title: Run Validator on GCP
description: This page demonstrates how to deploy Avalanche validators on GCP using just one Avalanche-CLI command.
---

This page demonstrates how to deploy Avalanche validators on GCP using just one Avalanche-CLI command.

<Callout title="Note">
Currently, only Fuji network and Devnets are supported.
</Callout>

<Callout type="warn">
ALPHA WARNING: This command is currently in experimental mode. Proceed at your own risk.
</Callout>

## Prerequisites

Before we begin, you will need to:

- Create a GCP account [here](https://console.cloud.google.com/freetrial) and create a new project
- Enable Compute Engine API [here](https://console.cloud.google.com/apis/api/compute.googleapis.com)
- Download the key json for the automatically created service account as shown [here](https://cloud.google.com/iam/docs/keys-create-delete#creating)

## Create Validator

To create Avalanche validators, run:

```bash
avalanche node create <clusterName>
```

The created nodes will be part of cluster `clusterName` and all avalanche node commands applied to cluster `clusterName` will apply to all nodes in the cluster.

<Callout title="Note">
Please note that running a validator on GCP will incur costs.

Ava Labs is not responsible for the cost incurred from running an Avalanche validator on cloud services via Avalanche-CLI.
</Callout>

Currently, we have set the following specs of the GCP cloud server to a fixed value, but we plan to enable customization in the near future:

- OS Image: `Ubuntu 20.04 LTS`
- Storage: `1 TB`

Instance type can be specified via `--node-type` parameter or via interactive menu. `e2-standard-8` is default(recommended) instance size.

The command will ask which region you want to set up your cloud server in:

```bash
Which Google Region do you want to set up your node(s) in?:
  ▸ us-east1
    us-central1
    us-west1
    Choose custom Google Region (list of Google Regions available at https://cloud.google.com/compute/docs/regions-zones/)
```

The command will next ask whether you want to set up monitoring for your nodes. 

```bash
  Do you want to set up a separate instance to host monitoring? (This enables you to monitor all your set up instances in one dashboard): 
  ▸ Yes
    No
```

Setting up monitoring on a separate GCP instance enables you to have a unified Grafana dashboard for all nodes in a cluster, as seen below:

![Centralized Logs](/images/centralized-logs.png)

![Main Dashboard](/images/gcp1.png)

The separate monitoring GCP instance will have similar specs to the default GCP cloud server, except for its storage, which will be set to 50 GB.

Please note that setting up monitoring on a separate GCP instance will incur additional cost of setting up an additional GCP cloud server.

The command will then ask which Avalanche Go version you would like to install in the cloud server. You can choose `default` (which will install the latest version) or you can enter the name of an Avalanche L1 created with CLI that you plan to be validated by this node (we will get the latest version that is compatible with the deployed Avalanche L1's RPC version).

Once the command has successfully completed, Avalanche-CLI outputs all the created cloud server node IDs as well as the public IP that each node can be reached at.

Avalanche-CLI also outputs the command that you can use to ssh into each cloud server node.

Finally, if monitoring is set up, Avalanche-CLI will also output the Grafana link where the centralized dashboards and logs can be accessed.

By the end of successful run of `create` command, Avalanche-CLI would have:

- Installed Avalanche Go in cloud server
- Installed Avalanche CLI in cloud server
- Downloaded the `.pem` private key file to access the cloud server into your local `.ssh` directory. Back up this private key file as you will not be able to ssh into the cloud server node without it (unless `ssh-agent` is used).
- Downloaded `staker.crt` and `staker.key` files to your local `.avalanche-cli` directory so that you can back up your node. More info about node backup can be found [here](/docs/nodes/maintain/backup-restore)
- Started the process of bootstrapping your new Avalanche node to the Primary Network

Please note that Avalanche CLI can be configured to use `ssh-agent` for ssh access to cloud server. Yubikey hardware can be also used to store private ssh key. Please use official Yubikey documentation, for example \[[https://developers.yubico.com/PGP/SSH\_authentication/](https://developers.yubico.com/PGP/SSH_authentication/)\] for more details.

Check Bootstrap Status[​](#check-bootstrap-status "Direct link to heading")
---------------------------------------------------------------------------

<Callout title="Note">
Ignore for Devnet
</Callout>

Please note that you will have to wait until the nodes have finished bootstrapping before the nodes can be Primary Network or Avalanche L1 Validators. To check whether all the nodes in a cluster have finished bootstrapping, run `avalanche node status <clusterName>`.

# Setup a Devnet (/docs/tooling/avalanche-cli/create-avalanche-nodes/setup-devnet)

---
title: Setup a Devnet
description: This page demonstrates how to setup a Devnet of cloud-based validators using Avalanche-CLI, and deploy a VM into it.
---

Devnets (Developer Networks) are isolated Avalanche networks deployed on the cloud. Similar to local networks in terms of configuration and usage but installed on remote nodes.

Think of DevNets as being an intermediate step in the developer testing process after local network and before Fuji network.

<Callout type="warn">
ALPHA WARNING: This command is currently in experimental mode. Proceed at your own risk.
</Callout>

## Prerequisites

Before we begin, you will need to create an AWS account and have an updated AWS `credentials` file in home directory with [default] profile or set up your GCP account according to [here](/docs/tooling/create-avalanche-nodes/run-validators-gcp).

Note: the tutorial uses AWS hosts, but Devnets can also be created and operated in other supported cloud providers, such as GCP.

## Setting up a Devnet

Setting up a Devnet consists of:

- Creating a cluster of cloud servers
- Deploying an Avalanche L1 into the cluster
- Adding the cloud servers as validator nodes in the Avalanche L1

To execute all steps above in one command, run:

```bash
avalanche node devnet wiz <clusterName>
```

Command line flags can be used instead of interacting with the prompts. The complete command line
flags for `devnet wiz` command can be found [here](/docs/tooling/cli-commands#node-devnet-wiz).

Let's go through several examples with the full command (with flags) provided.

### Create a Devnet and Deploy Subnet-EVM Based Avalanche L1 into the Devnet

For example, to spin up a Devnet with 5 validator nodes and 1 API node in 5 regions each 
(us-west-2,us-east-1,ap-south-1,ap-northeast-1,eu-west-1) in AWS with each node having spec of 
c7g.8xlarge AWS EC2 instance type and io2 volume type, with Avalanche L1 `<blockchainName>` deployed 
into the Devnet, we will run :

```bash
avalanche node devnet wiz <clusterName> <blockchainName> --authorize-access
  --aws --num-apis 1,1,1,1,1 --num-validators 5,5,5,5,5 
  --region us-west-2,us-east-1,ap-south-1,ap-northeast-1,eu-west-1 --default-validator-params 
  --node-type c7g.8xlarge --aws-volume-type=io2

Creating the devnet
...
Waiting for node(s) in cluster <clusterName> to be healthy...
...
Nodes healthy after 33 seconds

Deploying the subnet
...
Setting the nodes as subnet trackers
...
Waiting for node(s) in cluster <clusterName>to be healthy...
Nodes healthy after 33 seconds
...
Waiting for node(s) in cluster <clusterName> to be syncing subnet <blockchainName>...
Nodes Syncing <blockchainName> after 5 seconds

Adding nodes as subnet validators
...
Waiting for node(s) in cluster <clusterName> to be validating subnet <blockchainName>...
Nodes Validating <blockchainName> after 23 seconds

Devnet <clusterName> has been created and is validating subnet <blockchainName>!
```

### Create a Devnet and Deploy a Custom VM based Avalanche L1 into the Devnet

For this example, we will be using the custom VM [MorpheusVM](https://github.com/ava-labs/hypersdk/tree/main/examples/morpheusvm)
built with [HyperSDK](https://github.com/ava-labs/hypersdk).

The following settings will be used:

- `<repoUrl>` `https://github.com/ava-labs/hypersdk/`
- `<branch>` `vryx-poc`
- `<buildScript>` `examples/morpheusvm/scripts/build.sh`
- `<genesisPath>` [Genesis File](/docs/tooling/create-avalanche-nodes/deploy-custom-vm#genesis-file)
- `<chainConfigPath>` [Blockchain Config](/docs/tooling/create-avalanche-nodes/deploy-custom-vm#blockchain-config)
- `<subnetConfigPath>` [Avalanche L1 Config](/docs/tooling/create-avalanche-nodes/deploy-custom-vm#avalanche-l1-config)
- `<avagoConfigPath>` [AvalancheGo Config](/docs/tooling/create-avalanche-nodes/deploy-custom-vm#avalanchego-flags)

To spin up a Devnet with 5 validator nodes and 1 API node in 5 regions each
(us-west-2,us-east-1,ap-south-1,ap-northeast-1,eu-west-1) in AWS with each node having spec of
c7g.8xlarge AWS EC2 instance type and io2 volume type, with the Custom VM based Avalanche L1 
`<blockchainName>` deployed into the Devnet, we will run :

```bash
avalanche node devnet wiz <clusterName> <blockchainName> --custom-subnet \
  --subnet-genesis <genesisPath> --custom-vm-repo-url <repoUrl> \
  --custom-vm-branch <branch> --custom-vm-build-script <buildScript> \
  --chain-config <chainConfigPath> --subnet-config <subnetConfigPath> \
  --node-config <avagoConfigPath> --authorize-access --aws --num-apis 1,1,1,1,1 \
  --num-validators 5,5,5,5,5  --region us-west-2,us-east-1,ap-south-1,ap-northeast-1,eu-west-1 \
  --default-validator-params --node-type default

Creating the subnet
...
Creating the devnet
...
Waiting for node(s) in cluster <clusterName> to be healthy...
...
Nodes healthy after 33 seconds

Deploying the subnet
...
Setting the nodes as subnet trackers
...
Waiting for node(s) in cluster <clusterName>to be healthy...
Nodes healthy after 33 seconds
...
Waiting for node(s) in cluster <clusterName> to be syncing subnet <blockchainName>...
Nodes Syncing <blockchainName> after 5 seconds

Adding nodes as subnet validators
...
Waiting for node(s) in cluster <clusterName> to be validating subnet <blockchainName>...
Nodes Validating <blockchainName> after 23 seconds

Devnet <clusterName> has been created and is validating subnet <blockchainName>!
```

# Terminate All Nodes (/docs/tooling/avalanche-cli/create-avalanche-nodes/stop-node)

---
title: Terminate All Nodes
description: This page provides instructions for terminating cloud server nodes created by Avalanche-CLI.
---

<Callout type="warn">
ALPHA WARNING: This command is currently in experimental mode. Proceed at your own risk.
</Callout>

Terminating All Nodes[​](#terminating-all-nodes "Direct link to heading")
-------------------------------------------------------------------------

To terminate all nodes in a cluster, run:

```bash
avalanche node destroy <clusterName>
```

<Callout type="warn">
ALPHA WARNING: This command will delete all files associated with the cloud servers in the cluster. This includes the downloaded `staker.crt` and `staker.key` files in your local `.avalanche-cli` directory (which are used to back up your node). More info about node backup can be found [here](/docs/nodes/maintain/backup-restore).
</Callout>

Once completed, the instance set up on AWS / GCP would have been terminated and the Static Public IP associated with it would have been released.

# Validate the Primary Network (/docs/tooling/avalanche-cli/create-avalanche-nodes/validate-primary-network)

---
title: Validate the Primary Network
description: This page demonstrates how to configure nodes to validate the Primary Network. Validation via Avalanche-CLI is currently only supported on Fuji.
---

<Callout type="warn">
ALPHA WARNING: This command is currently in experimental mode. Proceed at your own risk.
</Callout>

## Prerequisites

Before we begin, you will need to have:

- Created a Cloud Server node as described for [AWS](/docs/tooling/create-avalanche-nodes/run-validators-aws) or [GCP](/docs/tooling/create-avalanche-nodes/run-validators-gcp)
- A node bootstrapped to the Primary Network (run `avalanche node status <clusterName>`to check bootstrap status as described [here](/docs/tooling/create-avalanche-nodes/run-validators-aws#check-bootstrap-status)
- Stored key / Ledger with AVAX to pay for gas fess associated with adding node as Primary Network. Instructions on how to fund stored key on Fuji can be found [here](/docs/tooling/create-deploy-avalanche-l1s/deploy-on-fuji-testnet#funding-the-key).

Be a Primary Network Validator[​](#be-a-primary-network-validator "Direct link to heading")
-------------------------------------------------------------------------------------------

Once all nodes in a cluster are bootstrapped to Primary Network, we can now have the nodes be Primary Network Validators.

To have all nodes in cluster `clusterName` be Primary Network Validators, run:

```bash
avalanche node validate primary <clusterName>
```

The nodes will start validating the Primary Network 20 seconds after the command is run.

The wizard will ask us how we want to pay for the transaction fee. Choose `Use stored key` for Fuji:

```bash
 Which key source should be used to pay transaction fees?:
  ▸ Use stored key
    Use ledger
```

Once you have selected the key to pay with, choose how many AVAX you would like to stake in the validator. Default is the minimum amount of AVAX that can be staked in a Fuji Network Validator. More info regarding minimum staking amount in different networks can be found [here](/docs/nodes/validate/how-to-stake#fuji-testnet).

```bash
 What stake weight would you like to assign to the validator?:
  ▸ Default (1.00 AVAX)
    Custom
```

Next, choose how long the node will be validating for:

```bash
 How long should your validator validate for?:
  ▸ Minimum staking duration on primary network
    Custom
```

Once all the inputs are completed you will see transaction IDs indicating that all the nodes in the cluster will be Primary Network Validators once the start time has elapsed.

# On Local Network (/docs/tooling/avalanche-cli/create-deploy-avalanche-l1s/deploy-locally)

---
title: On Local Network
description: This guide shows you how to deploy an Avalanche L1 to a local Avalanche network.
---

This how-to guide focuses on taking an already created Avalanche L1 configuration and deploying it to a local Avalanche network.

## Prerequisites

- [Avalanche-CLI installed](/docs/tooling/get-avalanche-cli)
- You have [created an Avalanche L1 configuration](/docs/tooling/create-avalanche-l1#create-your-avalanche-l1-configuration)

Deploying Avalanche L1s Locally[​](#deploying-avalanche-l1s-locally "Direct link to heading")
---------------------------------------------------------------------------------

In the following commands, make sure to substitute the name of your Avalanche L1 configuration for `<blockchainName>`.

To deploy your Avalanche L1, run:

```bash
avalanche blockchain deploy <blockchainName>
```

and select `Local Network` to deploy on. Alternatively, you can bypass this prompt by providing the `--local` flag. For example:

```bash
avalanche blockchain deploy <blockchainName> --local
```

The command may take a couple minutes to run.

Note: If you run `bash` on your shell and are running Avalanche-CLI on ARM64 on Mac, you will require Rosetta 2 to be able to deploy Avalanche L1s locally. You can download Rosetta 2 using `softwareupdate --install-rosetta` .

### Results[​](#results "Direct link to heading")

If all works as expected, the command output should look something like this:

```bash
> avalanche blockchain deploy myblockchain

✔ Local Network
Deploying [myblockchain] to Local Network

AvalancheGo path: /Users/felipe.madero/.avalanche-cli/bin/avalanchego/avalanchego-v1.13.0/avalanchego

Booting Network. Wait until healthy...

Node logs directory: /Users/felipe.madero/.avalanche-cli/runs/network_20250410_104205/<NodeID>/logs

Network ready to use.

Using [P-custom18jma8ppw3nhx5r4ap8clazz0dps7rv5u9xde7p] to be set as a change owner for leftover AVAX
AvalancheGo path: /Users/felipe.madero/.avalanche-cli/bin/avalanchego/avalanchego-v1.13.0/avalanchego

✓ Local cluster myblockchain-local-node-local-network not found. Creating...
Starting local avalanchego node using root: /Users/felipe.madero/.avalanche-cli/local/myblockchain-local-node-local-network ...
✓ Booting Network. Wait until healthy...
✓ Avalanchego started and ready to use from /Users/felipe.madero/.avalanche-cli/local/myblockchain-local-node-local-network

Node logs directory: /Users/felipe.madero/.avalanche-cli/local/myblockchain-local-node-local-network/<NodeID>/logs

Network ready to use.

URI: http://127.0.0.1:60172
NodeID: NodeID-NuQc8BQ8mV9TVksgMtpyc57VnWzU2J6aN

Your blockchain control keys: [P-custom18jma8ppw3nhx5r4ap8clazz0dps7rv5u9xde7p]
Your blockchain auth keys for chain creation: [P-custom18jma8ppw3nhx5r4ap8clazz0dps7rv5u9xde7p]
CreateSubnetTx fee: 0.000010278 AVAX
Blockchain has been created with ID: 2W9boARgCWL25z6pMFNtkCfNA5v28VGg9PmBgUJfuKndEdhrvw
Now creating blockchain...
CreateChainTx fee: 0.000129564 AVAX
+--------------------------------------------------------------------+
|                         DEPLOYMENT RESULTS                         |
+---------------+----------------------------------------------------+
| Chain Name    | myblockchain                                       |
+---------------+----------------------------------------------------+
| Subnet ID     | 2W9boARgCWL25z6pMFNtkCfNA5v28VGg9PmBgUJfuKndEdhrvw |
+---------------+----------------------------------------------------+
| VM ID         | qDNV9vtxZYYNqm7TN1mYBuaaknLdefDbFK8bFmMLTJQJKaWjV  |
+---------------+----------------------------------------------------+
| Blockchain ID | Yt9d8RRW9JcoqfvyefqJJMX14HawtBc28J9CQspQKPkdonp1y  |
+---------------+                                                    |
| P-Chain TXID  |                                                    |
+---------------+----------------------------------------------------+
Now calling ConvertSubnetToL1Tx...
ConvertSubnetToL1Tx fee: 0.000036992 AVAX
ConvertSubnetToL1Tx ID: 2d2EE7AorEhfKLBtnDGnAtcDYMGfPbWnHYDpNDm3SopYg6VtpV
Waiting for the Subnet to be converted into a sovereign L1 ... 100% [===============]

Validator Manager Protocol: ACP99
Restarting node NodeID-NuQc8BQ8mV9TVksgMtpyc57VnWzU2J6aN to track newly deployed subnet/s
Waiting for blockchain Yt9d8RRW9JcoqfvyefqJJMX14HawtBc28J9CQspQKPkdonp1y to be bootstrapped
✓ Local Network successfully tracking myblockchain
✓ Checking if node is healthy...
✓ Node is healthy after 0 seconds
Initializing Proof of Authority Validator Manager contract on blockchain myblockchain ...
✓ Proof of Authority Validator Manager contract successfully initialized on blockchain myblockchain

Your L1 is ready for on-chain interactions.

RPC Endpoint: http://127.0.0.1:60172/ext/bc/Yt9d8RRW9JcoqfvyefqJJMX14HawtBc28J9CQspQKPkdonp1y/rpc
ICM Messenger successfully deployed to myblockchain (0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf)
ICM Registry successfully deployed to myblockchain (0xEc7018552DC7E197Af85f157515f5976b1A15B12)
ICM Messenger successfully deployed to c-chain (0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf)
ICM Registry successfully deployed to c-chain (0x17aB05351fC94a1a67Bf3f56DdbB941aE6c63E25)
✓ ICM is successfully deployed

Generating relayer config file at /Users/felipe.madero/.avalanche-cli/runs/network_20250410_104205/icm-relayer-config.json
Relayer version icm-relayer-v1.6.2
Executing Relayer
✓ Relayer is successfully deployed

+--------------------------------------------------------------------------------------------------------------------------------+
|                                                          MYBLOCKCHAIN                                                          |
+---------------+----------------------------------------------------------------------------------------------------------------+
| Name          | myblockchain                                                                                                   |
+---------------+----------------------------------------------------------------------------------------------------------------+
| VM ID         | qDNV9vtxZYYNqm7TN1mYBuaaknLdefDbFK8bFmMLTJQJKaWjV                                                              |
+---------------+----------------------------------------------------------------------------------------------------------------+
| VM Version    | v0.7.3                                                                                                         |
+---------------+----------------------------------------------------------------------------------------------------------------+
| Validation    | Proof Of Authority                                                                                             |
+---------------+--------------------------+-------------------------------------------------------------------------------------+
| Local Network | ChainID                  | 888                                                                                 |
|               +--------------------------+-------------------------------------------------------------------------------------+
|               | SubnetID                 | 2W9boARgCWL25z6pMFNtkCfNA5v28VGg9PmBgUJfuKndEdhrvw                                  |
|               +--------------------------+-------------------------------------------------------------------------------------+
|               | Owners (Threhold=1)      | P-custom18jma8ppw3nhx5r4ap8clazz0dps7rv5u9xde7p                                     |
|               +--------------------------+-------------------------------------------------------------------------------------+
|               | BlockchainID (CB58)      | Yt9d8RRW9JcoqfvyefqJJMX14HawtBc28J9CQspQKPkdonp1y                                   |
|               +--------------------------+-------------------------------------------------------------------------------------+
|               | BlockchainID (HEX)       | 0x48644613a5ef255fa171bf4773df668b57ea0ea9593df8927a6d9f32376a9c6f                  |
|               +--------------------------+-------------------------------------------------------------------------------------+
|               | RPC Endpoint             | http://127.0.0.1:60172/ext/bc/Yt9d8RRW9JcoqfvyefqJJMX14HawtBc28J9CQspQKPkdonp1y/rpc |
+---------------+--------------------------+-------------------------------------------------------------------------------------+

+------------------------------------------------------------------------------------+
|                                         ICM                                        |
+---------------+-----------------------+--------------------------------------------+
| Local Network | ICM Messenger Address | 0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf |
|               +-----------------------+--------------------------------------------+
|               | ICM Registry Address  | 0xEc7018552DC7E197Af85f157515f5976b1A15B12 |
+---------------+-----------------------+--------------------------------------------+

+--------------------------+
|           TOKEN          |
+--------------+-----------+
| Token Name   | TST Token |
+--------------+-----------+
| Token Symbol | TST       |
+--------------+-----------+

+---------------------------------------------------------------------------------------------------------------------------------------+
|                                                        INITIAL TOKEN ALLOCATION                                                       |
+-------------------------+------------------------------------------------------------------+--------------+---------------------------+
| DESCRIPTION             | ADDRESS AND PRIVATE KEY                                          | AMOUNT (TST) | AMOUNT (WEI)              |
+-------------------------+------------------------------------------------------------------+--------------+---------------------------+
| Main funded account     | 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC                       | 1000000      | 1000000000000000000000000 |
| ewoq                    | 56289e99c94b6912bfc12adc093c9b51124f0dc54ac7a766b2bc5ccf558d8027 |              |                           |
+-------------------------+------------------------------------------------------------------+--------------+---------------------------+
| Used by ICM             | 0xf34408C05e3B339B1c89d15163d4B9D96845597A                       | 600          | 600000000000000000000     |
| cli-teleporter-deployer | 30d57c7b6e7e393e2e4ce8166768b497cc37930361a15b1c647d6e665d88afff |              |                           |
+-------------------------+------------------------------------------------------------------+--------------+---------------------------+

+----------------------------------------------------------------------------------------------------------------------------------+
|                                                          SMART CONTRACTS                                                         |
+----------------------------------------+--------------------------------------------+--------------------------------------------+
| DESCRIPTION                            | ADDRESS                                    | DEPLOYER                                   |
+----------------------------------------+--------------------------------------------+--------------------------------------------+
| Validator Messages Lib                 | 0x9C00629cE712B0255b17A4a657171Acd15720B8C |                                            |
+----------------------------------------+--------------------------------------------+--------------------------------------------+
| Proxy Admin                            | 0xC0fFEE1234567890aBCdeF1234567890abcDef34 | 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC |
+----------------------------------------+--------------------------------------------+--------------------------------------------+
| ACP99 Compatible PoA Validator Manager | 0x0C0DEbA5E0000000000000000000000000000000 |                                            |
+----------------------------------------+--------------------------------------------+--------------------------------------------+
| Transparent Proxy                      | 0x0Feedc0de0000000000000000000000000000000 |                                            |
+----------------------------------------+--------------------------------------------+--------------------------------------------+

+----------------------------------------------------------------------+
|                      INITIAL PRECOMPILE CONFIGS                      |
+------------+-----------------+-------------------+-------------------+
| PRECOMPILE | ADMIN ADDRESSES | MANAGER ADDRESSES | ENABLED ADDRESSES |
+------------+-----------------+-------------------+-------------------+
| Warp       | n/a             | n/a               | n/a               |
+------------+-----------------+-------------------+-------------------+

+-------------------------------------------------------------------------------------------------+
|                                      MYBLOCKCHAIN RPC URLS                                      |
+-----------+-------------------------------------------------------------------------------------+
| Localhost | http://127.0.0.1:60172/ext/bc/Yt9d8RRW9JcoqfvyefqJJMX14HawtBc28J9CQspQKPkdonp1y/rpc |
+-----------+-------------------------------------------------------------------------------------+

+------------------------------------------------------------------+
|                           PRIMARY NODES                          |
+------------------------------------------+-----------------------+
| NODE ID                                  | LOCALHOST ENDPOINT    |
+------------------------------------------+-----------------------+
| NodeID-7Xhw2mDxuDS44j42TCB6U5579esbSt3Lg | http://127.0.0.1:9650 |
+------------------------------------------+-----------------------+
| NodeID-MFrZFVCXPv5iCn6M9K6XduxGTYp891xXZ | http://127.0.0.1:9652 |
+------------------------------------------+-----------------------+
+----------------------------------------------------------------------------------+
|                                     L1 NODES                                     |
+------------------------------------------+------------------------+--------------+
| NODE ID                                  | LOCALHOST ENDPOINT     | L1           |
+------------------------------------------+------------------------+--------------+
| NodeID-NuQc8BQ8mV9TVksgMtpyc57VnWzU2J6aN | http://127.0.0.1:60172 | myblockchain |
+------------------------------------------+------------------------+--------------+

+-------------------------------------------------------------------------------------------------------+
|                                           WALLET CONNECTION                                           |
+-----------------+-------------------------------------------------------------------------------------+
| Network RPC URL | http://127.0.0.1:60172/ext/bc/Yt9d8RRW9JcoqfvyefqJJMX14HawtBc28J9CQspQKPkdonp1y/rpc |
+-----------------+-------------------------------------------------------------------------------------+
| Network Name    | myblockchain                                                                        |
+-----------------+-------------------------------------------------------------------------------------+
| Chain ID        | 888                                                                                 |
+-----------------+-------------------------------------------------------------------------------------+
| Token Symbol    | TST                                                                                 |
+-----------------+-------------------------------------------------------------------------------------+
| Token Name      | TST Token                                                                           |
+-----------------+-------------------------------------------------------------------------------------+
✓ L1 is successfully deployed on Local Network
```

You can use the deployment details to connect to and interact with your Avalanche L1.

Deploying Avalanche L1s Locally[​](#deploying-avalanche-l1s-locally)
---------------------------------------------------------------------------------

To deploy your Avalanche L1, run:

```bash
avalanche blockchain deploy myblockchain
```

Make sure to substitute the name of your Avalanche L1 if you used a different one than `myblockchain`.

```bash
? Choose a network for the operation: 
  ▸ Local Network
    Devnet
    Etna Devnet
    Fuji Testnet
    Mainnet
```

Next, select `Local Network`.

This command boots a three node Avalanche network on your machine:

- Two nodes to act as primary validators for the local network, that will validate the local P and C chains (unrelated to testnet/mainnet)..
- One node to act as sovereign validator for the new L1 that is deployed into the local network.

The command needs to download the latest versions of AvalancheGo and Subnet-EVM. It may take a couple minutes to run.

Note: If you run `bash` on your shell and are running Avalanche-CLI on ARM64 on Mac, you will require Rosetta 2 to be able to deploy Avalanche L1s locally. You can download Rosetta 2 using `softwareupdate --install-rosetta` .

If all works as expected, the command output should look something like this:

```bash
avalanche blockchain deploy myblockchain

# output
✔ Local Network
Deploying [myblockchain] to Local Network

AvalancheGo path: /Users/felipe.madero/.avalanche-cli/bin/avalanchego/avalanchego-v1.13.0/avalanchego

Booting Network. Wait until healthy...

Node logs directory: /Users/felipe.madero/.avalanche-cli/runs/network_20250410_104205/<NodeID>/logs

Network ready to use.

Using [P-custom18jma8ppw3nhx5r4ap8clazz0dps7rv5u9xde7p] to be set as a change owner for leftover AVAX
AvalancheGo path: /Users/felipe.madero/.avalanche-cli/bin/avalanchego/avalanchego-v1.13.0/avalanchego

✓ Local cluster myblockchain-local-node-local-network not found. Creating...
Starting local avalanchego node using root: /Users/felipe.madero/.avalanche-cli/local/myblockchain-local-node-local-network ...
✓ Booting Network. Wait until healthy...
✓ Avalanchego started and ready to use from /Users/felipe.madero/.avalanche-cli/local/myblockchain-local-node-local-network

Node logs directory: /Users/felipe.madero/.avalanche-cli/local/myblockchain-local-node-local-network/<NodeID>/logs

Network ready to use.

URI: http://127.0.0.1:60172
NodeID: NodeID-NuQc8BQ8mV9TVksgMtpyc57VnWzU2J6aN

Your blockchain control keys: [P-custom18jma8ppw3nhx5r4ap8clazz0dps7rv5u9xde7p]
Your blockchain auth keys for chain creation: [P-custom18jma8ppw3nhx5r4ap8clazz0dps7rv5u9xde7p]
CreateSubnetTx fee: 0.000010278 AVAX
Blockchain has been created with ID: 2W9boARgCWL25z6pMFNtkCfNA5v28VGg9PmBgUJfuKndEdhrvw
Now creating blockchain...
CreateChainTx fee: 0.000129564 AVAX
+--------------------------------------------------------------------+
|                         DEPLOYMENT RESULTS                         |
+---------------+----------------------------------------------------+
| Chain Name    | myblockchain                                       |
+---------------+----------------------------------------------------+
| Subnet ID     | 2W9boARgCWL25z6pMFNtkCfNA5v28VGg9PmBgUJfuKndEdhrvw |
+---------------+----------------------------------------------------+
| VM ID         | qDNV9vtxZYYNqm7TN1mYBuaaknLdefDbFK8bFmMLTJQJKaWjV  |
+---------------+----------------------------------------------------+
| Blockchain ID | Yt9d8RRW9JcoqfvyefqJJMX14HawtBc28J9CQspQKPkdonp1y  |
+---------------+                                                    |
| P-Chain TXID  |                                                    |
+---------------+----------------------------------------------------+
Now calling ConvertSubnetToL1Tx...
ConvertSubnetToL1Tx fee: 0.000036992 AVAX
ConvertSubnetToL1Tx ID: 2d2EE7AorEhfKLBtnDGnAtcDYMGfPbWnHYDpNDm3SopYg6VtpV
Waiting for the Subnet to be converted into a sovereign L1 ... 100% [===============]

Validator Manager Protocol: ACP99
Restarting node NodeID-NuQc8BQ8mV9TVksgMtpyc57VnWzU2J6aN to track newly deployed subnet/s
Waiting for blockchain Yt9d8RRW9JcoqfvyefqJJMX14HawtBc28J9CQspQKPkdonp1y to be bootstrapped
✓ Local Network successfully tracking myblockchain
✓ Checking if node is healthy...
✓ Node is healthy after 0 seconds
Initializing Proof of Authority Validator Manager contract on blockchain myblockchain ...
✓ Proof of Authority Validator Manager contract successfully initialized on blockchain myblockchain

Your L1 is ready for on-chain interactions.

RPC Endpoint: http://127.0.0.1:60172/ext/bc/Yt9d8RRW9JcoqfvyefqJJMX14HawtBc28J9CQspQKPkdonp1y/rpc
ICM Messenger successfully deployed to myblockchain (0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf)
ICM Registry successfully deployed to myblockchain (0xEc7018552DC7E197Af85f157515f5976b1A15B12)
ICM Messenger successfully deployed to c-chain (0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf)
ICM Registry successfully deployed to c-chain (0x17aB05351fC94a1a67Bf3f56DdbB941aE6c63E25)
✓ ICM is successfully deployed

Generating relayer config file at /Users/felipe.madero/.avalanche-cli/runs/network_20250410_104205/icm-relayer-config.json
Relayer version icm-relayer-v1.6.2
Executing Relayer
✓ Relayer is successfully deployed

+--------------------------------------------------------------------------------------------------------------------------------+
|                                                          MYBLOCKCHAIN                                                          |
+---------------+----------------------------------------------------------------------------------------------------------------+
| Name          | myblockchain                                                                                                   |
+---------------+----------------------------------------------------------------------------------------------------------------+
| VM ID         | qDNV9vtxZYYNqm7TN1mYBuaaknLdefDbFK8bFmMLTJQJKaWjV                                                              |
+---------------+----------------------------------------------------------------------------------------------------------------+
| VM Version    | v0.7.3                                                                                                         |
+---------------+----------------------------------------------------------------------------------------------------------------+
| Validation    | Proof Of Authority                                                                                             |
+---------------+--------------------------+-------------------------------------------------------------------------------------+
| Local Network | ChainID                  | 888                                                                                 |
|               +--------------------------+-------------------------------------------------------------------------------------+
|               | SubnetID                 | 2W9boARgCWL25z6pMFNtkCfNA5v28VGg9PmBgUJfuKndEdhrvw                                  |
|               +--------------------------+-------------------------------------------------------------------------------------+
|               | Owners (Threhold=1)      | P-custom18jma8ppw3nhx5r4ap8clazz0dps7rv5u9xde7p                                     |
|               +--------------------------+-------------------------------------------------------------------------------------+
|               | BlockchainID (CB58)      | Yt9d8RRW9JcoqfvyefqJJMX14HawtBc28J9CQspQKPkdonp1y                                   |
|               +--------------------------+-------------------------------------------------------------------------------------+
|               | BlockchainID (HEX)       | 0x48644613a5ef255fa171bf4773df668b57ea0ea9593df8927a6d9f32376a9c6f                  |
|               +--------------------------+-------------------------------------------------------------------------------------+
|               | RPC Endpoint             | http://127.0.0.1:60172/ext/bc/Yt9d8RRW9JcoqfvyefqJJMX14HawtBc28J9CQspQKPkdonp1y/rpc |
+---------------+--------------------------+-------------------------------------------------------------------------------------+

+------------------------------------------------------------------------------------+
|                                         ICM                                        |
+---------------+-----------------------+--------------------------------------------+
| Local Network | ICM Messenger Address | 0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf |
|               +-----------------------+--------------------------------------------+
|               | ICM Registry Address  | 0xEc7018552DC7E197Af85f157515f5976b1A15B12 |
+---------------+-----------------------+--------------------------------------------+

+--------------------------+
|           TOKEN          |
+--------------+-----------+
| Token Name   | TST Token |
+--------------+-----------+
| Token Symbol | TST       |
+--------------+-----------+

+---------------------------------------------------------------------------------------------------------------------------------------+
|                                                        INITIAL TOKEN ALLOCATION                                                       |
+-------------------------+------------------------------------------------------------------+--------------+---------------------------+
| DESCRIPTION             | ADDRESS AND PRIVATE KEY                                          | AMOUNT (TST) | AMOUNT (WEI)              |
+-------------------------+------------------------------------------------------------------+--------------+---------------------------+
| Main funded account     | 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC                       | 1000000      | 1000000000000000000000000 |
| ewoq                    | 56289e99c94b6912bfc12adc093c9b51124f0dc54ac7a766b2bc5ccf558d8027 |              |                           |
+-------------------------+------------------------------------------------------------------+--------------+---------------------------+
| Used by ICM             | 0xf34408C05e3B339B1c89d15163d4B9D96845597A                       | 600          | 600000000000000000000     |
| cli-teleporter-deployer | 30d57c7b6e7e393e2e4ce8166768b497cc37930361a15b1c647d6e665d88afff |              |                           |
+-------------------------+------------------------------------------------------------------+--------------+---------------------------+

+----------------------------------------------------------------------------------------------------------------------------------+
|                                                          SMART CONTRACTS                                                         |
+----------------------------------------+--------------------------------------------+--------------------------------------------+
| DESCRIPTION                            | ADDRESS                                    | DEPLOYER                                   |
+----------------------------------------+--------------------------------------------+--------------------------------------------+
| Validator Messages Lib                 | 0x9C00629cE712B0255b17A4a657171Acd15720B8C |                                            |
+----------------------------------------+--------------------------------------------+--------------------------------------------+
| Proxy Admin                            | 0xC0fFEE1234567890aBCdeF1234567890abcDef34 | 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC |
+----------------------------------------+--------------------------------------------+--------------------------------------------+
| ACP99 Compatible PoA Validator Manager | 0x0C0DEbA5E0000000000000000000000000000000 |                                            |
+----------------------------------------+--------------------------------------------+--------------------------------------------+
| Transparent Proxy                      | 0x0Feedc0de0000000000000000000000000000000 |                                            |
+----------------------------------------+--------------------------------------------+--------------------------------------------+

+----------------------------------------------------------------------+
|                      INITIAL PRECOMPILE CONFIGS                      |
+------------+-----------------+-------------------+-------------------+
| PRECOMPILE | ADMIN ADDRESSES | MANAGER ADDRESSES | ENABLED ADDRESSES |
+------------+-----------------+-------------------+-------------------+
| Warp       | n/a             | n/a               | n/a               |
+------------+-----------------+-------------------+-------------------+

+-------------------------------------------------------------------------------------------------+
|                                      MYBLOCKCHAIN RPC URLS                                      |
+-----------+-------------------------------------------------------------------------------------+
| Localhost | http://127.0.0.1:60172/ext/bc/Yt9d8RRW9JcoqfvyefqJJMX14HawtBc28J9CQspQKPkdonp1y/rpc |
+-----------+-------------------------------------------------------------------------------------+

+------------------------------------------------------------------+
|                           PRIMARY NODES                          |
+------------------------------------------+-----------------------+
| NODE ID                                  | LOCALHOST ENDPOINT    |
+------------------------------------------+-----------------------+
| NodeID-7Xhw2mDxuDS44j42TCB6U5579esbSt3Lg | http://127.0.0.1:9650 |
+------------------------------------------+-----------------------+
| NodeID-MFrZFVCXPv5iCn6M9K6XduxGTYp891xXZ | http://127.0.0.1:9652 |
+------------------------------------------+-----------------------+
+----------------------------------------------------------------------------------+
|                                     L1 NODES                                     |
+------------------------------------------+------------------------+--------------+
| NODE ID                                  | LOCALHOST ENDPOINT     | L1           |
+------------------------------------------+------------------------+--------------+
| NodeID-NuQc8BQ8mV9TVksgMtpyc57VnWzU2J6aN | http://127.0.0.1:60172 | myblockchain |
+------------------------------------------+------------------------+--------------+

+-------------------------------------------------------------------------------------------------------+
|                                           WALLET CONNECTION                                           |
+-----------------+-------------------------------------------------------------------------------------+
| Network RPC URL | http://127.0.0.1:60172/ext/bc/Yt9d8RRW9JcoqfvyefqJJMX14HawtBc28J9CQspQKPkdonp1y/rpc |
+-----------------+-------------------------------------------------------------------------------------+
| Network Name    | myblockchain                                                                        |
+-----------------+-------------------------------------------------------------------------------------+
| Chain ID        | 888                                                                                 |
+-----------------+-------------------------------------------------------------------------------------+
| Token Symbol    | TST                                                                                 |
+-----------------+-------------------------------------------------------------------------------------+
| Token Name      | TST Token                                                                           |
+-----------------+-------------------------------------------------------------------------------------+
✓ L1 is successfully deployed on Local Network
```

To manage the newly deployed local Avalanche network, see [the `avalanche network` command tree](/docs/tooling/cli-commands#avalanche-network).

You can use the deployment details to connect to and interact with your Avalanche L1. Now it's time to interact with it.

## Interacting with Your Avalanche L1

You can use the value provided by `Browser Extension connection details` to connect to your Avalanche L1 with Core, MetaMask, or any other wallet.

<Callout title="Note">
To allow API calls from other machines, use `--http-host=0.0.0.0` in the config.
</Callout>

```bash
Browser Extension connection details (any node URL from above works):
RPC URL:          http://127.0.0.1:9650/ext/bc/2BK8CKA4Vfvi69TBTc5GW94JQ9nPiL8xPpPNeeckb9UFSPYedD/rpc
Funded address:   0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC with 1000000 (10^18) - private key: 56289e99c94b6912bfc12adc093c9b51124f0dc54ac7a766b2bc5ccf558d8027
Network name:     myblockchain
Chain ID:         888
Currency Symbol:  TST
```

This tutorial uses Core.

### Importing the Test Private Key[​](#importing-the-test-private-key)

<Callout type="warn">
This address derives from a well-known private key. Anyone can steal funds sent to this address. Only use it on development networks that only you have access to. If you send production funds to this address, attackers may steal them instantly.
</Callout>

First, you need to import your airdrop private key into Core.

In the Accounts screen, select the `Imported` tab. Click on `Import private key`.

![](/images/deploy-subnet1.png)

Here, enter the private key. Import the well-known private key `0x56289e99c94b6912bfc12adc093c9b51124f0dc54ac7a766b2bc5ccf558d8027`.

![](/images/deploy-subnet2.png)

Next, rename the Core account to prevent confusion. On the `Imported` tab, click on the pen icon next to your account. Rename the account `DO NOT USE -- Public test key` to prevent confusion with any personal wallets.

![Rename Account](/images/deploy-subnet3.png)

![Rename Account](/images/deploy-subnet4.png)

### Connect to the Avalanche L1[​](#connect-to-the-avalanche-l1)

Next, you need to add your Avalanche L1 to Core's networks.

In the Core Extension click, `See All Networks` and then select the `+` icon in the top right.

![Add network](/images/deploy-subnet5.png)

Enter your Avalanche L1's details, found in the output of your `avalanche blockchain deploy` [command](#deploying-avalanche-l1s-locally), into the form and click `Save`.

![Add network 2](/images/deploy-subnet6.png)

If all worked as expected, your balance should read 1 million tokens. Your Avalanche L1 is ready for action. You might want to try to [Deploy a Smart Contract on Your Subnet-EVM Using Remix and Core](/docs/avalanche-l1s/add-utility/deploy-smart-contract).

![Avalanche L1 in Core](/images/deploy-subnet7.png)

## Deploying Multiple Avalanche L1s[​](#deploying-multiple-avalanche-l1s "Direct link to heading")

You may deploy multiple Avalanche L1s concurrently, but you can't deploy the same Avalanche L1 multiple times without resetting all deployed Avalanche L1 state.

## Redeploying the Avalanche L1

To redeploy the Avalanche L1, you first need to wipe the Avalanche L1 state. This permanently deletes all data from all locally deployed Avalanche L1s. To do so, run

```bash
avalanche network clean
```

You are now free to redeploy your Avalanche L1 with

```bash
avalanche blockchain deploy <blockchainName> --local
```

## Stopping the Local Network

To gracefully stop a running local network while preserving state, run:

```bash
avalanche network stop

# output
Network stopped successfully.
```

When restarted, all of your deployed Avalanche L1s resume where they left off.

### Resuming the Local Network

To resume a stopped network, run:

```bash
avalanche network start

# output
Starting previously deployed and stopped snapshot
Booting Network. Wait until healthy...
...............
Network ready to use. Local network node endpoints:
+-------+----------+------------------------------------------------------------------------------------+
| NODE  |    VM    |                                        URL                                         |
+-------+----------+------------------------------------------------------------------------------------+
| node5 | myblockchain | http://127.0.0.1:9658/ext/bc/SPqou41AALqxDquEycNYuTJmRvZYbfoV9DYApDJVXKXuwVFPz/rpc |
+-------+----------+------------------------------------------------------------------------------------+
| node1 | myblockchain | http://127.0.0.1:9650/ext/bc/SPqou41AALqxDquEycNYuTJmRvZYbfoV9DYApDJVXKXuwVFPz/rpc |
+-------+----------+------------------------------------------------------------------------------------+
| node2 | myblockchain | http://127.0.0.1:9652/ext/bc/SPqou41AALqxDquEycNYuTJmRvZYbfoV9DYApDJVXKXuwVFPz/rpc |
+-------+----------+------------------------------------------------------------------------------------+
| node3 | myblockchain | http://127.0.0.1:9654/ext/bc/SPqou41AALqxDquEycNYuTJmRvZYbfoV9DYApDJVXKXuwVFPz/rpc |
+-------+----------+------------------------------------------------------------------------------------+
| node4 | myblockchain | http://127.0.0.1:9656/ext/bc/SPqou41AALqxDquEycNYuTJmRvZYbfoV9DYApDJVXKXuwVFPz/rpc |
+-------+----------+------------------------------------------------------------------------------------+
```

The network resumes with the same state it paused with.

## Next Steps

After you feel comfortable with this deployment flow, try deploying smart contracts on your chain with [Remix](https://remix.ethereum.org/), [Hardhat](https://hardhat.org/), or [Foundry](https://github.com/foundry-rs/foundry). You can also experiment with customizing your Avalanche L1 by addingprecompiles or adjusting the airdrop.

Once you've developed a stable Avalanche L1 you like, see [Create an EVM Avalanche L1 on Fuji Testnet](/docs/avalanche-l1s/upgrade/customize-avalanche-l1) to take your Avalanche L1 one step closer to production.

## FAQ

**How is the Avalanche L1 ID (SubnetID) determined upon creation?**

The Avalanche L1 ID (SubnetID) is the hash of the transaction that created the Avalanche L1.


# On Fuji Testnet (/docs/tooling/avalanche-cli/create-deploy-avalanche-l1s/deploy-on-fuji-testnet)

---
title: On Fuji Testnet
description: This tutorial shows how to deploy an Avalanche L1 on Fuji Testnet.
---

<Callout title="Note">
This document describes how to use the new Avalanche-CLI to deploy an Avalanche L1 on `Fuji`.
</Callout>

After trying out an Avalanche L1 on a local box by following [this tutorial](/docs/tooling/create-deploy-avalanche-l1s/deploy-locally), next step is to try it out on `Fuji` Testnet.

In this article, it's shown how to do the following on `Fuji` Testnet.

- Create an Avalanche L1.
- Deploy a virtual machine based on Subnet-EVM.
- Join a node to the newly created Avalanche L1.
- Add a node as a validator to the Avalanche L1.

All IDs in this article are for illustration purposes. They can be different in your own run-through of this tutorial.

## Prerequisites

- [`Avalanche-CLI`](https://github.com/ava-labs/avalanche-cli) installed

Virtual Machine[​](#virtual-machine "Direct link to heading")
-------------------------------------------------------------

Avalanche can run multiple blockchains. Each blockchain is an instance of a [Virtual Machine](/docs/quick-start/virtual-machines), much like an object in an object-oriented language is an instance of a class. That's, the VM defines the behavior of the blockchain.

[Subnet-EVM](https://github.com/ava-labs/subnet-evm) is the VM that defines the Avalanche L1 Contract Chains. Subnet-EVM is a simplified version of [Avalanche C-Chain](https://github.com/ava-labs/coreth).

This chain implements the Ethereum Virtual Machine and supports Solidity smart contracts as well as most other Ethereum client features.


Avalanche-CLI[​](#avalanche-cli "Direct link to heading")
---------------------------------------------------------

If not yet installed, install `Avalanche-CLI` following the tutorial at [Avalanche-CLI installation](/docs/tooling/get-avalanche-cli)

### Private Key[​](#private-key "Direct link to heading")

All commands which issue a transaction require either a private key loaded into the tool, or a connected ledger device.

This tutorial focuses on stored key usage and leave ledger operation details for the `Mainnet` deploy one, as `Mainnet` operations requires ledger usage, while for `Fuji` it's optional.

`Avalanche-CLI` supports the following key operations:

- create
- delete
- export
- list

<Callout type="warn">
You should only use the private key created for this tutorial for testing operations on `Fuji` or other testnets. Don't use this key on `Mainnet`. CLI is going to store the key on your file system. Whoever gets access to that key is going to have access to all funds secured by that private key.
</Callout>

Run `create` if you don't have any private key available yet. You can create multiple named keys. Each command requiring a key is going to therefore require the appropriate key name you want to use.

```bash
avalanche key create mytestkey
```

This is going to generate a new key named `mytestkey`. The command is going to then also print addresses associated with the key:

```bash
Generating new key...
Key created
+-----------+-------------------------------+-------------------------------------------------+---------------+
| KEY NAME  |             CHAIN             |                     ADDRESS                     |    NETWORK    |
+-----------+-------------------------------+-------------------------------------------------+---------------+
| mytestkey | C-Chain (Ethereum hex format) | 0x86BB07a534ADF43786ECA5Dd34A97e3F96927e4F      | All           |
+           +-------------------------------+-------------------------------------------------+---------------+
|           | P-Chain (Bech32 format)       | P-custom1a3azftqvygc4tlqsdvd82wks2u7nx85rg7v8ta | Local Network |
+           +                               +-------------------------------------------------+---------------+
|           |                               | P-fuji1a3azftqvygc4tlqsdvd82wks2u7nx85rhk6zqh   | Fuji          |
+-----------+-------------------------------+-------------------------------------------------+---------------+
```

You may use the C-Chain address (`0x86BB07a534ADF43786ECA5Dd34A97e3F96927e4F`) to fund your key:
- **Recommended:** Create a [Builder Hub account](https://build.avax.network/login) and connect your wallet to receive testnet tokens automatically
- **Alternative:** Use the [external faucet](https://core.app/tools/testnet-faucet/)

The command also prints P-Chain addresses for both the default local network and `Fuji`. The latter (`P-fuji1a3azftqvygc4tlqsdvd82wks2u7nx85rhk6zqh`) is the one needed for this tutorial.

The `delete` command of course deletes a private key:

```bash
avalanche key delete mytestkey
```

Be careful though to always have a key available for commands involving transactions.

The `export` command is going to **print your private key** in hex format to stdout.

```bash
avalanche key export mytestkey
21940fbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb5f0b
```

This key is intentionally modified.

You can also **import** a key by using the `--file` flag with a path argument and also providing a name to it:

```bash
avalanche key create othertest --file /tmp/test.pk
Loading user key...
Key loaded
```

Finally, the `list` command is going to list all your keys in your system and their associated addresses (CLI stores the keys in a special directory on your file system, tampering with the directory is going to result in malfunction of the tool).

```bash
avalanche key list
+-----------+-------------------------------+-------------------------------------------------+---------------+
| KEY NAME  |             CHAIN             |                     ADDRESS                     |    NETWORK    |
+-----------+-------------------------------+-------------------------------------------------+---------------+
| othertest | C-Chain (Ethereum hex format) | 0x36c83263e33f9e87BB98D3fEb54a01E35a3Fa735      | All           |
+           +-------------------------------+-------------------------------------------------+---------------+
|           | P-Chain (Bech32 format)       | P-custom1n5n4h99j3nx8hdrv50v8ll7aldm383nap6rh42 | Local Network |
+           +                               +-------------------------------------------------+---------------+
|           |                               | P-fuji1n5n4h99j3nx8hdrv50v8ll7aldm383na7j4j7q   | Fuji          |
+-----------+-------------------------------+-------------------------------------------------+---------------+
| mytestkey | C-Chain (Ethereum hex format) | 0x86BB07a534ADF43786ECA5Dd34A97e3F96927e4F      | All           |
+           +-------------------------------+-------------------------------------------------+---------------+
|           | P-Chain (Bech32 format)       | P-custom1a3azftqvygc4tlqsdvd82wks2u7nx85rg7v8ta | Local Network |
+           +                               +-------------------------------------------------+---------------+
|           |                               | P-fuji1a3azftqvygc4tlqsdvd82wks2u7nx85rhk6zqh   | Fuji          |
+-----------+-------------------------------+-------------------------------------------------+---------------+
```

#### Funding the Key[​](#funding-the-key "Direct link to heading")

<Callout type="warn">
Do these steps only to follow this tutorial for `Fuji` addresses. To access the wallet for `Mainnet`, the use of a ledger device is strongly recommended.
</Callout>

1. A newly created key has no funds on it. You have several options to fund it:
   - **Recommended:** Create a [Builder Hub account](https://build.avax.network/login) and connect your wallet to receive testnet tokens automatically on C-Chain and P-Chain
   - **Alternative:** Use the [external faucet](https://core.app/tools/testnet-faucet/) with your C-Chain address. If you have an AVAX balance on Mainnet, you can request tokens directly. Otherwise, request a faucet coupon on [Guild](https://guild.xyz/avalanche) or contact admins/mods on [Discord](https://discord.com/invite/RwXY7P6)
2. Export your key via the `avalanche key export` command. The output is your private key, which will help you [import](https://support.avax.network/en/articles/6821877-core-extension-how-can-i-import-an-account) your account into the Core extension.
3. Connect Core extension to [Core web](https://core.app/), and move the test funds from C-Chain to the P-Chain by clicking Stake, then Cross-Chain Transfer (find more details on [this tutorial](https://support.avax.network/en/articles/8133713-core-web-how-do-i-make-cross-chain-transfers-in-core-stake)).

After following these 3 steps, your test key should now have a balance on the P-Chain on `Fuji` Testnet.

Create an EVM Avalanche L1[​](#create-an-evm-avalanche-l1 "Direct link to heading")
-----------------------------------------------------------------------

Creating an Avalanche L1 with `Avalanche-CLI` for `Fuji` works the same way as with a local network. In fact, the `create` commands only creates a specification of your Avalanche L1 on the local file system. Afterwards the Avalanche L1 needs to be _deployed_. This allows to reuse configs, by creating the config with the `create` command, then first deploying to a local network and successively to `Fuji` - and eventually to `Mainnet`.

To create an EVM Avalanche L1, run the `blockchain create` command with a name of your choice:

```bash
avalanche blockchain create testblockchain
```

This is going to start a series of prompts to customize your EVM Avalanche L1 to your needs. Most prompts have some validation to reduce issues due to invalid input. The first prompt asks for the type of the virtual machine (see [Virtual Machine](#virtual-machine)).

```bash
Use the arrow keys to navigate: ↓ ↑ → ←
? Choose your VM:
  ▸ SubnetEVM
    Custom
```

As you want to create an EVM Avalanche L1, just accept the default `Subnet-EVM`.

Choose either Proof of Authority (PoA) or Proof of Stake (PoS) as your consensus mechanism.

```bash
? Which validator management type would you like to use in your blockchain?:
  ▸ Proof Of Authority
    Proof Of Stake
    Explain the difference
```
For this tutorial, select `Proof of Authority (PoA)`.

For more info, reference the [Validator Management Contracts](/docs/avalanche-l1s/validator-manager/contract).

```bash
Which address do you want to enable as controller of ValidatorManager contract?:
  ▸ Get address from an existing stored key (created from avalanche key create or avalanche key import)
    Custom
```
This address will be able to add and remove validators from your Avalanche L1. You can either use an existing key or create a new one.
In addition to being the PoA owner, this address will also be the owner of the `ProxyAdmin` contract of the Validator Manager's `TransparentUpgradeableProxy`. This address will be able to upgrade (PoA -> PoS) the Validator Manager implementation through updating the proxy.

Next, CLI will ask for blockchain configuration values. Since we are deploying to Fuji, select `I want to use defaults for a production environment`.

```bash
? Do you want to use default values for the Blockchain configuration?:
  ▸ I want to use defaults for a test environment
    I want to use defaults for a production environment
    I don't want to use default values
    Explain the difference
```

The default values for production environment:

- Use latest Subnet-EVM release
- Allocate 1 million tokens to:
    1. **a newly created key (production)**: name of this key will be in the format of `subnet_blockchainName_airdrop`
    2. **ewoq address (test)**: 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC
- Supply of the native token will be hard-capped
- Set gas fee config as low throughput (12 million gas per block)
- Use constant gas prices
- Disable further adjustments in transaction fee configuration
- Transaction fees are burned
- Enable interoperability with other blockchains
- Allow any user to deploy smart contracts, send transactions, and interact with your blockchain.

Next, CLI asks for the ChainID. You should provide your own ID. Check [chainlist.org](https://chainlist.org/) to see if the value you'd like is already in use.

```bash
✔ Subnet-EVM
creating Avalanche L1 test blockchain
Enter your Avalanche L1's ChainId. It can be any positive integer.
ChainId: 3333
```

Now, provide a symbol of your choice for the token of this EVM:

```bash
Select a symbol for your Avalanche L1's native token
Token symbol: TST
```

It's possible to end the process with Ctrl-C at any time.

At this point, CLI creates the specification of the new Avalanche L1 on disk, but isn't deployed yet.

Print the specification to disk by running the `describe` command:

```bash
avalanche blockchain describe testblockchain
```

```bash
+------------------------------------------------------------------+
|                          TESTBLOCKCHAIN                          |
+------------+-----------------------------------------------------+
| Name       | testblockchain                                      |
+------------+-----------------------------------------------------+
| VM ID      | tGBrM94jbkesczgqsL1UaxjrdxRQQobs3MZTNQ4GrfhzvpiE8   |
+------------+-----------------------------------------------------+
| VM Version | v0.6.12                                             |
+------------+-----------------------------------------------------+
| Validation | Proof Of Authority                                  |
+------------+-----------------------------------------------------+

+--------------------------+
|           TOKEN          |
+--------------+-----------+
| Token Name   | TST Token |
+--------------+-----------+
| Token Symbol | TST       |
+--------------+-----------+

+-----------------------------------------------------------------------------------------------------------------------------------+
|                                                      INITIAL TOKEN ALLOCATION                                                     |
+---------------------+------------------------------------------------------------------+--------------+---------------------------+
| DESCRIPTION         | ADDRESS AND PRIVATE KEY                                          | AMOUNT (TST) | AMOUNT (WEI)              |
+---------------------+------------------------------------------------------------------+--------------+---------------------------+
| Main funded account | 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC                       | 1000000      | 1000000000000000000000000 |
| ewoq                | 56289e99c94b6912bfc12adc093c9b51124f0dc54ac7a766b2bc5ccf558d8027 |              |                           |
+---------------------+------------------------------------------------------------------+--------------+---------------------------+

+-----------------------------------------------------------------------------------------------------------------+
|                                                 SMART CONTRACTS                                                 |
+-----------------------+--------------------------------------------+--------------------------------------------+
| DESCRIPTION           | ADDRESS                                    | DEPLOYER                                   |
+-----------------------+--------------------------------------------+--------------------------------------------+
| Proxy Admin           | 0xC0fFEE1234567890aBCdeF1234567890abcDef34 | 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC |
+-----------------------+--------------------------------------------+--------------------------------------------+
| PoA Validator Manager | 0x0C0DEbA5E0000000000000000000000000000000 |                                            |
+-----------------------+--------------------------------------------+--------------------------------------------+
| Transparent Proxy     | 0x0Feedc0de0000000000000000000000000000000 |                                            |
+-----------------------+--------------------------------------------+--------------------------------------------+

+----------------------------------------------------------------------+
|                      INITIAL PRECOMPILE CONFIGS                      |
+------------+-----------------+-------------------+-------------------+
| PRECOMPILE | ADMIN ADDRESSES | MANAGER ADDRESSES | ENABLED ADDRESSES |
+------------+-----------------+-------------------+-------------------+
| Warp       | n/a             | n/a               | n/a               |
+------------+-----------------+-------------------+-------------------+

```


Deploy the Avalanche L1[​](#deploy-the-avalanche-l1 "Direct link to heading")
-----------------------------------------------------------------

<Callout title="Note">
To deploy the Avalanche L1, you will need some testnet AVAX on the P-chain.
</Callout>

To deploy the new Avalanche L1, run:

```bash
avalanche blockchain deploy testblockchain
```

This is going to start a new prompt series.

```bash
Use the arrow keys to navigate: ↓ ↑ → ←
? Choose a network to deploy on:
  ▸ Local Network
    Fuji
    Mainnet
```

This tutorial is about deploying to `Fuji`, so navigate with the arrow keys to `Fuji` and hit enter. The user is then asked to provide which private key to use for the deployment. Select a key to has P-Chain AVAX to pay for transaction fees.

Also, this tutorial assumes that a node is up running, fully bootstrapped on `Fuji`, and runs from the **same** box.

```bash
✔ Fuji
Deploying [testblockchain] to Fuji
Use the arrow keys to navigate: ↓ ↑ → ←
? Which private key should be used to issue the transaction?:
    test
  ▸ mytestkey
```

Avalanche L1s require bootstrap validators during creation process. Avalanche CLI has enabled using local machine as a bootstrap validator on the blockchain.
This means that you don't have to to set up a remote server on a cloud service (e.g. AWS / GCP) to be a validator on the blockchain.

We will select `Yes` on using our local machine as a bootstrap validator. Note that since we need to sync our node with Fuji, this process will take around 3 minutes.

```bash
You can use your local machine as a bootstrap validator on the blockchain
This means that you don't have to to set up a remote server on a cloud service (e.g. AWS / GCP) to be a validator on the blockchain.
Use the arrow keys to navigate: ↓ ↑ → ←
? Do you want to use your local machine as a bootstrap validator?:
  ▸ Yes
    No
```

Well done. You have just created your own Avalanche L1 on `Fuji`.

You will be able to see information on the deployed L1 at the end of `avalanche blockchain deploy` command:

```bash
+--------------------+----------------------------------------------------+
| DEPLOYMENT RESULTS |                                                    |
+--------------------+----------------------------------------------------+
| Chain Name         | testblockchain                                     |
+--------------------+----------------------------------------------------+
| Subnet ID          | 2cNuyBhvAd4jH5bFSGndezhB66Z4UHYAsLCMGoCpvhXVhrZfgd |
+--------------------+----------------------------------------------------+
| VM ID              | qcvkEX1zWSz7PtGd7CKvPRBqLVTzA7qyMPvkh5NMDWkuhrcCu  |
+--------------------+----------------------------------------------------+
| Blockchain ID      | 2U7vNdB78xTiN6QtZ9aetfKoGtQhfeEPQG6QZC8bpq8QMf4cDx |
+--------------------+                                                    +
| P-Chain TXID       |                                                    |
+--------------------+----------------------------------------------------+
```

To get your new Avalanche L1 information, visit the [Avalanche L1 Explorer](https://subnets-test.avax.network/). The search best works by blockchain ID, so in this example, enter `2U7vNdB78xTiN6QtZ9aetfKoGtQhfeEPQG6QZC8bpq8QMf4cDx` into the search box and you should see your shiny new blockchain information.

Add a Validator[​](#add-a-validator "Direct link to heading")
-------------------------------------------------------------

Before proceeding to add a validator to our Avalanche L1, we will need to have the validator's NodeID, BLS public key and proof of possession. These can be obtained by ssh into the node itself and run the `getNodeID` API specified [here](/docs/api-reference/info-api#infogetnodeid).

To add a validator to an Avalanche L1, the owner of the key that acts as the controller of `ValidatorManager` contract specified in `avalanche blockchain create` command above run:

```bash
avalanche blockchain addValidator testblockchain
```

Choose `Fuji`:

```bash
Use the arrow keys to navigate: ↓ ↑ → ←
? Choose a network to deploy on:
  ▸ Fuji
```

You will need to specify which private key to use to pay for the transaction fees:

```bash
Use the arrow keys to navigate: ↓ ↑ → ←
?  Which key should be used to pay for transaction fees on P-Chain?:
    test
  ▸ mytestkey
```

Now enter the **NodeID** of the new validator to be added.

```bash
What is the NodeID of the validator you'd like to whitelist?: NodeID-BFa1paAAAAAAAAAAAAAAAAAAAAQGjPhUy
```

Next, enter the node's BLS public key and proof of possession.

Now, enter the amount of AVAX that you would like to allocate to the new validator.

The validator's balance is used to pay for continuous fee to the P-Chain. When this Balance reaches 0, the validator will be considered inactive and will no longer participate in validating the L1.

1 AVAX should last the validator about a month.

```bash
What balance would you like to assign to the validator (in AVAX)?: 1
```

Next, select a key that will receive the leftover AVAX if the validator is removed from the L1:

```bash
 Which stored key should be used be set as a change owner for leftover AVAX?:
    test
  ▸ mytestkey
```

Next, select a key that can remove the validator:

```bash
? Which stored key should be used be able to disable the validator using P-Chain transactions?:
    test
  ▸ mytestkey
```

By the end of the command, you would have successfully added a new validator to the Avalanche L1 on Fuji Testnet!

Appendix[​](#appendix "Direct link to heading")
-----------------------------------------------

### Connect with Core[​](#connect-with-core "Direct link to heading")

To connect Core (or MetaMask) with your blockchain on the new Avalanche L1 running on your local computer, you can add a new network on your Core wallet with the following values:

```bash
- Network Name: testblockchain
- RPC URL: [http://127.0.0.1:9650/ext/bc/2U7vNdB78xTiN6QtZ9aetfKoGtQhfeEPQG6QZC8bpq8QMf4cDx/rpc]
- Chain ID: 3333
- Symbol: TST
```


# On Avalanche Mainnet (/docs/tooling/avalanche-cli/create-deploy-avalanche-l1s/deploy-on-mainnet)

---
title: On Avalanche Mainnet
description: Deploy an Avalanche L1 to Avalanche Mainnet
---
<Callout type="warn">
Deploying an Avalanche L1 to Mainnet has many risks. Doing so safely requires a laser focus on security. This tutorial does its best to point out common pitfalls, but there may be other risks not discussed here.

This tutorial is an educational resource and provides no guarantees that following it results in a secure deployment. Additionally, this tutorial takes some shortcuts that aid the understanding of the deployment process at the expense of security. The text highlights these shortcuts and they shouldn't be used for a production deployment.
</Callout>

After managing a successful Avalanche L1 deployment on the `Fuji Testnet`, you're ready to deploy your Avalanche L1 on Mainnet. If you haven't done so, first [Deploy an Avalanche L1 on Testnet](/docs/tooling/create-deploy-avalanche-l1s/deploy-on-fuji-testnet).

This tutorial shows how to do the following on `Mainnet`.

- Deploy an Avalanche L1.
- Add a node as a validator to the Avalanche L1.

<Callout title="Note">
All IDs in this article are for illustration purposes only. They are guaranteed to be different in your own run-through of this tutorial.
</Callout>

## Prerequisites

- An Avalanche node running and [fully bootstrapped](/docs/nodes) on `Mainnet`
- [Avalanche-CLI is installed](/docs/tooling/get-avalanche-cli) on each validator node's box
- A [Ledger](https://www.ledger.com/) device
- You've [created an Avalanche L1 configuration](/docs/tooling/create-avalanche-l1#create-your-avalanche-l1-configuration) and fully tested a [Fuji Testnet Avalanche L1 deployment](/docs/tooling/create-deploy-avalanche-l1s/deploy-on-fuji-testnet)

### Setting up Your Ledger[​](#setting-up-your-ledger "Direct link to heading")

In the interest of security, all Avalanche-CLI `Mainnet` operations require the use of a connected Ledger device. You must unlock your Ledger and run the Avalanche App. See [How to Use Ledger](https://support.avax.network/en/articles/6150237-how-to-use-a-ledger-nano-s-or-nano-x-with-avalanche) for help getting set up.

Ledger devices support TX signing for any address inside a sequence automatically generated by the device.

By default, Avalanche-CLI uses the first address of the derivation, and that address needs funds to issue the TXs to create the Avalanche L1 and add validators.

To get the first `Mainnet` address of your Ledger device, first make sure it is connected, unblocked, and running the Avalanche app. Then execute the `key list` command:

```bash
avalanche key list --ledger 0 --mainnet
```

```bash
+--------+---------+-------------------------+-----------------------------------------------+---------+---------+
|  KIND  |  NAME   |          CHAIN          |                    ADDRESS                    | BALANCE | NETWORK |
+--------+---------+-------------------------+-----------------------------------------------+---------+---------+
| ledger | index 0 | P-Chain (Bech32 format) | P-avax1ucykh6ls8thqpuwhg3vp8vvu6spg5e8tp8a25j |      11 | Mainnet |
+--------+---------+-------------------------+-----------------------------------------------+---------+---------+
```

The command prints the P-Chain address for `Mainnet`, `P-avax1ucykh6ls8thqpuwhg3vp8vvu6spg5e8tp8a25j`, and its balance.

<Callout title="Note">
You can use the `key list` command to get any Ledger address in the derivation sequence by changing the index parameter from `0` to the one desired, or to a list of them (for example: `2`, or `0,4,7`). Also, you can ask for addresses on `Mainnet` with the `--mainnet` parameter, and local networks with the `--local` parameter.
</Callout>

#### Funding the Ledger[​](#funding-the-ledger "Direct link to heading")

A new Ledger device has no funds on the addresses it controls. You'll need to send funds to it by exporting them from C-Chain to the P-Chain using [Core web](https://core.app/) connected to [Core extension](https://core.app/).

You can load the Ledger's C-Chain address in Core extension, or load in a different private key to [Core extension](https://core.app/), and then connect to Core web .

You can move test funds from the C-Chain to the P-Chain by clicking Stake on Core web , then Cross-Chain Transfer (find more details on [this tutorial](https://support.avax.network/en/articles/8133713-core-web-how-do-i-make-cross-chain-transfers-in-core-stake)).

Deploy the Avalanche L1[​](#deploy-the-avalanche-l1 "Direct link to heading")
-----------------------------------------------------------------

<Callout title="Note">
To deploy the Avalanche L1, you will need some AVAX on the P-Chain.
</Callout>

For our Fuji example, we used our local machine as a bootstrap validator. However, since bootstrapping a node to Mainnet will take several hours,
we will use an Avalanche node set up on an AWS server that is already bootstrapped to Mainnet for this example.

To check if the Avalanche node is done bootstrapping, ssh into the node and call [`info.isBootstrapped`](/docs/api-reference/info-api#infoisbootstrapped) by copying and pasting the following command:

```bash
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"info.isBootstrapped",
    "params": {
        "chain":"P"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info
```

If this returns `true`, it means that the chain is bootstrapped and we will proceed to deploying our L1.

We will need to have the Avalanche node's NodeID, BLS public key and proof of possession. These can be obtained by ssh into the node itself and run the `getNodeID` API specified [here](/docs/api-reference/info-api#infogetnodeid)

To deploy the new Avalanche L1, with your Ledger unlocked and running the Avalanche app, run:

```bash
avalanche blockchain deploy testblockchain
```

This is going to start a new prompt series.

```bash
Use the arrow keys to navigate: ↓ ↑ → ←
? Choose a network to deploy on:
    Local Network
    Fuji
  ▸ Mainnet
```

This tutorial is about deploying to `Mainnet`, so navigate with the arrow keys to `Mainnet` and hit enter. The user is then asked to provide which private key to use for the deployment. Select a key to has P-Chain AVAX to pay for transaction fees.

```bash
✔ Mainnet
Deploying [testblockchain] to Mainnet
```

After that, CLI shows the `Mainnet` Ledger address used to fund the deployment:

```bash
Ledger address: P-avax1ucykh6ls8thqpuwhg3vp8vvu6spg5e8tp8a25j
```

Select `No` to using local machine as a bootstrap validator on the blockchain.

```bash
You can use your local machine as a bootstrap validator on the blockchain
This means that you don't have to to set up a remote server on a cloud service (e.g. AWS / GCP) to be a validator on the blockchain.
Use the arrow keys to navigate: ↓ ↑ → ←
? Do you want to use your local machine as a bootstrap validator?:
    Yes
  ▸ No
```

Enter 1 as the number of bootstrap validators we will be setting up.

```bash
✔ No
✗ How many bootstrap validators do you want to set up?: 1
```

Select `Yes` since we have already set up our Avalanche Node on AWS.

```bash
If you have set up your own Avalanche Nodes, you can provide the Node ID and BLS Key from those nodes in the next step.
Otherwise, we will generate new Node IDs and BLS Key for you.
Use the arrow keys to navigate: ↓ ↑ → ←
? Have you set up your own Avalanche Nodes?:
  ▸ Yes
    No
```

Next, we will enter the node's Node-ID:

```bash
Getting info for bootstrap validator 1
✗ What is the NodeID of the node you want to add as bootstrap validator?: █
```

And BLS public key and proof of possession:

```bash
Next, we need the public key and proof of possession of the node's BLS
Check https://build.avax.network/docs/api-reference/info-api#infogetnodeid for instructions on calling info.getNodeID API
✗ What is the node's BLS public key?: █
```

Next, the CLI generates a CreateSubnet TX to create the Subnet and asks the user to sign it by using the Ledger.

```bash
*** Please sign Avalanche L1 creation hash on the ledger device ***
```

This activates a `Please review` window on the Ledger. Navigate to the Ledger's `APPROVE` window by using the Ledger's right button, and then authorize the request by pressing both left and right buttons.

If the Ledger doesn't have enough funds, the user may see an error message:

```bash
*** Please sign Avalanche L1 creation hash on the ledger device ***
Error: insufficient funds: provided UTXOs need 1000000000 more units of asset "U8iRqJoiJm8xZHAacmvYyZVwqQx6uDNtQeP3CQ6fcgQk3JqnK"
```

If successful, the CLI next asks you to sign a CreateChain Tx. Once CreateChain Tx is signed, it will then ask you to sign ConvertSubnetToL1 Tx.

Well done. You have just created your own Avalanche L1 on `Mainnet`.

You will be able to see information on the deployed L1 at the end of `avalanche blockchain deploy` command:

```bash
+--------------------+----------------------------------------------------+
| DEPLOYMENT RESULTS |                                                    |
+--------------------+----------------------------------------------------+
| Chain Name         | testblockchain                                     |
+--------------------+----------------------------------------------------+
| Subnet ID          | 2cNuyBhvAd4jH5bFSGndezhB66Z4UHYAsLCMGoCpvhXVhrZfgd |
+--------------------+----------------------------------------------------+
| VM ID              | qcvkEX1zWSz7PtGd7CKvPRBqLVTzA7qyMPvkh5NMDWkuhrcCu  |
+--------------------+----------------------------------------------------+
| Blockchain ID      | 2U7vNdB78xTiN6QtZ9aetfKoGtQhfeEPQG6QZC8bpq8QMf4cDx |
+--------------------+                                                    +
| P-Chain TXID       |                                                    |
+--------------------+----------------------------------------------------+
```

To get your new Avalanche L1 information, there are two options:

- Call `avalanche blockchain describe` command or
- Visit the [Avalanche L1 Explorer](https://subnets-test.avax.network/). The search best works by blockchain ID, so in this example, enter `2U7vNdB78xTiN6QtZ9aetfKoGtQhfeEPQG6QZC8bpq8QMf4cDx` into the search box and you should see your shiny new blockchain information.

Add a Validator[​](#add-a-validator "Direct link to heading")
-------------------------------------------------------------

Before proceeding to add a validator to our Avalanche L1, we will need to have the validator's NodeID, BLS public key and proof of possession. These can be obtained by ssh into the node itself and run the `getNodeID` API specified [here](/docs/api-reference/info-api#infogetnodeid)

To add a validator to an Avalanche L1, the owner of the key that acts as the controller of ValidatorManager contract specified in `avalanche blockchain create` command above run:

```bash
avalanche blockchain addValidator testblockchain
```

Choose `Mainnet`:

```bash
Use the arrow keys to navigate: ↓ ↑ → ←
? Choose a network to deploy on:
  ▸ Mainnet
```

The CLI will show the Ledger address that will be used to pay for add validator tx:

```bash
Ledger address: P-avax1ucykh6ls8thqpuwhg3vp8vvu6spg5e8tp8a25j
```

Now enter the **NodeID** of the new validator to be added.

```bash
What is the NodeID of the validator you'd like to whitelist?: NodeID-BFa1paAAAAAAAAAAAAAAAAAAAAQGjPhUy
```

Next, enter the node's BLS public key and proof of possession.

Now, enter the amount of AVAX that you would like to allocate to the new validator.

The validator's balance is used to pay for continuous fee to the P-Chain. When this Balance reaches 0, the validator will be considered inactive and will no longer participate in validating the L1.

1 AVAX should last the validator about a month.

```bash
What balance would you like to assign to the validator (in AVAX)?: 1
```

Sign the addValidatorTx with your Ledger:

```bash
*** Please sign add validator hash on the ledger device ***
```

This activates a `Please review` window on the Ledger. Navigate to the Ledger's `APPROVE` window by using the Ledger's right button, and then authorize the request by pressing both left and right buttons.

This might take a couple of seconds. After, it prints:

```bash
Transaction successful, transaction ID: r3tJ4Wr2CWA8AaticmFrKdKgAs5AhW2wwWTaQHRBZKwJhsXzb
```

This means the node is now a validator on the given Avalanche L1 on `Mainnet`!

Going Live[​](#going-live "Direct link to heading")
---------------------------------------------------

For the safety of your validators, you should setup dedicated API nodes to process transactions, but for test purposes, you can issue transactions directly to one of your validator's RPC interface.

# On Production Infra (/docs/tooling/avalanche-cli/create-deploy-avalanche-l1s/deploy-on-production-infra)

---
title: On Production Infra
description: Learn how to deploy an Avalanche L1 on production infrastructure.
---

After architecting your Avalanche L1 environment on the [local machine](/docs/tooling/create-deploy-avalanche-l1s/deploy-locally), proving the design and testing it out on [the Fuji Testnet](/docs/tooling/create-deploy-avalanche-l1s/deploy-on-fuji-testnet), eventually you will need to deploy your Avalanche L1 to production environment.

Running an Avalanche L1 in production is much more involved than local and Testnet deploys, as your Avalanche L1 will have to take care of real world usage, maintaining uptime, upgrades and all of that in a potentially adversarial environment. The purpose of this document is to point out a set of general considerations and propose potential solutions to them.

The architecture of the environment your particular Avalanche L1 will use will be greatly influenced by the type of load and activity your Avalanche L1 is designed to support so your solution will most likely differ from what we propose here. Still, it might be useful to follow along, to build up the intuition for the type of questions you will need to consider.

Node Setup[​](#node-setup "Direct link to heading")
---------------------------------------------------

Avalanche nodes are essential elements for running your Avalanche L1 in production. At a minimum, your Avalanche L1 will need validator nodes, potentially also nodes that act as RPC servers, indexers or explorers. Running a node is basically running an instance of [AvalancheGo](/docs/nodes) on a server.

### Server OS[​](#server-os "Direct link to heading")

Although AvalancheGo can run on a MacOS or a Windows computer, we strongly recommend running nodes on computers running Linux as they are designed specifically for server loads and all the tools and utilities needed for administering a server are native to Linux.

### Hardware Specification[​](#hardware-specification "Direct link to heading")

For running AvalancheGo as a validator on the Primary Network the recommended configuration is as follows:

- CPU: Equivalent of 8 AWS vCPU
- RAM: 16 GiB
- Storage: 1 TiB with at least 3000 IOPS
- OS: Ubuntu 20.04
- Network: Reliable IPv4 or IPv6 network connection, with an open public port

That is the configuration sufficient for running a Primary Network node. Any resource requirements for your Avalanche L1 come on top of this, so you should not go below this configuration, but may need to step up the specification if you expect your Avalanche L1 to handle a significant amount of transactions.

Be sure to set up monitoring of resource consumption for your nodes because resource exhaustion may cause your node to slow down or even halt, which may severely impact your Avalanche L1 negatively.

### Server Location[​](#server-location "Direct link to heading")

You can run a node on a physical computer that you own and run, or on a cloud instance. Although running on your own HW may seem like a good idea, unless you have a sizeable DevOps 24/7 staff we recommend using cloud service providers as they generally provide reliable computing resources that you can count on to be properly maintained and monitored.

#### Local Servers[​](#local-servers "Direct link to heading")

If you plan on running nodes on your own hardware, make sure they satisfy the minimum HW specification as outlined earlier. Pay close attention to proper networking setup, making sure the p2p port (9651) is accessible and public IP properly configured on the node. Make sure the node is connected to the network physically (not over Wi-Fi), and that the router is powerful enough to handle a couple of thousands of persistent TCP connections and that network bandwidth can accommodate at least 5Mbps of steady upstream and downstream network traffic.

When installing the AvalancheGo node on the machines, unless you have a dedicated DevOps staff that will take care of node setup and configuration, we recommend using the [installer script](/docs/nodes/using-install-script/installing-avalanche-go) to set up the nodes. It will abstract most of the setup process for you, set up the node as a system service and will enable easy node upgrades.

#### Cloud Providers[​](#cloud-providers "Direct link to heading")

There are a number of different cloud providers. We have documents that show how to set up a node on the most popular ones:

- [Amazon Web Services](/docs/nodes/on-third-party-services/amazon-web-services)
- [Azure](/docs/nodes/on-third-party-services/microsoft-azure)
- [Google Cloud Platform](/docs/nodes/on-third-party-services/google-cloud)

There is a whole range of other cloud providers that may offer lower prices or better deals for your particular needs, so it makes sense to shop around.

Once you decide on a provider (or providers), if they offer instances in multiple data centers, it makes sense to spread the nodes geographically since that provides a better resilience and stability against outages.

### Number of Validators[​](#number-of-validators "Direct link to heading")

Number of validators on an Avalanche L1 is a crucial decision you need to make. For stability and decentralization, you should strive to have as many validators as possible.

For stability reasons our recommendation is to have **at least** 5 full validators on your Avalanche L1. If you have less than 5 validators your Avalanche L1 liveness will be at risk whenever a single validator goes offline, and if you have less than 4 even one offline node will halt your Avalanche L1.

You should be aware that 5 is the minimum we recommend. But, from a decentralization standpoint having more validators is always better as it increases the stability of your Avalanche L1 and makes it more resilient to both technical failures and adversarial action. In a nutshell: run as many Avalanche L1 validators as you can.

Considering that at times you will have to take nodes offline, for routine maintenance (at least for node upgrades which happen with some regularity) or unscheduled outages and failures you need to be able to routinely handle at least one node being offline without your Avalanche L1 performance degrading.

### Node Bootstrap[​](#node-bootstrap "Direct link to heading")

Once you set up the server and install AvalancheGo on them, nodes will need to bootstrap (sync with the network). This is a lengthy process, as the nodes need to catch up and replay all the network activity since the genesis up to the present moment. Full bootstrap on a node can take more than a week, but there are ways to shorten that process, depending on your circumstances.

#### State Sync[​](#state-sync "Direct link to heading")

If the nodes you will be running as validators don't need to have the full transaction history, then you can use [state sync](/docs/nodes/chain-configs/c-chain#state-sync-enabled). With this flag enabled, instead of replaying the whole history to get to the current state, nodes simply download only the current state from other network peers, shortening the bootstrap process from multiple days to a couple of hours. If the nodes will be used for Avalanche L1 validation exclusively, you can use the state sync without any issues. Currently, state sync is only available for the C-Chain, but since the bulk of the transactions on the platform happen there it still has a significant impact on the speed of bootstrapping.

#### Database Copy[​](#database-copy "Direct link to heading")

Good way to cut down on bootstrap times on multiple nodes is database copy. Database is identical across nodes, and as such can safely be copied from one node to another. Just make sure to that the node is not running during the copy process, as that can result in a corrupted database. Database copy procedure is explained in detail [here](/docs/nodes/maintain/backup-restore#database).

Please make sure you don't reuse any node's NodeID by accident, especially don't restore another node's ID, see [here](/docs/nodes/maintain/backup-restore#nodeid) for details. Each node must has its own unique NodeID, otherwise, the nodes sharing the same ID will not behave correctly, which will impact your validator's uptime, thus staking rewards, and the stability of your Avalanche L1.

Avalanche L1 Deploy[​](#avalanche-l1-deploy "Direct link to heading")
---------------------------------------------------------

Once you have the nodes set up you are ready to deploy the actual Avalanche L1. Right now, the recommended tool to do that is [Avalanche-CLI](https://github.com/ava-labs/avalanche-cli).

Instructions for deployment by Avalanche-CLI can be found [here](/docs/tooling/create-deploy-avalanche-l1s/deploy-on-mainnet).

### Ledger Hardware Wallet[​](#ledger-hw-wallet "Direct link to heading")

When creating the Avalanche L1, you will be required to have a private key that will control the administrative functions of the Avalanche L1 (adding validators, managing the configuration). Needless to say, whoever has this private key has complete control over the Avalanche L1 and the way it runs. Therefore, protecting that key is of the utmost operational importance. Which is why we strongly recommend using a hardware wallet such as a [Ledger HW Wallet](https://www.ledger.com/) to store and access that private key.

General instruction on how to use a Ledger device with Avalanche can be found [here](https://support.avax.network/en/articles/6150237-how-to-use-a-ledger-nano-s-or-nano-x-with-avalanche).

### Genesis File[​](#genesis-file "Direct link to heading")

The structure that defines the most important parameters in an Avalanche L1 is found in the genesis file, which is a `json` formatted, human-readable file. Describing the contents and the options available in the genesis file is beyond the scope of this document, and if you're ready to deploy your Avalanche L1 to production you probably have it mapped out already.

If you want to review, we have a description of the genesis file in our document on [customizing EVM Avalanche L1s](/docs/avalanche-l1s/upgrade/customize-avalanche-l1).

Validator Configuration[​](#validator-configuration "Direct link to heading")
-----------------------------------------------------------------------------

Running nodes as Avalanche L1 validators warrants some additional considerations, above those when running a regular node or a Primary Network-only validator.

### Joining an Avalanche L1[​](#joining-a-avalanche-l1 "Direct link to heading")

For a node to join an Avalanche L1, there are two prerequisites:

- Primary Network validation
- Avalanche L1 tracking

Primary Network validation means that a node cannot join an Avalanche L1 as a validator before becoming a validator on the Primary Network itself. So, after you add the node to the validator set on the Primary Network, node can join an Avalanche L1. Of course, this is valid only for Avalanche L1 validators, if you need a non-validating Avalanche L1 node, then the node doesn't need to be a validator at all.

To have a node start syncing the Avalanche L1, you need to add the `--track-subnets` command line option, or `track-subnets` key to the node config file (found at `.avalanchego/configs/node.json` for installer-script created nodes). A single node can sync multiple Layer 1s, so you can add them as a comma-separated list of Avalanche L1 IDs (SubnetID).

An example of a node config syncing two Avalanche L1s:

```json
{
  "public-ip-resolution-service": "opendns",
  "http-host": "",
  "track-subnets": "28nrH5T2BMvNrWecFcV3mfccjs6axM1TVyqe79MCv2Mhs8kxiY,Ai42MkKqk8yjXFCpoHXw7rdTWSHiKEMqh5h8gbxwjgkCUfkrk"
}
```

But that is not all. Besides tracking the SubnetID, the node also needs to have the plugin that contains the VM instance the blockchain in the Avalanche L1 will run. You should have already been through that on Testnet and Fuji, but for a refresher, you can refer to [this tutorial](/docs/tooling/create-deploy-avalanche-l1s/deploy-on-fuji-testnet).

So, name the VM plugin binary as the `VMID` of the Avalanche L1 chain and place it in the `plugins` directory where the node binary is (for installer-script created nodes that would be `~/avalanche-node/plugins/`).

### Avalanche L1 Bootstrapping[​](#avalanche-l1-bootstrapping "Direct link to heading")

After you have tracked the Avalanche L1 and placed the VM binary in the correct directory, your node is ready to start syncing with the Avalanche L1. Restart the node and monitor the log output. You should notice something similar to:

```bash
Jul 30 18:26:31 node-fuji avalanchego[1728308]: [07-30|18:26:31.422] INFO chains/manager.go:262 creating chain:
Jul 30 18:26:31 node-fuji avalanchego[1728308]:     ID: 2ebCneCbwthjQ1rYT41nhd7M76Hc6YmosMAQrTFhBq8qeqh6tt
Jul 30 18:26:31 node-fuji avalanchego[1728308]:     VMID:srEXiWaHuhNyGwPUi444Tu47ZEDwxTWrbQiuD7FmgSAQ6X7Dy
```

That means the node has detected the Avalanche L1, and is attempting to initialize it and start bootstrapping the Avalanche L1. It might take some time (if there are already transactions on the Avalanche L1), and eventually it will finish the bootstrap with a message like:

```bash
Jul 30 18:27:21 node-fuji avalanchego[1728308]: [07-30|18:27:21.055] INFO <2ebCneCbwthjQ1rYT41nhd7M76Hc6YmosMAQrTFhBq8qeqh6tt Chain> snowman/transitive.go:333 consensus starting with J5wjmotMCrM2DKxeBTBPfwgCPpvsjtuqWNozLog2TomTjSuGK as the last accepted block
```

That means the node has successfully bootstrapped the Avalanche L1 and is now in sync. If the node is one of the validators, it will start validating any transactions that get posted to the Avalanche L1.

### Monitoring[​](#monitoring "Direct link to heading")

If you want to inspect the process of Avalanche L1 syncing, you can use the RPC call to check for the [blockchain status](/docs/api-reference/p-chain/api#platformgetblockchainstatus).

For a more in-depth look into Avalanche L1 operation, check out the blockchain log. By default, the log can be found in `~/.avalanchego/logs/ChainID.log` where you replace the `ChainID` with the actual ID of the blockchain in your Avalanche L1.

For an even more thorough (and pretty!) insight into how the node and the Avalanche L1 is behaving, you can install the Prometheus+Grafana monitoring system with the custom dashboards for the regular node operation, as well as a dedicated dashboard for Avalanche L1 data. Check out the [tutorial](/docs/nodes/maintain/monitoring) for information on how to set it up.

### Managing Validation[​](#managing-validation "Direct link to heading")

On Avalanche all validations are limited in time and can range from two weeks up to one year. Furthermore, Avalanche L1 validations are always a subset of the Primary Network validation period (must be shorter or the same). That means that periodically your validators will expire and you will need to submit a new validation transaction for both the Primary Network and your Avalanche L1.

Unless managed properly and in a timely manner, that can be disruptive for your Avalanche L1 (if all validators expire at the same time your Avalanche L1 will halt). To avoid that, keep notes on when a particular validation is set to expire and be ready to renew it as soon as possible. Also, when initially setting up the nodes, make sure to stagger the validator expiry so they don't all expire on the same date. Setting end dates at least a day apart is a good practice, as well as setting reminders for each expiry.

Conclusion[​](#conclusion "Direct link to heading")
---------------------------------------------------

Hopefully, by reading this document you have a better picture of the requirements and considerations you need to make when deploying your Avalanche L1 to production and you are now better prepared to launch your Avalanche L1 successfully.

Keep in mind, running an Avalanche L1 in production is not a one-and-done kind of situation, it is in fact running a fleet of servers 24/7. And as with any real time service, you should have a robust logging, monitoring and alerting systems to constantly check the nodes and Avalanche L1 health and alert you if anything out of the ordinary happens.

If you have any questions, doubts or would like to chat, please check out our [Discord server](https://discord.gg/avax/), where we host a dedicated `#subnet-chat` channel dedicated to talking about all things Avalanche L1.


# With Custom VM (/docs/tooling/avalanche-cli/create-deploy-avalanche-l1s/deploy-with-custom-vm)

---
title: With Custom VM
description: Learn how to create an Avalanche L1 with a custom virtual machine and deploy it locally.
---

This tutorial walks through the process of creating an Avalanche L1 with a custom virtual machine and deploying it locally. Although the tutorial uses a fork of Subnet-EVM as an example, you can extend its lessons to support any custom VM binary.

Fork Subnet-EVM[​](#fork-subnet-evm "Direct link to heading")
-------------------------------------------------------------

Instead of building a custom VM from scratch, this tutorial starts with forking Subnet-EVM.

### Clone Subnet-EVM[​](#clone-subnet-evm "Direct link to heading")

First off, clone the Subnet-EVM repository into a directory of your choosing.

```bash
git clone https://github.com/ava-labs/subnet-evm.git
```

<Callout title="Note">
The repository cloning method used is HTTPS, but SSH can be used too:

`git clone git@github.com:ava-labs/subnet-evm.git`

You can find more about SSH and how to use it [here](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/about-ssh).
</Callout>

### Modify and Build Subnet-EVM[​](#modify-and-build-subnet-evm "Direct link to heading")

To prove you're running your custom binary and not the stock Subnet-EVM included with Avalanche-CLI, you need to modify the Subnet-EVM binary by making a minor change.

Navigate to the directory you cloned Subnet-EVM into and generate a new commit:

```bash
git commit -a --allow-empty -m "custom vm commit"
```

Take note of the new commit hash:

```bash
git rev-parse HEAD
c0fe6506a40da466285f37dd0d3c044f494cce32
```

In this case, `c0fe6506a40da466285f37dd0d3c044f494cce32`.

Now build your custom binary by running:

```bash
./scripts/build.sh custom_vm.bin
```

This command builds the binary and saves it at `./custom_vm.bin`.

### Create a Custom Genesis[​](#create-a-custom-genesis "Direct link to heading")

To start a VM, you need to provide a genesis file. Here is a basic Subnet-EVM genesis that's compatible with your custom VM.
This genesis includes the PoA Validator Manager, a Transparent Proxy and Proxy Admin as predeployed contracts.

`0c0deba5e0000000000000000000000000000000` is the ValidatorManager address.
`0feedc0de0000000000000000000000000000000` is the Transparent Proxy address.
`c0ffee1234567890abcdef1234567890abcdef34` is the Proxy Admin contract.

These proxy contracts are from [OpenZeppelin v4.9](https://github.com/OpenZeppelin/openzeppelin-contracts/tree/release-v4.9/contracts/proxy/transparent)
You can add your own predeployed contracts by running `forge build` and collecting the `deployedBytecode` output from `out/MyContract.sol`


```json
{
    "config": {
        "berlinBlock": 0,
        "byzantiumBlock": 0,
        "chainId": 1,
        "constantinopleBlock": 0,
        "eip150Block": 0,
        "eip155Block": 0,
        "eip158Block": 0,
        "feeConfig": {
            "gasLimit": 12000000,
            "targetBlockRate": 2,
            "minBaseFee": 25000000000,
            "targetGas": 60000000,
            "baseFeeChangeDenominator": 36,
            "minBlockGasCost": 0,
            "maxBlockGasCost": 1000000,
            "blockGasCostStep": 200000
        },
        "homesteadBlock": 0,
        "istanbulBlock": 0,
        "londonBlock": 0,
        "muirGlacierBlock": 0,
        "petersburgBlock": 0,
        "warpConfig": {
            "blockTimestamp": 1736356569,
            "quorumNumerator": 67,
            "requirePrimaryNetworkSigners": true
        }
    },
    "nonce": "0x0",
    "timestamp": "0x677eb2d9",
    "extraData": "0x",
    "gasLimit": "0xb71b00",
    "difficulty": "0x0",
    "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "coinbase": "0x0000000000000000000000000000000000000000",
    "alloc": {
        "0c0deba5e0000000000000000000000000000000": {
            "code": "0x608060405234801561000f575f80fd5b5060043610610132575f3560e01c80639ba96b86116100b4578063c974d1b611610079578063c974d1b6146102a7578063d588c18f146102af578063d5f20ff6146102c2578063df93d8de146102e2578063f2fde38b146102ec578063fd7ac5e7146102ff575f80fd5b80639ba96b861461024c578063a3a65e481461025f578063b771b3bc14610272578063bc5fbfec14610280578063bee0a03f14610294575f80fd5b8063715018a6116100fa578063715018a6146101be578063732214f8146101c65780638280a25a146101db5780638da5cb5b146101f557806397fb70d414610239575f80fd5b80630322ed981461013657806320d91b7a1461014b578063467ef06f1461015e57806360305d621461017157806366435abf14610193575b5f80fd5b610149610144366004612b01565b610312565b005b610149610159366004612b30565b610529565b61014961016c366004612b7e565b610a15565b610179601481565b60405163ffffffff90911681526020015b60405180910390f35b6101a66101a1366004612b01565b610a23565b6040516001600160401b03909116815260200161018a565b610149610a37565b6101cd5f81565b60405190815260200161018a565b6101e3603081565b60405160ff909116815260200161018a565b7f9016d09d72d40fdae2fd8ceac6b6234c7706214fd39c1cd1e609a0528c199300546001600160a01b03165b6040516001600160a01b03909116815260200161018a565b610149610247366004612b01565b610a4a565b6101cd61025a366004612bad565b610a5f565b61014961026d366004612b7e565b610a7b565b6102216005600160991b0181565b6101cd5f8051602061370d83398151915281565b6101496102a2366004612b01565b610c04565b6101e3601481565b6101496102bd366004612c06565b610d41565b6102d56102d0366004612b01565b610e4f565b60405161018a9190612cc3565b6101a66202a30081565b6101496102fa366004612d43565b610f9e565b6101cd61030d366004612d65565b610fdb565b5f8181525f8051602061372d8339815191526020526040808220815160e0810190925280545f8051602061370d83398151915293929190829060ff16600581111561035f5761035f612c42565b600581111561037057610370612c42565b815260200160018201805461038490612dd0565b80601f01602080910402602001604051908101604052809291908181526020018280546103b090612dd0565b80156103fb5780601f106103d2576101008083540402835291602001916103fb565b820191905f5260205f20905b8154815290600101906020018083116103de57829003601f168201915b505050918352505060028201546001600160401b038082166020840152600160401b820481166040840152600160801b820481166060840152600160c01b909104811660808301526003928301541660a0909101529091508151600581111561046657610466612c42565b146104a2575f8381526007830160205260409081902054905163170cc93360e21b81526104999160ff1690600401612e08565b60405180910390fd5b6005600160991b016001600160a01b031663ee5b48eb6104c78584606001515f611036565b6040518263ffffffff1660e01b81526004016104e39190612e16565b6020604051808303815f875af11580156104ff573d5f803e3d5ffd5b505050506040513d601f19601f820116820180604052508101906105239190612e28565b50505050565b7fe92546d698950ddd38910d2e15ed1d923cd0a7b3dde9e2a6a3f380565559cb09545f8051602061370d8339815191529060ff161561057b57604051637fab81e560e01b815260040160405180910390fd5b6005600160991b016001600160a01b0316634213cf786040518163ffffffff1660e01b8152600401602060405180830381865afa1580156105be573d5f803e3d5ffd5b505050506040513d601f19601f820116820180604052508101906105e29190612e28565b83602001351461060b576040516372b0a7e760e11b815260208401356004820152602401610499565b3061061c6060850160408601612d43565b6001600160a01b03161461065f5761063a6060840160408501612d43565b604051632f88120d60e21b81526001600160a01b039091166004820152602401610499565b5f61066d6060850185612e3f565b905090505f805b828163ffffffff161015610955575f6106906060880188612e3f565b8363ffffffff168181106106a6576106a6612e84565b90506020028101906106b89190612e98565b6106c190612fbc565b80516040519192505f9160088801916106d991613035565b9081526020016040518091039020541461070957805160405163a41f772f60e01b81526104999190600401612e16565b5f6002885f01358460405160200161073892919091825260e01b6001600160e01b031916602082015260240190565b60408051601f198184030181529082905261075291613035565b602060405180830381855afa15801561076d573d5f803e3d5ffd5b5050506040513d601f19601f820116820180604052508101906107909190612e28565b90508086600801835f01516040516107a89190613035565b90815260408051602092819003830181209390935560e0830181526002835284518284015284810180516001600160401b03908116858401525f60608601819052915181166080860152421660a085015260c0840181905284815260078a01909252902081518154829060ff1916600183600581111561082a5761082a612c42565b0217905550602082015160018201906108439082613091565b506040828101516002830180546060860151608087015160a08801516001600160401b039586166001600160801b031990941693909317600160401b92861692909202919091176001600160801b0316600160801b918516919091026001600160c01b031617600160c01b9184169190910217905560c0909301516003909201805467ffffffffffffffff1916928416929092179091558301516108e8911685613164565b82516040519195506108f991613035565b60408051918290038220908401516001600160401b031682529082907f9d47fef9da077661546e646d61830bfcbda90506c2e5eed38195e82c4eb1cbdf9060200160405180910390a350508061094e90613177565b9050610674565b50600483018190555f61097361096a86611085565b6040015161119b565b90505f61097f87611328565b90505f6002826040516109929190613035565b602060405180830381855afa1580156109ad573d5f803e3d5ffd5b5050506040513d601f19601f820116820180604052508101906109d09190612e28565b90508281146109fc57604051631872fc8d60e01b81526004810182905260248101849052604401610499565b5050506009909201805460ff1916600117905550505050565b610a1e81611561565b505050565b5f610a2d82610e4f565b6080015192915050565b610a3f61189f565b610a485f6118fa565b565b610a5261189f565b610a5b8161196a565b5050565b5f610a6861189f565b610a728383611c4e565b90505b92915050565b5f8051602061370d8339815191525f80610aa0610a9785611085565b604001516121a1565b9150915080610ac657604051632d07135360e01b81528115156004820152602401610499565b5f82815260068401602052604090208054610ae090612dd0565b90505f03610b045760405163089938b360e11b815260048101839052602401610499565b60015f83815260078501602052604090205460ff166005811115610b2a57610b2a612c42565b14610b5d575f8281526007840160205260409081902054905163170cc93360e21b81526104999160ff1690600401612e08565b5f8281526006840160205260408120610b7591612a75565b5f828152600784016020908152604091829020805460ff1916600290811782550180546001600160401b0342818116600160c01b026001600160c01b0390931692909217928390558451600160801b9093041682529181019190915283917ff8fd1c90fb9cfa2ca2358fdf5806b086ad43315d92b221c929efc7f105ce7568910160405180910390a250505050565b5f8181527fe92546d698950ddd38910d2e15ed1d923cd0a7b3dde9e2a6a3f380565559cb066020526040902080545f8051602061370d8339815191529190610c4b90612dd0565b90505f03610c6f5760405163089938b360e11b815260048101839052602401610499565b60015f83815260078301602052604090205460ff166005811115610c9557610c95612c42565b14610cc8575f8281526007820160205260409081902054905163170cc93360e21b81526104999160ff1690600401612e08565b5f82815260068201602052604090819020905163ee5b48eb60e01b81526005600160991b019163ee5b48eb91610d019190600401613199565b6020604051808303815f875af1158015610d1d573d5f803e3d5ffd5b505050506040513d601f19601f82011682018060405250810190610a1e9190612e28565b7ff0c57e16840df040f15088dc2f81fe391c3923bec73e23a9662efc9c229c6a008054600160401b810460ff1615906001600160401b03165f81158015610d855750825b90505f826001600160401b03166001148015610da05750303b155b905081158015610dae575080155b15610dcc5760405163f92ee8a960e01b815260040160405180910390fd5b845467ffffffffffffffff191660011785558315610df657845460ff60401b1916600160401b1785555b610e00878761235d565b8315610e4657845460ff60401b19168555604051600181527fc7f505b2f371ae2175ee4913f4499e1f2633a7b5936321eed1cdaeb6115181d29060200160405180910390a15b50505050505050565b610e57612aac565b5f8281525f8051602061372d833981519152602052604090819020815160e0810190925280545f8051602061370d833981519152929190829060ff166005811115610ea457610ea4612c42565b6005811115610eb557610eb5612c42565b8152602001600182018054610ec990612dd0565b80601f0160208091040260200160405190810160405280929190818152602001828054610ef590612dd0565b8015610f405780601f10610f1757610100808354040283529160200191610f40565b820191905f5260205f20905b815481529060010190602001808311610f2357829003601f168201915b505050918352505060028201546001600160401b038082166020840152600160401b820481166040840152600160801b820481166060840152600160c01b9091048116608083015260039092015490911660a0909101529392505050565b610fa661189f565b6001600160a01b038116610fcf57604051631e4fbdf760e01b81525f6004820152602401610499565b610fd8816118fa565b50565b6040515f905f8051602061370d833981519152907fe92546d698950ddd38910d2e15ed1d923cd0a7b3dde9e2a6a3f380565559cb089061101e9086908690613223565b90815260200160405180910390205491505092915050565b604080515f6020820152600360e01b602282015260268101949094526001600160c01b031960c093841b811660468601529190921b16604e830152805180830360360181526056909201905290565b60408051606080820183525f8083526020830152918101919091526040516306f8253560e41b815263ffffffff831660048201525f9081906005600160991b0190636f825350906024015f60405180830381865afa1580156110e9573d5f803e3d5ffd5b505050506040513d5f823e601f3d908101601f191682016040526111109190810190613241565b915091508061113257604051636b2f19e960e01b815260040160405180910390fd5b815115611158578151604051636ba589a560e01b81526004810191909152602401610499565b60208201516001600160a01b031615611194576020820151604051624de75d60e31b81526001600160a01b039091166004820152602401610499565b5092915050565b5f81516026146111d057815160405163cc92daa160e01b815263ffffffff909116600482015260266024820152604401610499565b5f805b600281101561121f576111e7816001613313565b6111f2906008613326565b61ffff1684828151811061120857611208612e84565b016020015160f81c901b91909117906001016111d3565b5061ffff8116156112495760405163407b587360e01b815261ffff82166004820152602401610499565b5f805b60048110156112a457611260816003613313565b61126b906008613326565b63ffffffff168561127d836002613164565b8151811061128d5761128d612e84565b016020015160f81c901b919091179060010161124c565b5063ffffffff8116156112ca57604051635b60892f60e01b815260040160405180910390fd5b5f805b602081101561131f576112e181601f613313565b6112ec906008613326565b866112f8836006613164565b8151811061130857611308612e84565b016020015160f81c901b91909117906001016112cd565b50949350505050565b60605f8083356020850135601461134487870160408901612d43565b6113516060890189612e3f565b60405160f09790971b6001600160f01b0319166020880152602287019590955250604285019290925260e090811b6001600160e01b0319908116606286015260609290921b6bffffffffffffffffffffffff191660668501529190911b16607a820152607e0160405160208183030381529060405290505f5b6113d76060850185612e3f565b9050811015611194576113ed6060850185612e3f565b828181106113fd576113fd612e84565b905060200281019061140f9190612e98565b61141d90602081019061333d565b905060301461143f5760405163180ffa0d60e01b815260040160405180910390fd5b8161144d6060860186612e3f565b8381811061145d5761145d612e84565b905060200281019061146f9190612e98565b611479908061333d565b90506114886060870187612e3f565b8481811061149857611498612e84565b90506020028101906114aa9190612e98565b6114b4908061333d565b6114c16060890189612e3f565b868181106114d1576114d1612e84565b90506020028101906114e39190612e98565b6114f190602081019061333d565b6114fe60608b018b612e3f565b8881811061150e5761150e612e84565b90506020028101906115209190612e98565b61153190606081019060400161337f565b6040516020016115479796959493929190613398565b60408051601f1981840301815291905291506001016113ca565b5f61156a612aac565b5f8051602061370d8339815191525f80611586610a9787611085565b9150915080156115ad57604051632d07135360e01b81528115156004820152602401610499565b5f828152600784016020526040808220815160e081019092528054829060ff1660058111156115de576115de612c42565b60058111156115ef576115ef612c42565b815260200160018201805461160390612dd0565b80601f016020809104026020016040519081016040528092919081815260200182805461162f90612dd0565b801561167a5780601f106116515761010080835404028352916020019161167a565b820191905f5260205f20905b81548152906001019060200180831161165d57829003601f168201915b505050918352505060028201546001600160401b038082166020840152600160401b820481166040840152600160801b820481166060840152600160c01b909104811660808301526003928301541660a090910152909150815160058111156116e5576116e5612c42565b14158015611706575060018151600581111561170357611703612c42565b14155b1561172757805160405163170cc93360e21b81526104999190600401612e08565b60038151600581111561173c5761173c612c42565b0361174a576004815261174f565b600581525b8360080181602001516040516117659190613035565b90815260408051602092819003830190205f908190558581526007870190925290208151815483929190829060ff191660018360058111156117a9576117a9612c42565b0217905550602082015160018201906117c29082613091565b5060408201516002820180546060850151608086015160a08701516001600160401b039586166001600160801b031990941693909317600160401b92861692909202919091176001600160801b0316600160801b918516919091026001600160c01b031617600160c01b9184169190910217905560c0909201516003909101805467ffffffffffffffff1916919092161790558051600581111561186857611868612c42565b60405184907f1c08e59656f1a18dc2da76826cdc52805c43e897a17c50faefb8ab3c1526cc16905f90a39196919550909350505050565b336118d17f9016d09d72d40fdae2fd8ceac6b6234c7706214fd39c1cd1e609a0528c199300546001600160a01b031690565b6001600160a01b031614610a485760405163118cdaa760e01b8152336004820152602401610499565b7f9016d09d72d40fdae2fd8ceac6b6234c7706214fd39c1cd1e609a0528c19930080546001600160a01b031981166001600160a01b03848116918217845560405192169182907f8be0079c531659141344cd1fd0a4f28419497f9722a3daafe3b4186f6b6457e0905f90a3505050565b611972612aac565b5f8281525f8051602061372d8339815191526020526040808220815160e0810190925280545f8051602061370d83398151915293929190829060ff1660058111156119bf576119bf612c42565b60058111156119d0576119d0612c42565b81526020016001820180546119e490612dd0565b80601f0160208091040260200160405190810160405280929190818152602001828054611a1090612dd0565b8015611a5b5780601f10611a3257610100808354040283529160200191611a5b565b820191905f5260205f20905b815481529060010190602001808311611a3e57829003601f168201915b50505091835250506002828101546001600160401b038082166020850152600160401b820481166040850152600160801b820481166060850152600160c01b9091048116608084015260039093015490921660a09091015290915081516005811115611ac957611ac9612c42565b14611afc575f8481526007830160205260409081902054905163170cc93360e21b81526104999160ff1690600401612e08565b60038152426001600160401b031660c08201525f84815260078301602052604090208151815483929190829060ff19166001836005811115611b4057611b40612c42565b021790555060208201516001820190611b599082613091565b5060408201516002820180546060850151608086015160a08701516001600160401b039586166001600160801b031990941693909317600160401b92861692909202919091176001600160801b0316600160801b918516919091026001600160c01b031617600160c01b9184169190910217905560c0909201516003909101805467ffffffffffffffff1916919092161790555f611bf78582612377565b6080840151604080516001600160401b03909216825242602083015291935083925087917f13d58394cf269d48bcf927959a29a5ffee7c9924dafff8927ecdf3c48ffa7c67910160405180910390a3509392505050565b7fe92546d698950ddd38910d2e15ed1d923cd0a7b3dde9e2a6a3f380565559cb09545f9060ff16611c9257604051637fab81e560e01b815260040160405180910390fd5b5f8051602061370d83398151915242611cb1606086016040870161337f565b6001600160401b0316111580611ceb5750611ccf6202a30042613164565b611cdf606086016040870161337f565b6001600160401b031610155b15611d2557611d00606085016040860161337f565b604051635879da1360e11b81526001600160401b039091166004820152602401610499565b6030611d34602086018661333d565b905014611d6657611d48602085018561333d565b6040516326475b2f60e11b8152610499925060040190815260200190565b611d70848061333d565b90505f03611d9d57611d82848061333d565b604051633e08a12560e11b8152600401610499929190613401565b5f60088201611dac868061333d565b604051611dba929190613223565b90815260200160405180910390205414611df357611dd8848061333d565b60405163a41f772f60e01b8152600401610499929190613401565b611dfd835f6124ce565b6040805160e08101909152815481525f908190611f099060208101611e22898061333d565b8080601f0160208091040260200160405190810160405280939291908181526020018383808284375f92019190915250505090825250602090810190611e6a908a018a61333d565b8080601f0160208091040260200160405190810160405280939291908181526020018383808284375f92019190915250505090825250602001611eb360608a0160408b0161337f565b6001600160401b03168152602001611ece60608a018a61342f565b611ed790613443565b8152602001611ee960808a018a61342f565b611ef290613443565b8152602001876001600160401b03168152506126a8565b5f82815260068601602052604090209193509150611f278282613091565b508160088401611f37888061333d565b604051611f45929190613223565b9081526040519081900360200181209190915563ee5b48eb60e01b81525f906005600160991b019063ee5b48eb90611f81908590600401612e16565b6020604051808303815f875af1158015611f9d573d5f803e3d5ffd5b505050506040513d601f19601f82011682018060405250810190611fc19190612e28565b6040805160e081019091529091508060018152602001611fe1898061333d565b8080601f0160208091040260200160405190810160405280939291908181526020018383808284375f9201829052509385525050506001600160401b0389166020808401829052604080850184905260608501929092526080840183905260a0909301829052868252600788019092522081518154829060ff1916600183600581111561207057612070612c42565b0217905550602082015160018201906120899082613091565b5060408201516002820180546060850151608086015160a08701516001600160401b039586166001600160801b031990941693909317600160401b92861692909202919091176001600160801b0316600160801b918516919091026001600160c01b031617600160c01b9184169190910217905560c0909201516003909101805467ffffffffffffffff19169190921617905580612127888061333d565b604051612135929190613223565b6040518091039020847fb77297e3befc691bfc864a81e241f83e2ef722b6e7becaa2ecec250c6d52b430898b6040016020810190612173919061337f565b604080516001600160401b0393841681529290911660208301520160405180910390a4509095945050505050565b5f8082516027146121d757825160405163cc92daa160e01b815263ffffffff909116600482015260276024820152604401610499565b5f805b6002811015612226576121ee816001613313565b6121f9906008613326565b61ffff1685828151811061220f5761220f612e84565b016020015160f81c901b91909117906001016121da565b5061ffff8116156122505760405163407b587360e01b815261ffff82166004820152602401610499565b5f805b60048110156122ab57612267816003613313565b612272906008613326565b63ffffffff1686612284836002613164565b8151811061229457612294612e84565b016020015160f81c901b9190911790600101612253565b5063ffffffff81166002146122d357604051635b60892f60e01b815260040160405180910390fd5b5f805b6020811015612328576122ea81601f613313565b6122f5906008613326565b87612301836006613164565b8151811061231157612311612e84565b016020015160f81c901b91909117906001016122d6565b505f8660268151811061233d5761233d612e84565b016020015191976001600160f81b03199092161515965090945050505050565b612365612895565b61236e826128de565b610a5b816128f7565b5f8281525f8051602061372d833981519152602052604081206002015481905f8051602061370d83398151915290600160801b90046001600160401b03166123bf85826124ce565b5f6123c987612908565b5f8881526007850160205260408120600201805467ffffffffffffffff60801b1916600160801b6001600160401b038b16021790559091506005600160991b0163ee5b48eb6124198a858b611036565b6040518263ffffffff1660e01b81526004016124359190612e16565b6020604051808303815f875af1158015612451573d5f803e3d5ffd5b505050506040513d601f19601f820116820180604052508101906124759190612e28565b604080516001600160401b038a811682526020820184905282519394508516928b927f07de5ff35a674a8005e661f3333c907ca6333462808762d19dc7b3abb1a8c1df928290030190a3909450925050505b9250929050565b5f8051602061370d8339815191525f6001600160401b038084169085161115612502576124fb838561350a565b905061250f565b61250c848461350a565b90505b6040805160808101825260028401548082526003850154602083015260048501549282019290925260058401546001600160401b031660608201524291158061257157506001840154815161256d916001600160401b031690613164565b8210155b15612597576001600160401b0383166060820152818152604081015160208201526125b6565b82816060018181516125a9919061352a565b6001600160401b03169052505b60608101516125c690606461354a565b602082015160018601546001600160401b0392909216916125f19190600160401b900460ff16613326565b101561262157606081015160405163dfae880160e01b81526001600160401b039091166004820152602401610499565b856001600160401b03168160400181815161263c9190613164565b9052506040810180516001600160401b038716919061265c908390613313565b905250805160028501556020810151600385015560408101516004850155606001516005909301805467ffffffffffffffff19166001600160401b039094169390931790925550505050565b5f60608260400151516030146126d15760405163180ffa0d60e01b815260040160405180910390fd5b82516020808501518051604080880151606089015160808a01518051908701515193515f98612712988a986001989297929690959094909390929101613575565b60405160208183030381529060405290505f5b846080015160200151518110156127845781856080015160200151828151811061275157612751612e84565b602002602001015160405160200161276a92919061362f565b60408051601f198184030181529190529150600101612725565b5060a08401518051602091820151516040516127a4938593929101613665565b60405160208183030381529060405290505f5b8460a00151602001515181101561281657818560a001516020015182815181106127e3576127e3612e84565b60200260200101516040516020016127fc92919061362f565b60408051601f1981840301815291905291506001016127b7565b5060c084015160405161282d9183916020016136a0565b604051602081830303815290604052905060028160405161284e9190613035565b602060405180830381855afa158015612869573d5f803e3d5ffd5b5050506040513d601f19601f8201168201806040525081019061288c9190612e28565b94909350915050565b7ff0c57e16840df040f15088dc2f81fe391c3923bec73e23a9662efc9c229c6a0054600160401b900460ff16610a4857604051631afcd79f60e31b815260040160405180910390fd5b6128e6612895565b6128ee61297d565b610fd881612985565b6128ff612895565b610fd881612a6d565b5f8181525f8051602061372d8339815191526020526040812060020180545f8051602061370d833981519152919060089061295290600160401b90046001600160401b03166136d1565b91906101000a8154816001600160401b0302191690836001600160401b031602179055915050919050565b610a48612895565b61298d612895565b80355f8051602061370d83398151915290815560146129b260608401604085016136ec565b60ff1611806129d157506129cc60608301604084016136ec565b60ff16155b15612a05576129e660608301604084016136ec565b604051634a59bbff60e11b815260ff9091166004820152602401610499565b612a1560608301604084016136ec565b60018201805460ff92909216600160401b0260ff60401b19909216919091179055612a46604083016020840161337f565b600191909101805467ffffffffffffffff19166001600160401b0390921691909117905550565b610fa6612895565b508054612a8190612dd0565b5f825580601f10612a90575050565b601f0160209004905f5260205f2090810190610fd89190612ae9565b6040805160e08101909152805f81526060602082018190525f604083018190529082018190526080820181905260a0820181905260c09091015290565b5b80821115612afd575f8155600101612aea565b5090565b5f60208284031215612b11575f80fd5b5035919050565b803563ffffffff81168114612b2b575f80fd5b919050565b5f8060408385031215612b41575f80fd5b82356001600160401b03811115612b56575f80fd5b830160808186031215612b67575f80fd5b9150612b7560208401612b18565b90509250929050565b5f60208284031215612b8e575f80fd5b610a7282612b18565b80356001600160401b0381168114612b2b575f80fd5b5f8060408385031215612bbe575f80fd5b82356001600160401b03811115612bd3575f80fd5b830160a08186031215612be4575f80fd5b9150612b7560208401612b97565b6001600160a01b0381168114610fd8575f80fd5b5f808284036080811215612c18575f80fd5b6060811215612c25575f80fd5b508291506060830135612c3781612bf2565b809150509250929050565b634e487b7160e01b5f52602160045260245ffd5b60068110612c7257634e487b7160e01b5f52602160045260245ffd5b9052565b5f5b83811015612c90578181015183820152602001612c78565b50505f910152565b5f8151808452612caf816020860160208601612c76565b601f01601f19169290920160200192915050565b60208152612cd5602082018351612c56565b5f602083015160e06040840152612cf0610100840182612c98565b905060408401516001600160401b0380821660608601528060608701511660808601528060808701511660a08601528060a08701511660c08601528060c08701511660e086015250508091505092915050565b5f60208284031215612d53575f80fd5b8135612d5e81612bf2565b9392505050565b5f8060208385031215612d76575f80fd5b82356001600160401b0380821115612d8c575f80fd5b818501915085601f830112612d9f575f80fd5b813581811115612dad575f80fd5b866020828501011115612dbe575f80fd5b60209290920196919550909350505050565b600181811c90821680612de457607f821691505b602082108103612e0257634e487b7160e01b5f52602260045260245ffd5b50919050565b60208101610a758284612c56565b602081525f610a726020830184612c98565b5f60208284031215612e38575f80fd5b5051919050565b5f808335601e19843603018112612e54575f80fd5b8301803591506001600160401b03821115612e6d575f80fd5b6020019150600581901b36038213156124c7575f80fd5b634e487b7160e01b5f52603260045260245ffd5b5f8235605e19833603018112612eac575f80fd5b9190910192915050565b634e487b7160e01b5f52604160045260245ffd5b604051606081016001600160401b0381118282101715612eec57612eec612eb6565b60405290565b604080519081016001600160401b0381118282101715612eec57612eec612eb6565b604051601f8201601f191681016001600160401b0381118282101715612f3c57612f3c612eb6565b604052919050565b5f6001600160401b03821115612f5c57612f5c612eb6565b50601f01601f191660200190565b5f82601f830112612f79575f80fd5b8135612f8c612f8782612f44565b612f14565b818152846020838601011115612fa0575f80fd5b816020850160208301375f918101602001919091529392505050565b5f60608236031215612fcc575f80fd5b612fd4612eca565b82356001600160401b0380821115612fea575f80fd5b612ff636838701612f6a565b8352602085013591508082111561300b575f80fd5b5061301836828601612f6a565b60208301525061302a60408401612b97565b604082015292915050565b5f8251612eac818460208701612c76565b601f821115610a1e57805f5260205f20601f840160051c8101602085101561306b5750805b601f840160051c820191505b8181101561308a575f8155600101613077565b5050505050565b81516001600160401b038111156130aa576130aa612eb6565b6130be816130b88454612dd0565b84613046565b602080601f8311600181146130f1575f84156130da5750858301515b5f19600386901b1c1916600185901b178555613148565b5f85815260208120601f198616915b8281101561311f57888601518255948401946001909101908401613100565b508582101561313c57878501515f19600388901b60f8161c191681555b505060018460011b0185555b505050505050565b634e487b7160e01b5f52601160045260245ffd5b80820180821115610a7557610a75613150565b5f63ffffffff80831681810361318f5761318f613150565b6001019392505050565b5f60208083525f84546131ab81612dd0565b806020870152604060018084165f81146131cc57600181146131e857613215565b60ff19851660408a0152604084151560051b8a01019550613215565b895f5260205f205f5b8581101561320c5781548b82018601529083019088016131f1565b8a016040019650505b509398975050505050505050565b818382375f9101908152919050565b80518015158114612b2b575f80fd5b5f8060408385031215613252575f80fd5b82516001600160401b0380821115613268575f80fd5b908401906060828703121561327b575f80fd5b613283612eca565b8251815260208084015161329681612bf2565b828201526040840151838111156132ab575f80fd5b80850194505087601f8501126132bf575f80fd5b835192506132cf612f8784612f44565b83815288828587010111156132e2575f80fd5b6132f184838301848801612c76565b80604084015250819550613306818801613232565b9450505050509250929050565b81810381811115610a7557610a75613150565b8082028115828204841417610a7557610a75613150565b5f808335601e19843603018112613352575f80fd5b8301803591506001600160401b0382111561336b575f80fd5b6020019150368190038213156124c7575f80fd5b5f6020828403121561338f575f80fd5b610a7282612b97565b5f88516133a9818460208d01612c76565b60e089901b6001600160e01b031916908301908152868860048301378681019050600481015f8152858782375060c09390931b6001600160c01b0319166004939094019283019390935250600c019695505050505050565b60208152816020820152818360408301375f818301604090810191909152601f909201601f19160101919050565b5f8235603e19833603018112612eac575f80fd5b5f60408236031215613453575f80fd5b61345b612ef2565b61346483612b18565b81526020808401356001600160401b0380821115613480575f80fd5b9085019036601f830112613492575f80fd5b8135818111156134a4576134a4612eb6565b8060051b91506134b5848301612f14565b81815291830184019184810190368411156134ce575f80fd5b938501935b838510156134f857843592506134e883612bf2565b82825293850193908501906134d3565b94860194909452509295945050505050565b6001600160401b0382811682821603908082111561119457611194613150565b6001600160401b0381811683821601908082111561119457611194613150565b6001600160401b0381811683821602808216919082811461356d5761356d613150565b505092915050565b61ffff60f01b8a60f01b1681525f63ffffffff60e01b808b60e01b166002840152896006840152808960e01b1660268401525086516135bb81602a850160208b01612c76565b8651908301906135d281602a840160208b01612c76565b60c087901b6001600160c01b031916602a9290910191820152613604603282018660e01b6001600160e01b0319169052565b61361d603682018560e01b6001600160e01b0319169052565b603a019b9a5050505050505050505050565b5f8351613640818460208801612c76565b60609390931b6bffffffffffffffffffffffff19169190920190815260140192915050565b5f8451613676818460208901612c76565b6001600160e01b031960e095861b8116919093019081529290931b16600482015260080192915050565b5f83516136b1818460208801612c76565b60c09390931b6001600160c01b0319169190920190815260080192915050565b5f6001600160401b0380831681810361318f5761318f613150565b5f602082840312156136fc575f80fd5b813560ff81168114612d5e575f80fdfee92546d698950ddd38910d2e15ed1d923cd0a7b3dde9e2a6a3f380565559cb00e92546d698950ddd38910d2e15ed1d923cd0a7b3dde9e2a6a3f380565559cb07a164736f6c6343000819000a",
            "balance": "0x0",
            "nonce": "0x1"
        },
        "0feedc0de0000000000000000000000000000000": {
            "code": "0x60806040523661001357610011610017565b005b6100115b61001f610169565b6001600160a01b0316330361015f5760606001600160e01b0319600035166364d3180d60e11b810161005a5761005361019c565b9150610157565b63587086bd60e11b6001600160e01b031982160161007a576100536101f3565b63070d7c6960e41b6001600160e01b031982160161009a57610053610239565b621eb96f60e61b6001600160e01b03198216016100b95761005361026a565b63a39f25e560e01b6001600160e01b03198216016100d9576100536102aa565b60405162461bcd60e51b815260206004820152604260248201527f5472616e73706172656e745570677261646561626c6550726f78793a2061646d60448201527f696e2063616e6e6f742066616c6c6261636b20746f2070726f78792074617267606482015261195d60f21b608482015260a4015b60405180910390fd5b815160208301f35b6101676102be565b565b60007fb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d61035b546001600160a01b0316919050565b60606101a66102ce565b60006101b53660048184610683565b8101906101c291906106c9565b90506101df816040518060200160405280600081525060006102d9565b505060408051602081019091526000815290565b60606000806102053660048184610683565b81019061021291906106fa565b91509150610222828260016102d9565b604051806020016040528060008152509250505090565b60606102436102ce565b60006102523660048184610683565b81019061025f91906106c9565b90506101df81610305565b60606102746102ce565b600061027e610169565b604080516001600160a01b03831660208201529192500160405160208183030381529060405291505090565b60606102b46102ce565b600061027e61035c565b6101676102c961035c565b61036b565b341561016757600080fd5b6102e28361038f565b6000825111806102ef5750805b15610300576102fe83836103cf565b505b505050565b7f7e644d79422f17c01e4894b5f4f588d331ebfa28653d42ae832dc59e38c9798f61032e610169565b604080516001600160a01b03928316815291841660208301520160405180910390a1610359816103fb565b50565b60006103666104a4565b905090565b3660008037600080366000845af43d6000803e80801561038a573d6000f35b3d6000fd5b610398816104cc565b6040516001600160a01b038216907fbc7cd75a20ee27fd9adebab32041f755214dbc6bffa90cc0225b39da2e5c2d3b90600090a250565b60606103f4838360405180606001604052806027815260200161083060279139610560565b9392505050565b6001600160a01b0381166104605760405162461bcd60e51b815260206004820152602660248201527f455243313936373a206e65772061646d696e20697320746865207a65726f206160448201526564647265737360d01b606482015260840161014e565b807fb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d61035b80546001600160a01b0319166001600160a01b039290921691909117905550565b60007f360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc61018d565b6001600160a01b0381163b6105395760405162461bcd60e51b815260206004820152602d60248201527f455243313936373a206e657720696d706c656d656e746174696f6e206973206e60448201526c1bdd08184818dbdb9d1c9858dd609a1b606482015260840161014e565b807f360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc610483565b6060600080856001600160a01b03168560405161057d91906107e0565b600060405180830381855af49150503d80600081146105b8576040519150601f19603f3d011682016040523d82523d6000602084013e6105bd565b606091505b50915091506105ce868383876105d8565b9695505050505050565b60608315610647578251600003610640576001600160a01b0385163b6106405760405162461bcd60e51b815260206004820152601d60248201527f416464726573733a2063616c6c20746f206e6f6e2d636f6e7472616374000000604482015260640161014e565b5081610651565b6106518383610659565b949350505050565b8151156106695781518083602001fd5b8060405162461bcd60e51b815260040161014e91906107fc565b6000808585111561069357600080fd5b838611156106a057600080fd5b5050820193919092039150565b80356001600160a01b03811681146106c457600080fd5b919050565b6000602082840312156106db57600080fd5b6103f4826106ad565b634e487b7160e01b600052604160045260246000fd5b6000806040838503121561070d57600080fd5b610716836106ad565b9150602083013567ffffffffffffffff8082111561073357600080fd5b818501915085601f83011261074757600080fd5b813581811115610759576107596106e4565b604051601f8201601f19908116603f01168101908382118183101715610781576107816106e4565b8160405282815288602084870101111561079a57600080fd5b8260208601602083013760006020848301015280955050505050509250929050565b60005b838110156107d75781810151838201526020016107bf565b50506000910152565b600082516107f28184602087016107bc565b9190910192915050565b602081526000825180602084015261081b8160408501602087016107bc565b601f01601f1916919091016040019291505056fe416464726573733a206c6f772d6c6576656c2064656c65676174652063616c6c206661696c6564a2646970667358221220b22984eb1f3348f5b2148862b6f80392e497e3c65d0d2cfbb5e53d737e5a6c6a64736f6c63430008190033",
            "storage": {
                "0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc": "0x0000000000000000000000000c0deba5e0000000000000000000000000000000",
                "0xb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d6103": "0x000000000000000000000000c0ffee1234567890abcdef1234567890abcdef34"
            },
            "balance": "0x0",
            "nonce": "0x1"
        },
        "32aaa04b1c166d02b0ee152dd221367687f72108": {
            "balance": "0x2086ac351052600000"
        },
        "48a90c916ad48a72f49fa72a9f889c1ba9cc9b4b": {
            "balance": "0x8ac7230489e80000"
        },
        "8db97c7cece249c2b98bdc0226cc4c2a57bf52fc": {
            "balance": "0xd3c21bcecceda1000000"
        },
        "c0ffee1234567890abcdef1234567890abcdef34": {
            "code": "0x60806040526004361061007b5760003560e01c80639623609d1161004e5780639623609d1461011157806399a88ec414610124578063f2fde38b14610144578063f3b7dead1461016457600080fd5b8063204e1c7a14610080578063715018a6146100bc5780637eff275e146100d35780638da5cb5b146100f3575b600080fd5b34801561008c57600080fd5b506100a061009b366004610499565b610184565b6040516001600160a01b03909116815260200160405180910390f35b3480156100c857600080fd5b506100d1610215565b005b3480156100df57600080fd5b506100d16100ee3660046104bd565b610229565b3480156100ff57600080fd5b506000546001600160a01b03166100a0565b6100d161011f36600461050c565b610291565b34801561013057600080fd5b506100d161013f3660046104bd565b610300565b34801561015057600080fd5b506100d161015f366004610499565b610336565b34801561017057600080fd5b506100a061017f366004610499565b6103b4565b6000806000836001600160a01b03166040516101aa90635c60da1b60e01b815260040190565b600060405180830381855afa9150503d80600081146101e5576040519150601f19603f3d011682016040523d82523d6000602084013e6101ea565b606091505b5091509150816101f957600080fd5b8080602001905181019061020d91906105e2565b949350505050565b61021d6103da565b6102276000610434565b565b6102316103da565b6040516308f2839760e41b81526001600160a01b038281166004830152831690638f283970906024015b600060405180830381600087803b15801561027557600080fd5b505af1158015610289573d6000803e3d6000fd5b505050505050565b6102996103da565b60405163278f794360e11b81526001600160a01b03841690634f1ef2869034906102c990869086906004016105ff565b6000604051808303818588803b1580156102e257600080fd5b505af11580156102f6573d6000803e3d6000fd5b5050505050505050565b6103086103da565b604051631b2ce7f360e11b81526001600160a01b038281166004830152831690633659cfe69060240161025b565b61033e6103da565b6001600160a01b0381166103a85760405162461bcd60e51b815260206004820152602660248201527f4f776e61626c653a206e6577206f776e657220697320746865207a65726f206160448201526564647265737360d01b60648201526084015b60405180910390fd5b6103b181610434565b50565b6000806000836001600160a01b03166040516101aa906303e1469160e61b815260040190565b6000546001600160a01b031633146102275760405162461bcd60e51b815260206004820181905260248201527f4f776e61626c653a2063616c6c6572206973206e6f7420746865206f776e6572604482015260640161039f565b600080546001600160a01b038381166001600160a01b0319831681178455604051919092169283917f8be0079c531659141344cd1fd0a4f28419497f9722a3daafe3b4186f6b6457e09190a35050565b6001600160a01b03811681146103b157600080fd5b6000602082840312156104ab57600080fd5b81356104b681610484565b9392505050565b600080604083850312156104d057600080fd5b82356104db81610484565b915060208301356104eb81610484565b809150509250929050565b634e487b7160e01b600052604160045260246000fd5b60008060006060848603121561052157600080fd5b833561052c81610484565b9250602084013561053c81610484565b9150604084013567ffffffffffffffff8082111561055957600080fd5b818601915086601f83011261056d57600080fd5b81358181111561057f5761057f6104f6565b604051601f8201601f19908116603f011681019083821181831017156105a7576105a76104f6565b816040528281528960208487010111156105c057600080fd5b8260208601602083013760006020848301015280955050505050509250925092565b6000602082840312156105f457600080fd5b81516104b681610484565b60018060a01b03831681526000602060406020840152835180604085015260005b8181101561063c57858101830151858201606001528201610620565b506000606082860101526060601f19601f83011685010192505050939250505056fea264697066735822122019f39983a6fd15f3cffa764efd6fb0234ffe8d71051b3ebddc0b6bd99f87fa9764736f6c63430008190033",
            "storage": {
                "0x0000000000000000000000000000000000000000000000000000000000000000": "0x00000000000000000000000048a90c916ad48a72f49fa72a9f889c1ba9cc9b4b"
            },
            "balance": "0x0",
            "nonce": "0x1"
        }
    },
    "airdropHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "airdropAmount": null,
    "number": "0x0",
    "gasUsed": "0x0",
    "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "baseFeePerGas": null,
    "excessBlobGas": null,
    "blobGasUsed": null
}
```

Open a text editor and copy the preceding text into a file called `custom_genesis.json`. For full breakdown of the genesis file, see the [Genesis File](/docs/avalanche-l1s/upgrade/customize-avalanche-l1#genesis).

<Callout title="Note">
The `timestamp` field is the Unix timestamp of the genesis block. `0x677eb2d9` represents
the timestamp 1736356569 which is the time this tutorial was written. You should use the
timestamp when you create your genesis file.
</Callout>

Create the Avalanche L1 Configuration[​](#create-the-avalanche-l1-configuration "Direct link to heading")
---------------------------------------------------------------------------------------------

Now that you have your binary, it's time to create the Avalanche L1 configuration. This tutorial uses `myblockchain` as it's Avalanche L1 name. Invoke the Avalanche L1 Creation Wizard with this command:

```bash
avalanche blockchain create myblockchain
```

### Choose Your VM[​](#choose-your-vm "Direct link to heading")

Select `Custom` for your VM.

```bash
Use the arrow keys to navigate: ↓ ↑ → ←
? Choose your VM:
    Subnet-EVM
  ▸ Custom
```

### Select Validator Manager type
```bash
Which validator management type would you like to use in your blockchain?:
  ▸ Proof Of Authority
    Proof Of Stake
    Explain the difference
```
Select the Validator manager that matches the `deployedBytecode` in your genesis. This tutorial is using Proof Of Authority.

Next, select the key that will be used to controller the PoA ValidatorManager contract:

```bash
Which address do you want to enable as controller of ValidatorManager contract?:
  ▸ Get address from an existing stored key (created from avalanche key create or avalanche key import)
    Custom
```
This key can add, remove and change weight of the validator set.

### Enter the Path to Your Genesis[​](#enter-the-path-to-your-genesis "Direct link to heading")

Enter the path to the genesis file you created in this [step](#create-a-custom-genesis).

```bash
✔ Enter path to custom genesis: ./custom_genesis.json
```

### ICM Setup

```bash
? Do you want to connect your blockchain with other blockchains or the C-Chain?:
    Yes, I want to enable my blockchain to interoperate with other blockchains and the C-Chain
  ▸ No, I want to run my blockchain isolated
    Explain the difference
```

Select no for now as we can setup ICM after deployment.

### Enter the Path to Your VM Binary[​](#enter-the-path-to-your-vm-binary "Direct link to heading")
```bash
? How do you want to set up the VM binary?:
    Download and build from a git repository (recommended for cloud deployments)
  ▸ I already have a VM binary (local network deployments only)
```
Select `I already have a VM binary`.
Next, enter the path to your VM binary. This should be the path to the `custom_evm.bin` you created [previously](#modify-and-build-subnet-evm).

```bash
✔ Enter path to vm binary: ./custom_vm.bin
```

### Wrapping Up[​](#wrapping-up "Direct link to heading")

If all worked successfully, the command prints:
```bash
✓ Successfully created blockchain configuration
Run 'avalanche blockchain describe' to view all created addresses and what their roles are
```

Now it's time to deploy it.

Deploy the Avalanche L1 Locally[​](#deploy-the-avalanche-l1-locally "Direct link to heading")
---------------------------------------------------------------------------------

To deploy your Avalanche L1, run:
```bash
avalanche blockchain deploy myblockchain
```


Make sure to substitute the name of your Avalanche L1 if you used a different one than `myblockchain`.

Next, select `Local Network`:

```bash
Use the arrow keys to navigate: ↓ ↑ → ←
? Choose a network to deploy on:
  ▸ Local Network
    Fuji
    Mainnet
```

This command boots a five node Avalanche network on your machine. It needs to download the latest versions of AvalancheGo and Subnet-EVM. The command may take a couple minutes to run.

If all works as expected, the command output should look something like this:

```bash
Deploying [myblockchain] to Local Network

Backend controller started, pid: 49158, output at: /Users/l1-dev/.avalanche-cli/runs/server_20250108_140532/avalanche-cli-backend.log

Installing avalanchego-v1.12.1...
avalanchego-v1.12.1 installation successful
AvalancheGo path: /Users/l1-dev/.avalanche-cli/bin/avalanchego/avalanchego-v1.12.1/avalanchego

Booting Network. Wait until healthy...

Node logs directory: /Users/l1-dev/.avalanche-cli/runs/network_20250108_140538/node<i>/logs

Network ready to use.

Your blockchain control keys: [P-custom18jma8ppw3nhx5r4ap8clazz0dps7rv5u9xde7p]
Your subnet auth keys for chain creation: [P-custom18jma8ppw3nhx5r4ap8clazz0dps7rv5u9xde7p]
CreateSubnetTx fee: 0.000010278 AVAX
Subnet has been created with ID: GEieSy2doZ96bpMo5CuHPaX1LvaxpKZ9C72L22j94t6YyUb6X
Now creating blockchain...
CreateChainTx fee: 0.000095896 AVAX
+-------------------------------------------------------------------+
|                         DEPLOYMENT RESULTS                        |
+---------------+---------------------------------------------------+
| Chain Name    | myblockchain                                      |
+---------------+---------------------------------------------------+
| Subnet ID     | GEieSy2doZ96bpMo5CuHPaX1LvaxpKZ9C72L22j94t6YyUb6X |
+---------------+---------------------------------------------------+
| VM ID         | qDNV9vtxZYYNqm7TN1mYBuaaknLdefDbFK8bFmMLTJQJKaWjV |
+---------------+---------------------------------------------------+
| Blockchain ID | 9FrNVEPkVpQyWDECQhEPDuT9oK98EhWQdg7anypKujVt9uSVT |
+---------------+                                                   |
| P-Chain TXID  |                                                   |
+---------------+---------------------------------------------------+

Restarting node node2 to track subnet
Restarting node node1 to track subnet
Waiting for http://127.0.0.1:9652/ext/bc/9FrNVEPkVpQyWDECQhEPDuT9oK98EhWQdg7anypKujVt9uSVT/rpc to be available
Waiting for http://127.0.0.1:9650/ext/bc/9FrNVEPkVpQyWDECQhEPDuT9oK98EhWQdg7anypKujVt9uSVT/rpc to be available
✓ Local Network successfully tracking myblockchain
✓ Subnet is successfully deployed Local Network
```

Use the describe command to find your L1s RPC: 
```bash
avalanche blockchain describe myblockchain
```

You can use the `RPC URL` to connect to and interact with your Avalanche L1.

Interact with Your Avalanche L1[​](#interact-with-your-avalanche-l1 "Direct link to heading")
---------------------------------------------------------------------------------

### Check the Version[​](#check-the-version "Direct link to heading")

You can verify that your Avalanche L1 has deployed correctly by querying the local node to see what Avalanche L1s it's running. You need to use the [`getNodeVersion`](/docs/api-reference/info-api#infogetnodeversion) endpoint. Try running this curl command:

```bash
curl --location --request POST 'http://127.0.0.1:9650/ext/info' \
--header 'Content-Type: application/json' \
--data-raw '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"info.getNodeVersion",
    "params" :{
    }
}'
```

The command returns a list of all the VMs your local node is currently running along with their versions.

```json
{
  "jsonrpc": "2.0",
  "result": {
    "version": "avalanche/1.10.8",
    "databaseVersion": "v1.4.5",
    "rpcProtocolVersion": "27",
    "gitCommit": "e70a17d9d988b5067f3ef5c4a057f15ae1271ac4",
    "vmVersions": {
      "avm": "v1.10.8",
      "evm": "v0.12.5",
      "platform": "v1.10.8",
      "qDMnZ895HKpRXA2wEvujJew8nNFEkvcrH5frCR9T1Suk1sREe": "v0.5.4@c0fe6506a40da466285f37dd0d3c044f494cce32"
    }
  },
  "id": 1
}
```

Your results may be slightly different, but you can see that in addition to the X-Chain's `avm`, the C-Chain's `evm`, and the P-Chain's `platform` VM, the node is running the custom VM with commit `c0fe6506a40da466285f37dd0d3c044f494cce32`.

### Check a Balance[​](#check-a-balance "Direct link to heading")

If you used the default genesis, your custom VM has a prefunded address. You can verify its balance with a curl command. Make sure to substitute the command's URL with the `RPC URL` from your deployment output.

```bash
curl --location --request POST 'http://127.0.0.1:9650/ext/bc/myblockchain/rpc' \
--header 'Content-Type: application/json' \
--data-raw '{
    "jsonrpc": "2.0",
    "method": "eth_getBalance",
    "params": [
        "0x8db97c7cece249c2b98bdc0226cc4c2a57bf52fc",
        "latest"
    ],
    "id": 1
}'
```

The command should return:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": "0xd3c21bcecceda1000000"
}
```

The balance is hex encoded, so this means the address has a balance of 1 million tokens.

Note, this command doesn't work on all custom VMs, only VMs that implement the EVM's `eth_getBalance` interface.

Next Steps[​](#next-steps "Direct link to heading")
---------------------------------------------------

You've now unlocked the ability to deploy custom VMs. Go build something cool!


# With Multisig Auth (/docs/tooling/avalanche-cli/create-deploy-avalanche-l1s/deploy-with-multisig-auth)

---
title: With Multisig Auth
description: Learn how to create an Avalanche L1 with a multisig authorization.
---

Avalanche L1 creators can control critical Avalanche L1 operations with a N of M multisig. This multisig must be setup at deployment time and can't be edited afterward. Multisigs can are available on both the Fuji Testnet and Mainnet.

To setup your multisig, you need to know the P-Chain address of each key holder and what you want your signing threshold to be.

<Callout title="Note">
Avalanche-CLI requires Ledgers for Mainnet deployments. This how-to guide assumes the use of Ledgers for setting up your multisig.
</Callout>

## Prerequisites

- [`Avalanche-CLI`](https://github.com/ava-labs/avalanche-cli) installed
- Familiarity with process of [Deploying an Avalanche L1 on Testnet](/docs/tooling/create-deploy-avalanche-l1s/deploy-on-fuji-testnet) and [Deploying a Permissioned Avalanche L1 on Mainnet](/docs/tooling/create-deploy-avalanche-l1s/deploy-on-mainnet)
- Multiple Ledger devices [configured for Avalanche](/docs/tooling/create-deploy-avalanche-l1s/deploy-on-mainnet#setting-up-your-ledger)
- an Avalanche L1 configuration ready to deploy to either Fuji Testnet or Mainnet

Getting Started[​](#getting-started "Direct link to heading")
-------------------------------------------------------------

When issuing the transactions to create the Avalanche L1, you need to sign the TXs with multiple keys from the multisig.

### Specify Network[​](#specify-network "Direct link to heading")

Start the Avalanche L1 deployment with

```bash
avalanche blockchain deploy testAvalanche L1
```

First step is to specify `Fuji` or `Mainnet` as the network:

```bash
Use the arrow keys to navigate: ↓ ↑ → ←
? Choose a network to deploy on:
    Local Network
    Fuji
  ▸ Mainnet
```

```bash
Deploying [testblockchain] to Mainnet
```

Ledger is automatically recognized as the signature mechanism on `Mainnet`.

After that, the CLI shows the first `Mainnet` Ledger address.

```bash
Ledger address: P-avax1kdzq569g2c9urm9887cmldlsa3w3jhxe0knfy5
```

### Set Control Keys[​](#set-control-keys "Direct link to heading")

Next the CLI asks the user to specify the control keys. This is where you setup your multisig.

```bash
Configure which addresses may make changes to the Avalanche L1.
These addresses are known as your control keys. You are going to also
set how many control keys are required to make an Avalanche L1 change (the threshold).
Use the arrow keys to navigate: ↓ ↑ → ←
? How would you like to set your control keys?:
  ▸ Use ledger address
    Custom list
```

Select `Custom list` and add every address that you'd like to be a key holder on the multisig.

```bash
✔ Custom list
? Enter control keys:
  ▸ Add
    Delete
    Preview
    More Info
↓   Done
```

Use the given menu to add each key, and select `Done` when finished.

The output at this point should look something like:

```bash
✔ Custom list
✔ Add
Enter P-Chain address (Example: P-...): P-avax1wryu62weky9qjlp40cpmnqf6ml2hytnagj5q28
✔ Add
Enter P-Chain address (Example: P-...): P-avax1kdzq569g2c9urm9887cmldlsa3w3jhxe0knfy5
✔ Add
Enter P-Chain address (Example: P-...): P-avax12gcy0xl0al6gcjrt0395xqlcuq078ml93wl5h8
✔ Add
Enter P-Chain address (Example: P-...): P-avax1g7nkguzg8yju8cq3ndzc9lql2yg69s9ejqa2af
✔ Add
Enter P-Chain address (Example: P-...): P-avax1g4eryh40dtcsltmxn9zk925ny07gdq2xyjtf4g
✔ Done
Your Avalanche L1's control keys: [P-avax1wryu62weky9qjlp40cpmnqf6ml2hytnagj5q28 P-avax1kdzq569g2c9urm9887cmldlsa3w3jhxe0knfy5 P-avax12gcy0xl0al6gcjrt0395xqlcuq078ml93wl5h8 P-avax1g7nkguzg8yju8cq3ndzc9lql2yg69s9ejqa2af P-avax1g4eryh40dtcsltmxn9zk925ny07gdq2xyjtf4g]
```

<Callout title="Note">
When deploying an Avalanche L1 with Ledger, you must include the Ledger's default address determined in [Specify Network](#specify-network) for the deployment to succeed. You may see an error like

```
Error: wallet does not contain Avalanche L1 auth keys
exit status 1
```
</Callout>

### Set Threshold[​](#set-threshold "Direct link to heading")

Next, specify the threshold. In your N of M multisig, your threshold is N, and M is the number of control keys you added in the previous step.

```bash
Use the arrow keys to navigate: ↓ ↑ → ←
? Select required number of control key signatures to make an Avalanche L1 change:
  ▸ 1
    2
    3
    4
    5
```

### Specify Control Keys to Sign the Chain Creation TX[​](#specify-control-keys-to-sign-the-chain-creation-tx "Direct link to heading")

You now need N of your key holders to sign the Avalanche L1 deployment transaction. You must select which addresses you want to sign the TX.

```bash
? Choose an Avalanche L1 auth key:
  ▸ P-avax1wryu62weky9qjlp40cpmnqf6ml2hytnagj5q28
    P-avax1kdzq569g2c9urm9887cmldlsa3w3jhxe0knfy5
    P-avax12gcy0xl0al6gcjrt0395xqlcuq078ml93wl5h8
    P-avax1g7nkguzg8yju8cq3ndzc9lql2yg69s9ejqa2af
    P-avax1g4eryh40dtcsltmxn9zk925ny07gdq2xyjtf4g
```

A successful control key selection looks like:

```bash
✔ 2
✔ P-avax1kdzq569g2c9urm9887cmldlsa3w3jhxe0knfy5
✔ P-avax1g7nkguzg8yju8cq3ndzc9lql2yg69s9ejqa2af
Your subnet auth keys for chain creation: [P-avax1kdzq569g2c9urm9887cmldlsa3w3jhxe0knfy5 P-avax1g7nkguzg8yju8cq3ndzc9lql2yg69s9ejqa2af]
*** Please sign Avalanche L1 creation hash on the ledger device ***
```

#### Potential Errors[​](#potential-errors "Direct link to heading")

If the currently connected Ledger address isn't included in your TX signing group, the operation fails with:

```bash
✔ 2
✔ P-avax1g7nkguzg8yju8cq3ndzc9lql2yg69s9ejqa2af
✔ P-avax1g4eryh40dtcsltmxn9zk925ny07gdq2xyjtf4g
Your Avalanche L1 auth keys for chain creation: [P-avax1g7nkguzg8yju8cq3ndzc9lql2yg69s9ejqa2af P-avax1g4eryh40dtcsltmxn9zk925ny07gdq2xyjtf4g]
Error: wallet does not contain Avalanche L1 auth keys
exit status 1
```

This can happen either because the original specified control keys -previous step- don't contain the Ledger address, or because the Ledger address control key wasn't selected in the current step.

If the user has the correct address but doesn't have sufficient balance to pay for the TX, the operation fails with:

```bash
✔ 2
✔ P-avax1g7nkguzg8yju8cq3ndzc9lql2yg69s9ejqa2af
✔ P-avax1g4eryh40dtcsltmxn9zk925ny07gdq2xyjtf4g
Your Avalanche L1 auth keys for chain creation: [P-avax1g7nkguzg8yju8cq3ndzc9lql2yg69s9ejqa2af P-avax1g4eryh40dtcsltmxn9zk925ny07gdq2xyjtf4g]
*** Please sign Avalanche L1 creation hash on the ledger device ***
Error: insufficient funds: provided UTXOs need 1000000000 more units of asset "rgNLkDPpANwqg3pHC4o9aGJmf2YU4GgTVUMRKAdnKodihkqgr"
exit status 1
```

### Sign Avalanche L1 Deployment TX with the First Address[​](#sign-avalanche-l1-deployment-tx-with-the-first-address "Direct link to heading")

The Avalanche L1 Deployment TX is ready for signing.

```bash
*** Please sign Avalanche L1 creation hash on the ledger device ***
```

This activates a `Please review` window on the Ledger. Navigate to the Ledger's `APPROVE` window by using the Ledger's right button, and then authorize the request by pressing both left and right buttons.

```bash
Avalanche L1 has been created with ID: 2qUKjvPx68Fgc1NMi8w4mtaBt5hStgBzPhsQrS1m7vSub2q9ew. Now creating blockchain...
*** Please sign blockchain creation hash on the ledger device ***
```

After successful Avalanche L1 creation, the CLI asks the user to sign the blockchain creation TX.

This activates a `Please review` window on the Ledger. Navigate to the Ledger's `APPROVE` window by using the Ledger's right button, and then authorize the request by pressing both left and right buttons.

On success, the CLI provides Avalanche L1 deploy details. As only one address signed the chain creation TX, the CLI writes a file to disk to save the TX to continue the signing process with another command.

```bash
+--------------------+----------------------------------------------------+
| DEPLOYMENT RESULTS |                                                    |
+--------------------+----------------------------------------------------+
| Chain Name         | testblockchain                                         |
+--------------------+----------------------------------------------------+
| Subnet ID          | 2qUKjvPx68Fgc1NMi8w4mtaBt5hStgBzPhsQrS1m7vSub2q9ew |
+--------------------+----------------------------------------------------+
| VM ID              | rW1esjm6gy4BtGvxKMpHB2M28MJGFNsqHRY9AmnchdcgeB3ii  |
+--------------------+----------------------------------------------------+

1 of 2 required Blockchain Creation signatures have been signed. Saving TX to disk to enable remaining signing.

Path to export partially signed TX to:
```

Enter the name of file to write to disk, such as `partiallySigned.txt`. This file shouldn't exist already.

```bash
Path to export partially signed TX to: partiallySigned.txt

Addresses remaining to sign the tx: P-avax1g7nkguzg8yju8cq3ndzc9lql2yg69s9ejqa2af

Connect a ledger with one of the remaining addresses or choose a stored key and run the signing command, or send "partiallySigned.txt" to another user for signing.

Signing command: avalanche transaction sign testblockchain --input-tx-filepath partiallySigned.txt
```

Gather Remaining Signatures and Issue the Avalanche L1 Deployment TX[​](#gather-remaining-signatures-and-issue-the-avalanche-l1-deployment-tx "Direct link to heading")
-----------------------------------------------------------------------------------------------------------------------------------------------------------

So far, one address has signed the Avalanche L1 deployment TX, but you need N signatures. Your Avalanche L1 has not been fully deployed yet. To get the remaining signatures, you may connect a different Ledger to the same computer you've been working on. Alternatively, you may send the `partiallySigned.txt` file to other users to sign themselves.

The remainder of this section assumes that you are working on a machine with access to both the remaining keys and the `partiallySigned.txt` file.

### Issue the Command to Sign the Chain Creation TX[​](#issue-the-command-to-sign-the-chain-creation-tx "Direct link to heading")

Avalanche-CLI can detect the deployment network automatically. For `Mainnet` TXs, it uses your Ledger automatically. For `Fuji Testnet`, the CLI prompts the user to choose the signing mechanism.

You can start the signing process with the `transaction sign` command:

```bash
avalanche transaction sign testblockchain --input-tx-filepath partiallySigned.txt
```

```bash
Ledger address: P-avax1g7nkguzg8yju8cq3ndzc9lql2yg69s9ejqa2af
*** Please sign TX hash on the ledger device ***
```

Next, the CLI starts a new signing process for the Avalanche L1 deployment TX. If the Ledger isn't the correct one, the following error should appear instead:

```bash
Ledger address: P-avax1kdzq569g2c9urm9887cmldlsa3w3jhxe0knfy5
Error: wallet does not contain Avalanche L1 auth keys
exit status 1
```

This activates a `Please review` window on the Ledger. Navigate to the Ledger's `APPROVE` window by using the Ledger's right button, and then authorize the request by pressing both left and right buttons.

Repeat this processes until all required parties have signed the TX. You should see a message like this:

```bash
All 2 required Tx signatures have been signed. Saving TX to disk to enable commit.

Overwriting partiallySigned.txt

Tx is fully signed, and ready to be committed

Commit command: avalanche transaction commit testblockchain --input-tx-filepath partiallySigned.txt
```

Now, `partiallySigned.txt` contains a fully signed TX.

### Commit the Avalanche L1 Deployment TX[​](#commit-the-avalanche-l1-deployment-tx "Direct link to heading")

To run submit the fully signed TX, run:

```bash
avalanche transaction commit testblockchain --input-tx-filepath partiallySigned.txt
```

The CLI recognizes the deployment network automatically and submits the TX appropriately.

```bash
+--------------------+-------------------------------------------------------------------------------------+
| DEPLOYMENT RESULTS |                                                                                     |
+--------------------+-------------------------------------------------------------------------------------+
| Chain Name         | testblockchain                                                                          |
+--------------------+-------------------------------------------------------------------------------------+
| Subnet ID          | 2qUKjvPx68Fgc1NMi8w4mtaBt5hStgBzPhsQrS1m7vSub2q9ew                                  |
+--------------------+-------------------------------------------------------------------------------------+
| VM ID              | rW1esjm6gy4BtGvxKMpHB2M28MJGFNsqHRY9AmnchdcgeB3ii                                   |
+--------------------+-------------------------------------------------------------------------------------+
| Blockchain ID      | 2fx9EF61C964cWBu55vcz9b7gH9LFBkPwoj49JTSHA6Soqqzoj                                  |
+--------------------+-------------------------------------------------------------------------------------+
| RPC URL            | http://127.0.0.1:9650/ext/bc/2fx9EF61C964cWBu55vcz9b7gH9LFBkPwoj49JTSHA6Soqqzoj/rpc |
+--------------------+-------------------------------------------------------------------------------------+
| P-Chain TXID       | 2fx9EF61C964cWBu55vcz9b7gH9LFBkPwoj49JTSHA6Soqqzoj                                  |
+--------------------+-------------------------------------------------------------------------------------+
```

Your Avalanche L1 successfully deployed with a multisig.

Add Validators Using the Multisig[​](#add-validators-using-the-multisig "Direct link to heading")
-------------------------------------------------------------------------------------------------

The `addValidator` command also requires use of the multisig. Before starting, make sure to connect, unlock, and run the Avalanche Ledger app.

```bash
avalanche blockchain addValidator testblockchain
```

### Select Network[​](#select-network "Direct link to heading")

First specify the network. Select either `Fuji` or `Mainnet`:

```bash
Use the arrow keys to navigate: ↓ ↑ → ←
? Choose a network to add validator to.:
  ▸ Fuji
    Mainnet
```

### Choose Signing Keys[​](#choose-signing-keys "Direct link to heading")

Then, similar to the `deploy` command, the command asks the user to select the N control keys needed to sign the TX.

```bash
✔ Mainnet
Use the arrow keys to navigate: ↓ ↑ → ←
? Choose an Avalanche L1 auth key:
  ▸ P-avax1wryu62weky9qjlp40cpmnqf6ml2hytnagj5q28
    P-avax1kdzq569g2c9urm9887cmldlsa3w3jhxe0knfy5
    P-avax12gcy0xl0al6gcjrt0395xqlcuq078ml93wl5h8
    P-avax1g7nkguzg8yju8cq3ndzc9lql2yg69s9ejqa2af
    P-avax1g4eryh40dtcsltmxn9zk925ny07gdq2xyjtf4g
```

```bash
✔ Mainnet
✔ P-avax1kdzq569g2c9urm9887cmldlsa3w3jhxe0knfy5
✔ P-avax1g7nkguzg8yju8cq3ndzc9lql2yg69s9ejqa2af
Your subnet auth keys for add validator TX creation: [P-avax1kdzq569g2c9urm9887cmldlsa3w3jhxe0knfy5 P-avax1g7nkguzg8yju8cq3ndzc9lql2yg69s9ejqa2af].
```

### Finish Assembling the TX[​](#finish-assembling-the-tx "Direct link to heading")

Take a look at [Add a Validator](/docs/tooling/create-deploy-avalanche-l1s/deploy-on-mainnet#add-a-validator) for additional help issuing this transaction.

<Callout title="Note">
If setting up a multisig, don't select your validator start time to be in one minute. Finishing the signing process takes significantly longer when using a multisig.
</Callout>

```bash
Next, we need the NodeID of the validator you want to whitelist.

Check https://build.avax.network/docs/api-reference/info-api#info-getnodeid for instructions about how to query the NodeID from your node
(Edit host IP address and port to match your deployment, if needed).
What is the NodeID of the validator you'd like to whitelist?: NodeID-7Xhw2mDxuDS44j42TCB6U5579esbSt3Lg
✔ Default (20)
When should your validator start validating?
If your validator is not ready by this time, Avalanche L1 downtime can occur.
✔ Custom
When should the validator start validating? Enter a UTC datetime in 'YYYY-MM-DD HH:MM:SS' format: 2022-11-22 23:00:00
✔ Until primary network validator expires
NodeID: NodeID-7Xhw2mDxuDS44j42TCB6U5579esbSt3Lg
Network: Local Network
Start time: 2022-11-22 23:00:00
End time: 2023-11-22 15:57:27
Weight: 20
Inputs complete, issuing transaction to add the provided validator information...
```

```bash
Ledger address: P-avax1kdzq569g2c9urm9887cmldlsa3w3jhxe0knfy5
*** Please sign add validator hash on the ledger device ***
```

After that, the command shows the connected Ledger's address, and asks the user to sign the TX with the Ledger.

```bash
Partial TX created

1 of 2 required Add Validator signatures have been signed. Saving TX to disk to enable remaining signing.

Path to export partially signed TX to:
```

Because you've setup a multisig, TX isn't fully signed, and the commands asks a file to write into. Use something like `partialAddValidatorTx.txt`.

```bash
Path to export partially signed TX to: partialAddValidatorTx.txt

Addresses remaining to sign the tx: P-avax1g7nkguzg8yju8cq3ndzc9lql2yg69s9ejqa2af

Connect a Ledger with one of the remaining addresses or choose a stored key and run the signing command, or send "partialAddValidatorTx.txt" to another user for signing.

Signing command: avalanche transaction sign testblockchain --input-tx-filepath partialAddValidatorTx.txt
```

Sign and Commit the Add Validator TX[​](#sign-and-commit-the-add-validator-tx "Direct link to heading")
-------------------------------------------------------------------------------------------------------

The process is very similar to signing of Avalanche L1 Deployment TX. So far, one address has signed the TX, but you need N signatures. To get the remaining signatures, you may connect a different Ledger to the same computer you've been working on. Alternatively, you may send the `partialAddValidatorTx.txt` file to other users to sign themselves.

The remainder of this section assumes that you are working on a machine with access to both the remaining keys and the `partialAddValidatorTx.txt` file.

### Issue the Command to Sign the Add Validator TX[​](#issue-the-command-to-sign-the-add-validator-tx "Direct link to heading")

Avalanche-CLI can detect the deployment network automatically. For `Mainnet` TXs, it uses your Ledger automatically. For `Fuji Testnet`, the CLI prompts the user to choose the signing mechanism.

```bash
avalanche transaction sign testblockchain --input-tx-filepath partialAddValidatorTx.txt
```

```bash
Ledger address: P-avax1g7nkguzg8yju8cq3ndzc9lql2yg69s9ejqa2af
*** Please sign TX hash on the ledger device ***
```

Next, the command is going to start a new signing process for the Add Validator TX.

This activates a `Please review` window on the Ledger. Navigate to the Ledger's `APPROVE` window by using the Ledger's right button, and then authorize the request by pressing both left and right buttons.

Repeat this processes until all required parties have signed the TX. You should see a message like this:

```bash
All 2 required Tx signatures have been signed. Saving TX to disk to enable commit.

Overwriting partialAddValidatorTx.txt

Tx is fully signed, and ready to be committed

Commit command: avalanche transaction commit testblockchain --input-tx-filepath partialAddValidatorTx.txt
```

Now, `partialAddValidatorTx.txt` contains a fully signed TX.

### Issue the Command to Commit the add validator TX[​](#issue-the-command-to-commit-the-add-validator-tx "Direct link to heading")

To run submit the fully signed TX, run:

```bash
avalanche transaction commit testblockchain --input-tx-filepath partialAddValidatorTx.txt
```

The CLI recognizes the deployment network automatically and submits the TX appropriately.

```bash
Transaction successful, transaction ID: K7XNSwcmgjYX7BEdtFB3hEwQc6YFKRq9g7hAUPhW4J5bjhEJG
```

You've successfully added the validator to the Avalanche L1.


# Teleporter on Devnet (/docs/tooling/avalanche-cli/cross-chain/teleporter-devnet)

---
title: Teleporter on Devnet
description: This how-to guide focuses on deploying Teleporter-enabled Avalanche L1s to a Devnet.
---

After this tutorial, you would have created a Devnet and deployed two Avalanche L1s in it, and have enabled them to cross-communicate with each other and with the C-Chain through Teleporter and the underlying Warp technology.

For more information on cross chain messaging through Teleporter and Warp, check:

- [Cross Chain References](/docs/cross-chain)

Note that currently only [Subnet-EVM](https://github.com/ava-labs/subnet-evm) and [Subnet-EVM-Based](/docs/virtual-machines/evm-customization/introduction) virtual machines support Teleporter.

## Prerequisites

Before we begin, you will need to have:

- Created an AWS account and have an updated AWS `credentials` file in home directory with \[default\] profile

Note: the tutorial uses AWS hosts, but Devnets can also be created and operated in other supported cloud providers, such as GCP.

Create Avalanche L1s Configurations[​](#create-avalanche-l1s-configurations "Direct link to heading")
-----------------------------------------------------------------------------------------

For this section we will follow this [steps](/docs/tooling/cross-chain/teleporter-local-network#create-avalanche-l1s-configurations), to create two Teleporter-enabled Avalanche L1s, `<chain1>` and `<chain2>`.

Create a Devnet and Deploy an Avalanche L1 in It[​](#create-a-devnet-and-deploy-a-avalanche-l1-in-it "Direct link to heading")
-----------------------------------------------------------------------------------------------------------------

Let's use the `devnet wiz` command to create a devnet `<devnetName>` and deploy `<chain1>` in it.

The devnet will be created in the `us-east-1` region of AWS, and will consist of 5 validators only.

```bash
avalanche node devnet wiz <devnetName> <chain1> --aws --node-type default --region us-east-1 --num-validators 5 --num-apis 0 --enable-monitoring=false --default-validator-params 

Creating the devnet...

Creating new EC2 instance(s) on AWS...
...

Deploying [chain1] to Cluster <devnetName>
...

configuring AWM RElayer on host i-0f1815c016b555fcc

Setting the nodes as subnet trackers
...

Setting up teleporter on subnet

Teleporter Messenger successfully deployed to chain1 (0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf)
Teleporter Registry successfully deployed to chain1 (0xb623C4495220C603D0A939D32478F55891a61750)
Teleporter Messenger successfully deployed to c-chain (0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf)
Teleporter Registry successfully deployed to c-chain (0x5DB9A7629912EBF95876228C24A848de0bfB43A9)

Starting AWM Relayer Service

setting AWM Relayer on host i-0f1815c016b555fcc to relay subnet chain1
updating configuration file ~/.avalanche-cli/nodes/i-0f1815c016b555fcc/services/awm-relayer/awm-relayer-config.json

Devnet <devnetName> is successfully created and is now validating subnet chain1!

Subnet <chain1> RPC URL: http://67.202.23.231:9650/ext/bc/fqcM24LNb3kTV7KD1mAvUJXYy5XunwP8mrE44YuNwPjgZHY6p/rpc
 
✓ Cluster information YAML file can be found at ~/.avalanche-cli/nodes/inventories/<devnetName>/clusterInfo.yaml at local host
```

Notice some details here:

- Two smart contracts are deployed to the Avalanche L1: Teleporter Messenger and Teleporter Registry
- Both Teleporter smart contracts are also deployed to `C-Chain`
- [AWM Teleporter Relayer](https://github.com/ava-labs/awm-relayer) is installed and configured as a service into one of the nodes (A Relayer [listens](/docs/cross-chain/teleporter/overview#data-flow) for new messages being generated on a source Avalanche L1 and sends them to the destination Avalanche L1.)

CLI configures the Relayer to enable every Avalanche L1 to send messages to all other Avalanche L1s. If you add more Avalanche L1s to the Devnet, the Relayer will be automatically reconfigured.

Checking Devnet Configuration and Relayer Logs[​](#checking-devnet-configuration-and-relayer-logs "Direct link to heading")
---------------------------------------------------------------------------------------------------------------------------

Execute `node list` command to get a list of the devnet nodes:

```bash
avalanche node list

Cluster "<devnetName>" (Devnet)
  Node i-0f1815c016b555fcc (NodeID-91PGQ7keavfSV1XVFva2WsQXWLWZqqqKe) 67.202.23.231 [Validator,Relayer]
  Node i-026392a651571232c (NodeID-AkPyyTs9e9nPGShdSoxdvWYZ6X2zYoyrK) 52.203.183.68 [Validator]
  Node i-0d1b98d5d941d6002 (NodeID-ByEe7kuwtrPStmdMgY1JiD39pBAuFY2mS) 50.16.235.194 [Validator]
  Node i-0c291f54bb38c2984 (NodeID-8SE2CdZJExwcS14PYEqr3VkxFyfDHKxKq) 52.45.0.56 [Validator]
  Node i-049916e2f35231c29 (NodeID-PjQY7xhCGaB8rYbkXYddrr1mesYi29oFo) 3.214.163.110 [Validator]
```

Notice that, in this case, `i-0f1815c016b555fcc` was set as Relayer. This host contains a `systemd` service called `awm-relayer` that can be used to check the Relayer logs, and set the execution status.

To view the Relayer logs, the following command can be used:

```bash
avalanche node ssh i-0f1815c016b555fcc "journalctl -u awm-relayer --no-pager"

  [Node i-0f1815c016b555fcc (NodeID-91PGQ7keavfSV1XVFva2WsQXWLWZqqqKe) 67.202.23.231 [Validator,Relayer]]
Warning: Permanently added '67.202.23.231' (ED25519) to the list of known hosts.
-- Logs begin at Fri 2024-04-05 14:11:43 UTC, end at Fri 2024-04-05 14:30:24 UTC. --
Apr 05 14:15:06 ip-172-31-47-187 systemd[1]: Started AWM Relayer systemd service.
Apr 05 14:15:07 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:07.018Z","logger":"awm-relayer","caller":"main/main.go:66","msg":"Initializing awm-relayer"}
Apr 05 14:15:07 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:07.018Z","logger":"awm-relayer","caller":"main/main.go:71","msg":"Set config options."}
Apr 05 14:15:07 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:07.018Z","logger":"awm-relayer","caller":"main/main.go:78","msg":"Initializing destination clients"}
Apr 05 14:15:07 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:07.021Z","logger":"awm-relayer","caller":"main/main.go:97","msg":"Initializing app request network"}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.159Z","logger":"awm-relayer","caller":"main/main.go:309","msg":"starting metrics server...","port":9090}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.160Z","logger":"awm-relayer","caller":"main/main.go:251","msg":"Creating relayer","originBlockchainID":"fqcM24LNb3kTV7KD1mAvUJXYy5XunwP8mrE44YuNwPjgZHY6p"}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.160Z","logger":"awm-relayer","caller":"main/main.go:251","msg":"Creating relayer","originBlockchainID":"2EfJg86if9Ka5Ag73JRfoqWz4EGuFwtemaNf4XiBBpUW4YngS6"}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.160Z","logger":"awm-relayer","caller":"relayer/relayer.go:114","msg":"Creating relayer","subnetID":"11111111111111111111111111111111LpoYY","subnetIDHex":"0000000000000000000000000000000000000000000000000000000000000000","blockchainID":"2EfJg86if9Ka5Ag73JRfoqWz4EGuFwtemaNf4XiBBpUW4YngS6","blockchainIDHex":"a2b6b947cf2b9bf6df03c8caab08e38ab951d8b120b9c37265d9be01d86bb170"}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.160Z","logger":"awm-relayer","caller":"relayer/relayer.go:114","msg":"Creating relayer","subnetID":"giY8tswWgZmcAWzPkoNrmjjrykited7GJ9799SsFzTiq5a1ML","subnetIDHex":"5a2e2d87d74b4ec62fdd6626e7d36a44716484dfcc721aa4f2168e8a61af63af","blockchainID":"fqcM24LNb3kTV7KD1mAvUJXYy5XunwP8mrE44YuNwPjgZHY6p","blockchainIDHex":"582fc7bd55472606c260668213bf1b6d291df776c9edf7e042980a84cce7418a"}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.171Z","logger":"awm-relayer","caller":"evm/subscriber.go:247","msg":"Successfully subscribed","blockchainID":"2EfJg86if9Ka5Ag73JRfoqWz4EGuFwtemaNf4XiBBpUW4YngS6"}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.171Z","logger":"awm-relayer","caller":"relayer/relayer.go:161","msg":"processed-missed-blocks set to false, starting processing from chain head","blockchainID":"2EfJg86if9Ka5Ag73JRfoqWz4EGuFwtemaNf4XiBBpUW4YngS6"}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.172Z","logger":"awm-relayer","caller":"relayer/message_relayer.go:662","msg":"Updating latest processed block in database","relayerID":"0xea06381426934ec1800992f41615b9d362c727ad542f6351dbfa7ad2849a35bf","latestBlock":6}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.173Z","logger":"awm-relayer","caller":"relayer/message_relayer.go:662","msg":"Updating latest processed block in database","relayerID":"0x175e14327136d57fe22d4bdd295ff14bea8a7d7ab1884c06a4d9119b9574b9b3","latestBlock":6}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.173Z","logger":"awm-relayer","caller":"main/main.go:272","msg":"Created relayer","blockchainID":"2EfJg86if9Ka5Ag73JRfoqWz4EGuFwtemaNf4XiBBpUW4YngS6"}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.173Z","logger":"awm-relayer","caller":"main/main.go:295","msg":"Relayer initialized. Listening for messages to relay.","originBlockchainID":"2EfJg86if9Ka5Ag73JRfoqWz4EGuFwtemaNf4XiBBpUW4YngS6"}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.178Z","logger":"awm-relayer","caller":"evm/subscriber.go:247","msg":"Successfully subscribed","blockchainID":"fqcM24LNb3kTV7KD1mAvUJXYy5XunwP8mrE44YuNwPjgZHY6p"}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.178Z","logger":"awm-relayer","caller":"relayer/relayer.go:161","msg":"processed-missed-blocks set to false, starting processing from chain head","blockchainID":"fqcM24LNb3kTV7KD1mAvUJXYy5XunwP8mrE44YuNwPjgZHY6p"}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.179Z","logger":"awm-relayer","caller":"relayer/message_relayer.go:662","msg":"Updating latest processed block in database","relayerID":"0xe584ccc0df44506255811f6b54375e46abd5db40a4c84fd9235a68f7b69c6f06","latestBlock":6}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.179Z","logger":"awm-relayer","caller":"relayer/message_relayer.go:662","msg":"Updating latest processed block in database","relayerID":"0x70f14d33bde4716928c5c4723d3969942f9dfd1f282b64ffdf96f5ac65403814","latestBlock":6}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.180Z","logger":"awm-relayer","caller":"main/main.go:272","msg":"Created relayer","blockchainID":"fqcM24LNb3kTV7KD1mAvUJXYy5XunwP8mrE44YuNwPjgZHY6p"}
Apr 05 14:15:08 ip-172-31-47-187 awm-relayer[6886]: {"level":"info","timestamp":"2024-04-05T14:15:08.180Z","logger":"awm-relayer","caller":"main/main.go:295","msg":"Relayer initialized. Listening for messages to relay.","originBlockchainID":"fqcM24LNb3kTV7KD1mAvUJXYy5XunwP8mrE44YuNwPjgZHY6p"}
```

Deploying the Second Avalanche L1[​](#deploying-the-second-avalanche-l1 "Direct link to heading")
-------------------------------------------------------------------------------------

Let's use the `devnet wiz` command again to deploy `<chain2>`.

When deploying Avalanche L1 `<chain2>`, the two Teleporter contracts will not be deployed to C-Chain in Local Network as they have already been deployed when we deployed the first Avalanche L1.

```bash
avalanche node devnet wiz <devnetName> <chain2> --default-validator-params 

Adding subnet into existing devnet <devnetName>...
...

Deploying [chain2] to Cluster <devnetName>
...

Stopping AWM Relayer Service

Setting the nodes as subnet trackers
...

Setting up teleporter on subnet

Teleporter Messenger successfully deployed to chain2 (0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf)
Teleporter Registry successfully deployed to chain2 (0xb623C4495220C603D0A939D32478F55891a61750)
Teleporter Messenger has already been deployed to c-chain

Starting AWM Relayer Service

setting AWM Relayer on host i-0f1815c016b555fcc to relay subnet chain2
updating configuration file ~/.avalanche-cli/nodes/i-0f1815c016b555fcc/services/awm-relayer/awm-relayer-config.json

Devnet <devnetName> is now validating subnet chain2

Subnet <chain2> RPC URL: http://67.202.23.231:9650/ext/bc/7gKt6evRnkA2uVHRfmk9WrH3dYZH9gEVVxDAknwtjvtaV3XuQ/rpc

✓ Cluster information YAML file can be found at ~/.avalanche-cli/nodes/inventories/<devnetName>/clusterInfo.yaml at local host
```

Verify Teleporter Is Successfully Set Up[​](#verify-teleporter-is-successfully-set-up "Direct link to heading")
---------------------------------------------------------------------------------------------------------------

To verify that Teleporter is successfully, let's send a couple of cross messages:

```bash
avalanche teleporter msg C-Chain chain1 "Hello World" --cluster <devnetName>

Delivering message "this is a message" to source subnet "C-Chain" (2EfJg86if9Ka5Ag73JRfoqWz4EGuFwtemaNf4XiBBpUW4YngS6)
Waiting for message to be received at destination subnet subnet "chain1" (fqcM24LNb3kTV7KD1mAvUJXYy5XunwP8mrE44YuNwPjgZHY6p)
Message successfully Teleported!
```

```bash
avalanche teleporter msg chain2 chain1 "Hello World" --cluster <devnetName>

Delivering message "this is a message" to source subnet "chain2" (29WP91AG7MqPUFEW2YwtKnsnzVrRsqcWUpoaoSV1Q9DboXGf4q)
Waiting for message to be received at destination subnet subnet "chain1" (fqcM24LNb3kTV7KD1mAvUJXYy5XunwP8mrE44YuNwPjgZHY6p)
Message successfully Teleported!
```

You have Teleport-ed your first message in the Devnet!

Obtaining Information on Teleporter Deploys[​](#obtaining-information-on-teleporter-deploys "Direct link to heading")
---------------------------------------------------------------------------------------------------------------------

### Obtaining Avalanche L1 Information[​](#obtaining-avalanche-l1-information "Direct link to heading")

By executing `blockchain describe` on a Teleporter enabled Avalanche L1, the following relevant information can be found:

- Blockchain RPC URL
- Blockchain ID in cb58 format
- Blockchain ID in plain hex format
- Teleporter Messenger address
- Teleporter Registry address

Let's get the information for `<chain1>`:

```bash
avalanche blockchain describe <chain1>

 _____       _        _ _
|  __ \     | |      (_) |
| |  | | ___| |_ __ _ _| |___
| |  | |/ _ \ __/ _  | | / __|
| |__| |  __/ || (_| | | \__ \
|_____/ \___|\__\__,_|_|_|___/

+--------------------------------+----------------------------------------------------------------------------------------+
|           PARAMETER            |                               VALUE                                                    |
+--------------------------------+----------------------------------------------------------------------------------------+
| Blockchain Name                    | chain1                                                                                 |
+--------------------------------+----------------------------------------------------------------------------------------+
| ChainID                        | 1                                                                                      |
+--------------------------------+----------------------------------------------------------------------------------------+
| Token Name                     | TOKEN1 Token                                                                           |
+--------------------------------+----------------------------------------------------------------------------------------+
| Token Symbol                   | TOKEN1                                                                                 |
+--------------------------------+----------------------------------------------------------------------------------------+
| VM Version                     | v0.6.3                                                                                 |
+--------------------------------+----------------------------------------------------------------------------------------+
| VM ID                          | srEXiWaHjFEgKSgK2zBgnWQUVEy2MZA7UUqjqmBSS7MZYSCQ5                                      |
+--------------------------------+----------------------------------------------------------------------------------------+
| Cluster <devnetName> SubnetID  | giY8tswWgZmcAWzPkoNrmjjrykited7GJ9799SsFzTiq5a1ML                                      |
+--------------------------------+----------------------------------------------------------------------------------------+
| Cluster <devnetName> RPC URL   | http://67.202.23.231:9650/ext/bc/fqcM24LNb3kTV7KD1mAvUJXYy5XunwP8mrE44YuNwPjgZHY6p/rpc |
+--------------------------------+----------------------------------------------------------------------------------------+
| Cluster <devnetName>           | fqcM24LNb3kTV7KD1mAvUJXYy5XunwP8mrE44YuNwPjgZHY6p                                      |
| BlockchainID                   |                                                                                        |
+                                +----------------------------------------------------------------------------------------+
|                                | 0x582fc7bd55472606c260668213bf1b6d291df776c9edf7e042980a84cce7418a                     |
|                                |                                                                                        |
+--------------------------------+----------------------------------------------------------------------------------------+
| Cluster <devnetName> Teleporter| 0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf                                             |
| Messenger Address              |                                                                                        |
+--------------------------------+----------------------------------------------------------------------------------------+
| Cluster <devnetName> Teleporter| 0xb623C4495220C603D0A939D32478F55891a61750                                             |
| Registry Address               |                                                                                        |
+--------------------------------+----------------------------------------------------------------------------------------+
...
```

### Obtaining C-Chain Information[​](#obtaining-c-chain-information "Direct link to heading")

Similar information can be found for C-Chain by using `primary describe`:

```bash
avalanche primary describe --cluster <devnetName>

   _____       _____ _           _         _____
  / ____|     / ____| |         (_)       |  __ \
 | |   ______| |    | |__   __ _ _ _ __   | |__) |_ _ _ __ __ _ _ __ ___  ___
 | |  |______| |    | '_ \ / _  | | '_ \  |  ___/ _  | '__/ _  | '_   _ \/ __|
 | |____     | |____| | | | (_| | | | | | | |  | (_| | | | (_| | | | | | \__ \
  \_____|     \_____|_| |_|\__,_|_|_| |_| |_|   \__,_|_|  \__,_|_| |_| |_|___/

+------------------------------+--------------------------------------------------------------------+
|          PARAMETER           |                               VALUE                                |
+------------------------------+--------------------------------------------------------------------+
| RPC URL                      | http://67.202.23.231:9650/ext/bc/C/rpc                             |
+------------------------------+--------------------------------------------------------------------+
| EVM Chain ID                 | 43112                                                              |
+------------------------------+--------------------------------------------------------------------+
| TOKEN SYMBOL                 | AVAX                                                               |
+------------------------------+--------------------------------------------------------------------+
| Address                      | 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC                         |
+------------------------------+--------------------------------------------------------------------+
| Balance                      | 49999489.815751426                                                 |
+------------------------------+--------------------------------------------------------------------+
| Private Key                  | 56289e99c94b6912bfc12adc093c9b51124f0dc54ac7a766b2bc5ccf558d8027   |
+------------------------------+--------------------------------------------------------------------+
| BlockchainID                 | 2EfJg86if9Ka5Ag73JRfoqWz4EGuFwtemaNf4XiBBpUW4YngS6                 |
+                              +--------------------------------------------------------------------+
|                              | 0xa2b6b947cf2b9bf6df03c8caab08e38ab951d8b120b9c37265d9be01d86bb170 |
+------------------------------+--------------------------------------------------------------------+
| ICM Messenger Address        | 0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf                         |
+------------------------------+--------------------------------------------------------------------+
| ICM Registry Address         | 0x5DB9A7629912EBF95876228C24A848de0bfB43A9                         |
+------------------------------+--------------------------------------------------------------------+
```

Controlling Relayer Execution[​](#controlling-relayer-execution "Direct link to heading")
-----------------------------------------------------------------------------------------

CLI provides two commands to remotely control Relayer execution:

```bash
avalanche interchain relayer stop --cluster <devnetName>
✓ Remote AWM Relayer on i-0f1815c016b555fcc successfully stopped
```

```bash
avalanche interchain relayer start --cluster <devnetName>
✓ Remote AWM Relayer on i-0f1815c016b555fcc successfully started
```


# Teleporter on Local Network (/docs/tooling/avalanche-cli/cross-chain/teleporter-local-network)

---
title: Teleporter on Local Network
description: This how-to guide focuses on deploying Teleporter-enabled Avalanche L1s to a local Avalanche network.
---

After this tutorial, you would have created and deployed two Avalanche L1s to the local network and have enabled them to cross-communicate with each other and with the local C-Chain (through Teleporter and the underlying Warp technology.)

For more information on cross chain messaging through Teleporter and Warp, check:

- [Cross Chain References](/docs/cross-chain)

Note that currently only [Subnet-EVM](https://github.com/ava-labs/subnet-evm) and [Subnet-EVM-Based](/docs/virtual-machines/evm-customization/introduction) virtual machines support Teleporter.

## Prerequisites

- [Avalanche-CLI installed](/docs/tooling/get-avalanche-cli)

## Create Avalanche L1 Configurations

Let's create an Avalanche L1 called `<chain1>` with the latest Subnet-EVM version, a chain ID of 1, TOKEN1 as the token name, and with default Subnet-EVM parameters (more information regarding Avalanche L1 creation can be found [here](/docs/tooling/create-avalanche-l1#create-your-avalanche-l1-configuration)):

```bash
avalanche blockchain create <chain1> --evm --latest\
    --evm-chain-id 1 --evm-token TOKEN1 --evm-defaults

creating genesis for <blockchain chain1>
configuring airdrop to stored key "subnet_<chain1>_airdrop" with address 0x0EF8151A3e6ad1d4e17C8ED4128b20EB5edc58B1
loading stored key "cli-teleporter-deployer" for teleporter deploys
  (evm address, genesis balance) = (0xE932784f56774879e03F3624fbeC6261154ec711, 600000000000000000000)
using latest teleporter version (v1.0.0)
✓ Successfully created subnet configuration
```

Notice that by default, Teleporter is enabled and a stored key is created to fund Teleporter related operations (that is deploy Teleporter smart contracts, fund Teleporter Relayer).

To disable Teleporter in your Avalanche L1, use the flag `--teleporter=false` when creating the Avalanche L1.

To disable Relayer in your Avalanche L1, use the flag `--relayer=false` when creating the Avalanche L1.

Now let's create a second Avalanche L1 called `<chain2>`, with similar settings:

```bash
avalanche blockchain create <chain2> --evm --latest\
    --evm-chain-id 2 --evm-token TOKEN2 --evm-defaults

creating genesis for <blockchain chain2>
configuring airdrop to stored key "subnet_<chain2>_airdrop" with address 0x0EF815FFFF6ad1d4e17C8ED4128b20EB5edAABBB
loading stored key "cli-teleporter-deployer" for teleporter deploys
  (evm address, genesis balance) = (0xE932784f56774879e03F3624fbeC6261154ec711, 600000000000000000000)
using latest teleporter version (v1.0.0)
✓ Successfully created subnet configuration
```

Deploy the Avalanche L1s to Local Network[​](#deploy-the-avalanche-l1s-to-local-network "Direct link to heading")
-----------------------------------------------------------------------------------------------------

Let's deploy `<chain1>`:

```bash
avalanche blockchain deploy <chain1> --local

Deploying [<chain1>] to Local Network
Backend controller started, pid: 149427, output at: ~/.avalanche-cli/runs/server_20240229_165923/avalanche-cli-backend.log

Booting Network. Wait until healthy...
Node logs directory: ~/.avalanche-cli/runs/network_20240229_165923/node<i>/logs
Network ready to use.

Deploying Blockchain. Wait until network acknowledges...

Teleporter Messenger successfully deployed to c-chain (0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf)
Teleporter Registry successfully deployed to c-chain (0x17aB05351fC94a1a67Bf3f56DdbB941aE6c63E25)

Teleporter Messenger successfully deployed to <chain1> (0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf)
Teleporter Registry successfully deployed to <chain1> (0x9EDc4cB4E781413b1b82CC3A92a60131FC111F58)

Using latest awm-relayer version (v1.1.0)
Executing AWM-Relayer...

Blockchain ready to use. Local network node endpoints:
+-------+-----------+------------------------------------------------------------------------------------+--------------------------------------------+
| NODE  |     VM    |                                        URL                                         |                  ALIAS URL                 |
+-------+-----------+------------------------------------------------------------------------------------+--------------------------------------------+
| node1 | <chain1> | http://127.0.0.1:9650/ext/bc/MzN4AbtFzQ3eKqPhFaDpwCMJmagciWSCgghkZx6YeC6jRdvb6/rpc | http://127.0.0.1:9650/ext/bc/<chain1>/rpc |
+-------+-----------+------------------------------------------------------------------------------------+--------------------------------------------+
| node2 | <chain1> | http://127.0.0.1:9652/ext/bc/MzN4AbtFzQ3eKqPhFaDpwCMJmagciWSCgghkZx6YeC6jRdvb6/rpc | http://127.0.0.1:9652/ext/bc/<chain1>/rpc |
+-------+-----------+------------------------------------------------------------------------------------+--------------------------------------------+
| node3 | <chain1> | http://127.0.0.1:9654/ext/bc/MzN4AbtFzQ3eKqPhFaDpwCMJmagciWSCgghkZx6YeC6jRdvb6/rpc | http://127.0.0.1:9654/ext/bc/<chain1>/rpc |
+-------+-----------+------------------------------------------------------------------------------------+--------------------------------------------+
| node4 | <chain1> | http://127.0.0.1:9656/ext/bc/MzN4AbtFzQ3eKqPhFaDpwCMJmagciWSCgghkZx6YeC6jRdvb6/rpc | http://127.0.0.1:9656/ext/bc/<chain1>/rpc |
+-------+-----------+------------------------------------------------------------------------------------+--------------------------------------------+
| node5 | <chain1> | http://127.0.0.1:9658/ext/bc/MzN4AbtFzQ3eKqPhFaDpwCMJmagciWSCgghkZx6YeC6jRdvb6/rpc | http://127.0.0.1:9658/ext/bc/<chain1>/rpc |
+-------+-----------+------------------------------------------------------------------------------------+--------------------------------------------+

Browser Extension connection details (any node URL from above works):
RPC URL:          http://127.0.0.1:9650/ext/bc/MzN4AbtFzQ3eKqPhFaDpwCMJmagciWSCgghkZx6YeC6jRdvb6/rpc
Funded address:   0x0EF8151A3e6ad1d4e17C8ED4128b20EB5edc58B1 with 1000000 (10^18) - private key: 16289399c9466912ffffffdc093c9b51124f0dc54ac7a766b2bc5ccf558d8eee
Network name:     <chain1>
Chain ID:         1
Currency Symbol:  TOKEN1
```

Notice some details here:

- Two smart contracts are deployed to each Avalanche L1: Teleporter Messenger and Teleporter Registry
- Both Teleporter smart contracts are also deployed to `C-Chain` in the Local Network
- [AWM Teleporter Relayer](https://github.com/ava-labs/awm-relayer) is installed, configured and executed in background (A Relayer [listens](/docs/cross-chain/teleporter/overview#data-flow) for new messages being generated on a source Avalanche L1 and sends them to the destination Avalanche L1.)

CLI configures the Relayer to enable every Avalanche L1 to send messages to all other Avalanche L1s. If you add more Avalanche L1s, the Relayer will be automatically reconfigured.

When deploying Avalanche L1 `<chain2>`, the two Teleporter contracts will not be deployed to C-Chain in Local Network as they have already been deployed when we deployed the first Avalanche L1.

```bash
avalanche blockchain deploy <chain2> --local

Deploying [<chain2>] to Local Network

Deploying Blockchain. Wait until network acknowledges...

Teleporter Messenger has already been deployed to c-chain

Teleporter Messenger successfully deployed to <chain2> (0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf)
Teleporter Registry successfully deployed to <chain2> (0x9EDc4cB4E781413b1b82CC3A92a60131FC111F58)

Using latest awm-relayer version (v1.1.0)
Executing AWM-Relayer...

Blockchain ready to use. Local network node endpoints:
+-------+-----------+-------------------------------------------------------------------------------------+--------------------------------------------+
| NODE  |     VM    |                                         URL                                         |                  ALIAS URL                 |
+-------+-----------+-------------------------------------------------------------------------------------+--------------------------------------------+
| node1 | <chain2> | http://127.0.0.1:9650/ext/bc/2tVGwEQmeXtdnFURW1YSq5Yf4jbJPfTBfVcu68KWHdHe5e5gX5/rpc | http://127.0.0.1:9650/ext/bc/<chain2>/rpc |
+-------+-----------+-------------------------------------------------------------------------------------+--------------------------------------------+
| node1 | <chain1> | http://127.0.0.1:9650/ext/bc/MzN4AbtFzQ3eKqPhFaDpwCMJmagciWSCgghkZx6YeC6jRdvb6/rpc  | http://127.0.0.1:9650/ext/bc/<chain1>/rpc |
+-------+-----------+-------------------------------------------------------------------------------------+--------------------------------------------+
| node2 | <chain2> | http://127.0.0.1:9652/ext/bc/2tVGwEQmeXtdnFURW1YSq5Yf4jbJPfTBfVcu68KWHdHe5e5gX5/rpc | http://127.0.0.1:9652/ext/bc/<chain2>/rpc |
+-------+-----------+-------------------------------------------------------------------------------------+--------------------------------------------+
| node2 | <chain1> | http://127.0.0.1:9652/ext/bc/MzN4AbtFzQ3eKqPhFaDpwCMJmagciWSCgghkZx6YeC6jRdvb6/rpc  | http://127.0.0.1:9652/ext/bc/<chain1>/rpc |
+-------+-----------+-------------------------------------------------------------------------------------+--------------------------------------------+
| node3 | <chain2> | http://127.0.0.1:9654/ext/bc/2tVGwEQmeXtdnFURW1YSq5Yf4jbJPfTBfVcu68KWHdHe5e5gX5/rpc | http://127.0.0.1:9654/ext/bc/<chain2>/rpc |
+-------+-----------+-------------------------------------------------------------------------------------+--------------------------------------------+
| node3 | <chain1> | http://127.0.0.1:9654/ext/bc/MzN4AbtFzQ3eKqPhFaDpwCMJmagciWSCgghkZx6YeC6jRdvb6/rpc  | http://127.0.0.1:9654/ext/bc/<chain1>/rpc |
+-------+-----------+-------------------------------------------------------------------------------------+--------------------------------------------+
| node4 | <chain2> | http://127.0.0.1:9656/ext/bc/2tVGwEQmeXtdnFURW1YSq5Yf4jbJPfTBfVcu68KWHdHe5e5gX5/rpc | http://127.0.0.1:9656/ext/bc/<chain2>/rpc |
+-------+-----------+-------------------------------------------------------------------------------------+--------------------------------------------+
| node4 | <chain1> | http://127.0.0.1:9656/ext/bc/MzN4AbtFzQ3eKqPhFaDpwCMJmagciWSCgghkZx6YeC6jRdvb6/rpc  | http://127.0.0.1:9656/ext/bc/<chain1>/rpc |
+-------+-----------+-------------------------------------------------------------------------------------+--------------------------------------------+
| node5 | <chain1> | http://127.0.0.1:9658/ext/bc/MzN4AbtFzQ3eKqPhFaDpwCMJmagciWSCgghkZx6YeC6jRdvb6/rpc  | http://127.0.0.1:9658/ext/bc/<chain1>/rpc |
+-------+-----------+-------------------------------------------------------------------------------------+--------------------------------------------+
| node5 | <chain2> | http://127.0.0.1:9658/ext/bc/2tVGwEQmeXtdnFURW1YSq5Yf4jbJPfTBfVcu68KWHdHe5e5gX5/rpc | http://127.0.0.1:9658/ext/bc/<chain2>/rpc |
+-------+-----------+-------------------------------------------------------------------------------------+--------------------------------------------+

Browser Extension connection details (any node URL from above works):
RPC URL:          http://127.0.0.1:9650/ext/bc/2tVGwEQmeXtdnFURW1YSq5Yf4jbJPfTBfVcu68KWHdHe5e5gX5/rpc
Funded address:   0x0EF815FFFF6ad1d4e17C8ED4128b20EB5edAABBB with 1000000 (10^18) - private key: 56289e99c94b6912bfc12adc093c9b51124f0dc54ac7a766b2bc5ccf558d8027
Network name:     <chain2>
Chain ID:         2
Currency Symbol:  TOKEN2
```

Verify Teleporter Is Successfully Set Up[​](#verify-teleporter-is-successfully-set-up "Direct link to heading")
---------------------------------------------------------------------------------------------------------------

To verify that Teleporter is successfully, let's send a couple of cross messages (from C-Chain to chain1): 

```bash
avalanche teleporter sendMsg C-Chain chain1 "Hello World" --local
```

Results:
```bash
Delivering message "this is a message" to source subnet "C-Chain"
Waiting for message to be received at destination subnet subnet "chain1"
Message successfully Teleported!
```

To verify that Teleporter is successfully deployed, let's send a couple of cross-chain messages (from chain2 to chain1): 
```bash
avalanche teleporter sendMsg chain2 chain1 "Hello World" --local
```

Results:
```bash
Delivering message "this is a message" to source subnet "chain2"
Waiting for message to be received at destination subnet subnet "chain1"
Message successfully Teleported!
```

You have Teleport-ed your first message in the Local Network!

Relayer related logs can be found at `~/.avalanche-cli/runs/awm-relayer.log`, and Relayer configuration can be found at `~/.avalanche-cli/runs/awm-relayer-config.json`

Obtaining Information on Teleporter Deploys[​](#obtaining-information-on-teleporter-deploys "Direct link to heading")
---------------------------------------------------------------------------------------------------------------------

### Obtaining Avalanche L1 Information[​](#obtaining-avalanche-l1-information "Direct link to heading")

By executing `blockchain describe` on a Teleporter enabled Avalanche L1, the following relevant information can be found:

- Blockchain RPC URL
- Blockchain ID in cb58 format
- Blockchain ID in plain hex format
- Teleporter Messenger address
- Teleporter Registry address

Let's get the information for `<chain1>`:

```bash
avalanche blockchain describe <chain1>


 _____       _        _ _
|  __ \     | |      (_) |
| |  | | ___| |_ __ _ _| |___
| |  | |/ _ \ __/ _  | | / __|
| |__| |  __/ || (_| | | \__ \
|_____/ \___|\__\__,_|_|_|___/
+--------------------------------+-------------------------------------------------------------------------------------+
|           PARAMETER            |                               VALUE                                                 |
+--------------------------------+-------------------------------------------------------------------------------------+
| Blockchain Name                    | chain1                                                                              |
+--------------------------------+-------------------------------------------------------------------------------------+
| ChainID                        | 1                                                                                   |
+--------------------------------+-------------------------------------------------------------------------------------+
| Token Name                     | TOKEN1 Token                                                                        |
+--------------------------------+-------------------------------------------------------------------------------------+
| Token Symbol                   | TOKEN1                                                                              |
+--------------------------------+-------------------------------------------------------------------------------------+
| VM Version                     | v0.6.3                                                                              |
+--------------------------------+-------------------------------------------------------------------------------------+
| VM ID                          | srEXiWaHjFEgKSgK2zBgnWQUVEy2MZA7UUqjqmBSS7MZYSCQ5                                   |
+--------------------------------+-------------------------------------------------------------------------------------+
| Local Network SubnetID         | 2CZP2ndbQnZxTzGuZjPrJAm5b4s2K2Bcjh8NqWoymi8NZMLYQk                                  |
+--------------------------------+-------------------------------------------------------------------------------------+
| Local Network RPC URL          | http://127.0.0.1:9650/ext/bc/2cFWSgGkmRrmKtbPkB8yTpnq9ykK3Dc2qmxphwYtiGXCvnSwg8/rpc |
+--------------------------------+-------------------------------------------------------------------------------------+
| Local Network BlockchainID     | 2cFWSgGkmRrmKtbPkB8yTpnq9ykK3Dc2qmxphwYtiGXCvnSwg8                                  |
+                                +-------------------------------------------------------------------------------------+
|                                | 0xd3bc5f71e6946d17c488d320cd1f6f5337d9dce75b3fac5023433c4634b6e91e                  |
+--------------------------------+-------------------------------------------------------------------------------------+
| Local Network ICM              | 0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf                                          |
| Messenger Address              |                                                                                     |
+--------------------------------+-------------------------------------------------------------------------------------+
| Local Network ICM              | 0xbD9e8eC38E43d34CAB4194881B9BF39d639D7Bd3                                          |
| Registry Address               |                                                                                     |
+--------------------------------+-------------------------------------------------------------------------------------+

...
```

### Obtaining C-Chain Information[​](#obtaining-c-chain-information "Direct link to heading")

Similar information can be found for C-Chain by using `primary describe`:

```bash
avalanche primary describe --local

   _____       _____ _           _         _____
  / ____|     / ____| |         (_)       |  __ \
 | |   ______| |    | |__   __ _ _ _ __   | |__) |_ _ _ __ __ _ _ __ ___  ___
 | |  |______| |    | '_ \ / _  | | '_ \  |  ___/ _  | '__/ _  | '_   _ \/ __|
 | |____     | |____| | | | (_| | | | | | | |  | (_| | | | (_| | | | | | \__ \
  \_____|     \_____|_| |_|\__,_|_|_| |_| |_|   \__,_|_|  \__,_|_| |_| |_|___/

+------------------------------+--------------------------------------------------------------------+
|          PARAMETER           |                               VALUE                                |
+------------------------------+--------------------------------------------------------------------+
| RPC URL                      | http://127.0.0.1:9650/ext/bc/C/rpc                                 |
+------------------------------+--------------------------------------------------------------------+
| EVM Chain ID                 | 43112                                                              |
+------------------------------+--------------------------------------------------------------------+
| TOKEN SYMBOL                 | AVAX                                                               |
+------------------------------+--------------------------------------------------------------------+
| Address                      | 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC                         |
+------------------------------+--------------------------------------------------------------------+
| Balance                      | 49999489.829989485                                                 |
+------------------------------+--------------------------------------------------------------------+
| Private Key                  | 56289e99c94b6912bfc12adc093c9b51124f0dc54ac7a766b2bc5ccf558d8027   |
+------------------------------+--------------------------------------------------------------------+
| BlockchainID                 | 2JeJDKL9Bvn1vLuuPL1DpUccBCVUh7iRnkv3a5pV9kJW5HbuQz                 |
+                              +--------------------------------------------------------------------+
|                              | 0xabc1bd35cb7313c8a2b62980172e6d7ef42aaa532c870499a148858b0b6a34fd |
+------------------------------+--------------------------------------------------------------------+
| ICM Messenger Address        | 0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf                         |
+------------------------------+--------------------------------------------------------------------+
| ICM Registry Address         | 0x17aB05351fC94a1a67Bf3f56DdbB941aE6c63E25                         |
+------------------------------+--------------------------------------------------------------------+
```

Controlling Relayer Execution[​](#controlling-relayer-execution "Direct link to heading")
-----------------------------------------------------------------------------------------

Besides having the option to not use a Relayer at Avalanche L1 creation time, the Relayer can be stopped and restarted on used request.

To stop the Relayer:

```bash
avalanche interchain relayer stop --local

✓ Local AWM Relayer successfully stopped
```

To start it again:

```bash
avalanche interchain relayer start --local

using latest awm-relayer version (v1.1.0)
Executing AWM-Relayer...
✓ Local AWM Relayer successfully started
Logs can be found at ~/.avalanche-cli/runs/awm-relayer.log
```


# Teleporter Token Bridge (/docs/tooling/avalanche-cli/cross-chain/teleporter-token-bridge)

---
title: Teleporter Token Bridge
description: Deploy an example Teleporter Token Bridge on the local network.
---

Teleporter Token Bridge enables users to transfer tokens between Avalanche L1s. The bridge is a set of 
smart contracts that are deployed across multiple Avalanche L1s, and leverages Teleporter for cross-chain 
communication.

For more information on Teleporter Token Bridge, check:

- [Teleporter Token Bridge README](https://github.com/ava-labs/teleporter-token-bridge)

## How to Deploy Teleporter Token Bridge on a Local Network

This how-to guide focuses on deploying Teleporter Token Bridge on a local Avalanche network.

After this tutorial, you would have learned how to transfer an ERC-20 token between two 
Teleporter-enabled Avalanche L1s and between C-Chain and a Teleporter-enabled Avalanche L1.

## Prerequisites

For our example, you will first need to create and deploy a Teleporter-enabled Avalanche L1 in Local
Network. We will name our Avalanche L1 `testblockchain`.

- To create a Teleporter-enabled Avalanche L1 configuration, [visit here](/docs/tooling/cross-chain/teleporter-local-network#create-subnet-configurations)
- To deploy a Teleporter-enabled Avalanche L1, [visit here](/docs/tooling/cross-chain/teleporter-local-network#deploy-the-subnets-to-local-network)

## Deploy ERC-20 Token in C-Chain

First, let's create an ERC-20 Token and deploy it to C-Chain. For our example, it will be called 
TOK. 

Sample script to deploy the ERC-20 Token can be found [here](https://github.com/ava-labs/avalanche-cli/blob/main/cmd/contractcmd/deploy_erc20.go). 


To deploy the ERC-20 Token to C-Chain, we will call: 

```bash
avalanche contract deploy erc20
```

When the command is run, our EWOQ address `0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC` would have 
received 100000 TOK tokens in C-Chain. 

Note that `0x5DB9A7629912EBF95876228C24A848de0bfB43A9` is our ERC-20 Token address, which we will 
use in our next command.

## Deploy Teleporter Token Bridge 

Next, we will now deploy Teleporter Token Bridge to our Local Network, where we will deploy
the Home Contract to C-Chain and the Remote Contract to our Avalanche L1.

```bash
avalanche teleporter bridge deploy 
✔ Local Network
✔ C-Chain
✔ Deploy a new Home for the token
✔ An ERC-20 token
Enter the address of the ERC-20 Token: 0x5DB9A7629912EBF95876228C24A848de0bfB43A9
✔ Subnet testblockchain
Downloading Bridge Contracts
Compiling Bridge

Home Deployed to http://127.0.0.1:9650/ext/bc/C/rpc
Home Address: 0x4Ac1d98D9cEF99EC6546dEd4Bd550b0b287aaD6D

Remote Deployed to http://127.0.0.1:9650/ext/bc/2TnSWd7odhkDWKYFDZHqU7CvtY8G6m46gWxUnhJRNYu4bznrrc/rpc
Remote Address: 0x7DD1190e6F6CE8eE13C08F007FdAEE2f881B45D0
```

Before we transfer our ERC-20 token from C-Chain to our Avalanche L1, we will first call `avalanche key
list` command to check our initial balances in C-Chain and Avalanche L1. 

We will inquire the balances of our ERC-20 Token TOK both in C-Chain and our Avalanche L1, which has the 
address of `0x5DB9A7629912EBF95876228C24A848de0bfB43A9` in the C-Chain and address of
`0x7DD1190e6F6CE8eE13C08F007FdAEE2f881B45D0` in our Avalanche L1 `testblockchain`.

```bash
`avalanche key list --local --keys ewoq,blockchain_airdrop --subnets c,testblockchain --tokens 0x5DB9A7629912EBF95876228C24A848de0bfB43A9,0x7DD1190e6F6CE8eE13C08F007FdAEE2f881B45D0`
+--------+--------------------+------------+--------------------------------------------+---------------+-----------------+---------------+
|  KIND  |        NAME        | SUBNET     |                  ADDRESS                   |     TOKEN     |     BALANCE     |    NETWORK    |
+--------+--------------------+---------+--------------------------------------------+---------------+-----------------+---------------+
| stored | ewoq               | testblockchain | 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC | TOK (0x7DD1.) |               0 | Local Network |
+        +                    +---------+--------------------------------------------+---------------+-----------------+---------------+
|        |                    | C-Chain    | 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC | TOK (0x5DB9.) | 100000.000000000| Local Network |
+        +--------------------+---------+--------------------------------------------+---------------+-----------------+---------------+
|        | blockchain  | testblockchain | 0x5a4601D594Aa3848cA5EE0770b7883d3DBC666f6 | TOK (0x7DD1.) |               0 | Local Network |
+        + _airdrop           +---------+--------------------------------------------+---------------+-----------------+---------------+
|        |                    | C-Chain    | 0x5a4601D594Aa3848cA5EE0770b7883d3DBC666f6 | TOK (0x5DB9.) |               0 | Local Network |
+--------+--------------------+------------+--------------------------------------------+---------------+-----------------+---------------+
```

## Transfer the Token from C-Chain to Our Avalanche L1

Now we will transfer 100 TOK tokens from our `ewoq` address in C-Chain to blockchain_airdrop
address in our Avalanche L1 `testblockchain`. Note that we will be using the Home contract address `0x4Ac1d98D9cEF99EC6546dEd4Bd550b0b287aaD6D`
and Remote contract address `0x7DD1190e6F6CE8eE13C08F007FdAEE2f881B45D0`.

```bash
avalanche key transfer
✔ Local Network
✔ C-Chain
✔ Subnet testblockchain
Enter the address of the Bridge on c-chain: 0x4Ac1d98D9cEF99EC6546dEd4Bd550b0b287aaD6D
Enter the address of the Bridge on testblockchain: 0x7DD1190e6F6CE8eE13C08F007FdAEE2f881B45D0
✔ ewoq
✔ Key
✔ blockchain_airdrop
Amount to send (TOKEN units): 100
```

## Verify That Transfer Is Successful

We will call `avalanche key list` command again to verify that the transfer is successful.

`blockchain_airdrop` should now have 100 TOK tokens in our Avalanche L1 `testblockchain` and our EWOQ
account now has 99900 TOK tokens in C-Chain.

```bash
avalanche key list --local --keys ewoq,blockchain_airdrop --subnets c,testblockchain --tokens 0x5DB9A7629912EBF95876228C24A848de0bfB43A9,0x7DD1190e6F6CE8eE13C08F007FdAEE2f881B45D0
+--------+--------------------+------------+--------------------------------------------+---------------+-----------------+---------------+
|  KIND  |        NAME        | SUBNET     |                  ADDRESS                   |     TOKEN     |     BALANCE     |    NETWORK    |
+--------+--------------------+---------+--------------------------------------------+---------------+-----------------+---------------+
| stored | ewoq               | testblockchain | 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC | TOK (0x7DD1.) |               0 | Local Network |
+        +                    +---------+--------------------------------------------+---------------+-----------------+---------------+
|        |                    | C-Chain    | 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC | TOK (0x5DB9.) | 99900.000000000 | Local Network |
+        +--------------------+---------+--------------------------------------------+---------------+-----------------+---------------+
|        | blockchain  | testblockchain | 0x5a4601D594Aa3848cA5EE0770b7883d3DBC666f6 | TOK (0x7DD1.) |   100.000000000 | Local Network |
+        + _airdrop           +---------+--------------------------------------------+---------------+-----------------+---------------+
|        |                    | C-Chain    | 0x5a4601D594Aa3848cA5EE0770b7883d3DBC666f6 | TOK (0x5DB9.) |               0 | Local Network |
+--------+--------------------+------------+--------------------------------------------+---------------+-----------------+---------------+
```

And that's it! You have now successfully completed your first transfer from C-Chain to Avalanche L1 
using Teleporter Token Bridge!


# Import an Avalanche L1 (/docs/tooling/avalanche-cli/guides/import-avalanche-l1)

---
title: Import an Avalanche L1
description: Learn how to import an Avalanche-l1 into Avalanche-CLI.
---
Context[​](#context "Direct link to heading")
---------------------------------------------

In previous instances, Avalanche L1s might have been manually created through transaction issuance to node APIs, whether it was done using a local node or public API nodes. However, the current focus is on integrating Avalanche-CLI.

To achieve this integration, this guide demonstrates the process of importing an Avalanche L1 to the Avalanche-CLI to enable better management of the Avalanche L1's configuration. This how-to uses the BEAM Avalanche L1 deployed on Fuji Testnet as the example Avalanche L1.

Requirements[​](#requirements "Direct link to heading")
-------------------------------------------------------

For the import to work properly, you need:

- The Avalanche L1's genesis file, stored on disk
    
- The Avalanche L1's SubnetID
    

Import the Avalanche L1[​](#import-the-avalanche-l1 "Direct link to heading")
-----------------------------------------------------------------

For these use cases, Avalanche-CLI now supports the `import public` command.

Start the import by issuing

```
avalanche blockchain import public
```

The tool prompts for the network from which to import. The invariant assumption here is that the network is a public network, either the Fuji testnet or Mainnet. In other words, importing from a local network isn't supported.

```
Use the arrow keys to navigate: ↓ ↑ → ←
? Choose a network to import from:
  ▸ Fuji
    Mainnet
```

As stated earlier, this is from Fuji, so select it. As a next step, Avalanche-CLI asks for the path of the genesis file on disk:

```
✗ Provide the path to the genesis file: /tmp/subnet_evm.genesis.json
```

The wizard checks if the file at the provided path exists, refer to the checkmark at the beginning of the line:

```
✔ Provide the path to the genesis file: /tmp/subnetevm_genesis.json
```

Subsequently, the wizard asks if nodes have already been deployed for this Avalanche L1.

```
Use the arrow keys to navigate: ↓ ↑ → ←
? Have nodes already been deployed to this subnet?:
    Yes
  ▸ No
```

### Nodes are Already Validating This Avalanche L1[​](#nodes-are-already-validating-this-avalanche-l1 "Direct link to heading")

If nodes already have been deployed, the wizard attempts to query such a node for detailed data like the VM version. This allows the tool to skip querying GitHub (or wherever the VM's repository is hosted) for the VM's version, but rather we'll get the exact version which is actually running on the node.

For this to work, a node API URL is requested from the user, which is used for the query. This requires that the node's API IP and port are accessible from the machine running Avalanche-CLI, or the node is obviously not reachable, and thus the query times out and fails, and the tool exits. The node should also be validating the given Avalanche L1 for the import to be meaningful, otherwise, the import fails with missing information.

If the query succeeded, the wizard jumps to prompt for the Avalanche L1 ID (SubnetID).

```
Please provide an API URL of such a node so we can query its VM version (e.g. http://111.22.33.44:5555): http://154.42.240.119:9650
What is the ID of the subnet?: ie1wUBR2bQDPkGCRf2CBVzmP55eSiyJsFYqeGXnTYt2r33aKW
```

The rest of the wizard is identical to the next section, except that there is no prompt for the VM version anymore.

### Nodes Aren't Yet Validating this Avalanche L1, the Nodes API URL are Unknown, or Inaccessible (Firewalls)[​](#nodes-arent-yet-validating-this-avalanche-l1-the-nodes-api-url-are-unknown-or-inaccessible-firewalls "Direct link to heading")

If you don't have a node's API URL at hand, or it's not reachable from the machine running Avalanche-CLI, or maybe no nodes have even been deployed yet because only the `CreateSubnet` transaction has been issued, for example, you can query the public APIs.

You can't know for sure what Avalanche L1 VM versions the validators are running though, therefore the tool has to prompt later. So, select `No` when the tool asks for deployed nodes:

Thus, at this point the wizard requests the Avalanche L1's ID, without which it can't know what to import. Remember the ID is different on different networks.

From the [Testnet Avalanche L1 Explorer](https://subnets-test.avax.network/beam) you can see that BEAM's Avalanche L1 ID (SubnetID) is `ie1wUBR2bQDPkGCRf2CBVzmP55eSiyJsFYqeGXnTYt2r33aKW`:

```
✔ What is the ID of the subnet?: ie1wUBR2bQDPkGCRf2CBVzmP55eSiyJsFYqeGXnTYt2r33aKW
```

Notice the checkmark at line start, it signals that there is ID format validation.

If you hit `enter` now, the tool queries the public APIs for the given network, and if successful, it prints some information about the Avalanche L1, and proceeds to ask about the Avalanche L1's type:

```
Getting information from the Fuji network...
Retrieved information. BlockchainID: y97omoP2cSyEVfdSztQHXD9EnfnVP9YKjZwAxhUfGbLAPYT9t, Name: BEAM, VMID: kLPs8zGsTVZ28DhP1VefPCFbCgS7o5bDNez8JUxPVw9E6Ubbz
Use the arrow keys to navigate: ↓ ↑ → ←
? What's this VM's type?:
  ▸ Subnet-EVM
    Custom
```

Avalanche-CLI needs to know the VM type, to hit its repository and select what VM versions are available. This works automatically for Ava Labs VMs (like Subnet-EVM).

Custom VMs aren't supported yet at this point, but are next on the agenda.

As the import is for BEAM, and you know that it's a Subnet-EVM type, select that.

The tool then queries the (GitHub) repository for available releases, and prompts the user to pick the version she wants to use:

```
✔ Subnet-EVM
Use the arrow keys to navigate: ↓ ↑ → ←
? Pick the version for this VM:
  ▸ v0.4.5
    v0.4.5-rc.1
    v0.4.4
    v0.4.4-rc.0
↓   v0.4.3
```

There is only so much the tool can help here, the Avalanche L1 manager/administrator should know what they want to use Avalanche-CLI for, how, and why they're importing the Avalanche L1.

It's crucial to understand that the correct versions are only known to the user. The latest might be usually fine, but the tool can't make assumptions about it easily. This is why it's indispensable that the wizard prompts the user, and the tool requires her to choose.

If you selected to query an actual Avalanche L1 validator, not the public APIs, in the preceding step. In such a scenario, the tool skips this picking.

```
✔ v0.4.5
Subnet BEAM imported successfully
```

The choice finalizes the wizard, which hopefully signals that the import succeeded. If something went wrong, the error messages provide cause information. This means you can now use Avalanche-CLI to handle the imported Avalanche L1 in the accustomed way. For example, you could deploy the BEAM Avalanche L1 locally.

For a complete description of options, flags, and the command, visit the [command reference](/docs/tooling/cli-commands#avalanche-l1-import).

# Run with Docker (/docs/tooling/avalanche-cli/guides/run-with-docker)

---
title: Run with Docker
description: Instructions for running Avalanche-CLI in a Docker container.
---

To run Avalanche-CLI in a docker container, you need to enable ipv6.

Edit `/etc/docker/daemon.json`. Add this snippet then restart the docker service.

```json
{
  "ipv6": true,
  "fixed-cidr-v6": "fd00::/80"
}
```


# Add Validator (/docs/tooling/avalanche-cli/maintain/add-validator-l1)

---
title: Add Validator
description:  Learn how to add a validator to an Avalanche L1.
---


### Add a Validator to an Avalanche L1

```bash
avalanche blockchain addValidator <blockchainName>
```

#### Choose Network
Choose the network where the operation will be

```bash
? Choose a network for the operation: 
  ▸ Local Network
    Devnet
    Fuji Testnet
    Mainnet
```

#### Choose P-Chain Fee Payer

Choose the key that will be used to pay for the transaction fees on the P-Chain.

```bash
? Which key should be used to pay for transaction fees on P-Chain?: 
  ▸ Use stored key
    Use ledger
```

#### Enter Node ID

Enter the NodeID of the node you want to add as a blockchain validator.

```bash
✗ What is the NodeID of the node you want to add as a blockchain validator?:  
```

<Callout>
You can find the NodeID in the node's configuration file or the console when first started with avalanchego.
An example of a NodeID is `NodeID-7Xhw2mDxuDS44j42TCB6U5579esbSt3Lg`
</Callout>

#### Enter the BLS Public Key

Enter the public key of the node's BLS

```bash
Next, we need the public key and proof of possession of the node's BLS
Check https://build.avax.network/docs/api-reference/info-api#infogetnodeid for instructions on calling info.getNodeID API
✗ What is the node's BLS public key?:
```

<Callout>
You can find the BLS public key in the node's configuration file or the console when first started with avalanchego.
</Callout>

#### Enter BLS Proof of Possession

Enter the proof of possession of the node's BLS

```bash
✗ What is the node's BLS proof of possession?:
```

<Callout>
You can find the BLS proof of possession in the node's configuration file or the console when first started with avalanchego.
</Callout>

#### Enter AVAX Balance

This balance will be used to pay the P-Chain continuous staking fee.

```bash
✗ What balance would you like to assign to the validator (in AVAX)?: 
```

#### Enter Leftover AVAX Address

This address will receive any leftover AVAX when the node is removed from the validator set.

```bash
? Which key would you like to set as change owner for leftover AVAX if the node is removed from validator set?: 
 ▸ Get address from an existing stored key (created from avalanche key create or avalanche key import)
    Custom
```

#### Enter Disable Validator Address

This address will be able to disable the validator using P-Chain transactions.

```bash
 Which address do you want to be able to disable the validator using P-Chain transactions?: 
  ▸ Get address from an existing stored key (created from avalanche key create or avalanche key import)
    Custom
```

### Proof of Stake specific parameters

If your network was created with Proof of Stake validator manager, you will be asked for the following additional parameters. You can also pass these parameters as flags to the command.

```bash
--delegation-fee uint16                delegation fee (in bips)
--stake-amount uint                    amount of native tokens to stake
--staking-period duration              how long this validator will be staking
```


# Delete an Avalanche L1 (/docs/tooling/avalanche-cli/maintain/delete-avalanche-l1)

---
title: Delete an Avalanche L1
description:  Learn how to delete an Avalanche L1.
---

Deleting an Avalanche L1 Configuration[​](#deleting-a-avalanche-l1-configuration "Direct link to heading")
---------------------------------------------------------------------------------------------

To delete a created Avalanche L1 configuration, run:

```bash
avalanche blockchain delete <blockchainName>
```

Deleting a Deployed Avalanche L1[​](#deleting-a-deployed-avalanche-l1 "Direct link to heading")
-----------------------------------------------------------------------------------

You can't delete Avalanche L1s deployed to Mainnet or the Fuji Testnet.

However, you may delete Avalanche L1s deployed to a local network by cleaning the network state with below command:

```bash
avalanche network clean
```



# Remove Validator (/docs/tooling/avalanche-cli/maintain/remove-validator-l1)

---
title: Remove Validator
description:  Learn how to remove a validator from an Avalanche L1.
---

### Remove a Validator from an Avalanche L1

```bash
avalanche blockchain removeValidator <blockchainName>
```

#### Choose the Network
Choose the network where the validator is registered.
```bash
? Choose a network for the operation: 
  ▸ Local Network
    Devnet
    Fuji Testnet
    Mainnet
```

#### Choose P-Chain fee payer
Choose the key to pay for the transaction fees on the P-Chain.
```bash
? Which key should be used to pay for transaction fees on P-Chain?: 
  ▸ Use stored key
    Use ledger
```

#### Enter Node-ID of the Validator to Remove
Enter the Node-ID of the validator you want to remove.
```bash
✗ What is the NodeID of the node you want to remove as a blockchain validator?: 
```
<Callout>
You can find the NodeID in the node's configuration file or the console when first started with avalanchego.
An example of a NodeID is `NodeID-7Xhw2mDxuDS44j42TCB6U5579esbSt3Lg`
</Callout>

#### Confirm the removal
```bash
Validator manager owner 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC pays for the initialization of the validator's removal (Blockchain gas token)
RPC Endpoint: http://127.0.0.1:9652/ext/bc/2qmU6w47Mp7D7fGhbRuZm6Z1Nn6FZXZAxKpaeTMFiRQW9CBErh/rpc
Forcing removal of NodeID-7cQrriPWGXa5yuJGZUgsxxwH9j4T8pPkY as it is a PoS bootstrap validator
Using validationID: 228zzCgDmAmuaJDGnFkFgnVqbbJPRF7qF1Xpd3dhtqGDhMjJK2 for nodeID: NodeID-7cQrriPWGXa5yuJGZUgsxxwH9j4T8pPkY
ValidationID: 228zzCgDmAmuaJDGnFkFgnVqbbJPRF7qF1Xpd3dhtqGDhMjJK2
SetSubnetValidatorWeightTX fee: 0.000078836 AVAX
SetSubnetValidatorWeightTx ID: 2FUimPZ37DscPJiQDLrtKtumER3LNr48MJi6VR2jGXkYEKpCaq
✓ Validator successfully removed from the Subnet
```


### Proof of Authority Networks
<Callout>
If the network is a Proof of Authority network, the validator must be removed from the network by the Validator Manager owner.
</Callout>

### Proof of Stake Networks
<Callout>
If the network is a Proof of Stake network, the validator must be removed by the initial staker. Rewards will be distributed to the validator after the removal.
It is important to note that the initial PoS Validator set are treated as bootstrap validators and are not elgible for rewards.
</Callout>

# Troubleshooting (/docs/tooling/avalanche-cli/maintain/troubleshooting)

---
title: Troubleshooting
description: If you run into trouble deploying your Avalanche L1, use this document for tips to resolve common issues.
---

Deployment Times Out[​](#deployment-times-out "Direct link to heading")
-----------------------------------------------------------------------

During a local deployment, your network may fail to start. Your error may look something like this:

```bash
[~]$ avalanche blockchain deploy myblockchain

✔ Local Network
Deploying [myblockchain] to Local Network
Backend controller started, pid: 26388, output at: /Users/user/.avalanche-cli/runs/server_20221231_111605/avalanche-cli-backend
VMs ready.
Starting network...
..................................................................................
..................................................................................
......Error: failed to query network health: rpc error: code = DeadlineExceeded desc = context deadline exceeded
```

Avalanche-CLI only supports running one local Avalanche network at a time. If other instances of AvalancheGo are running concurrently, your Avalanche-CLI network fails to start.

To test for this error, start by shutting down any Avalanche nodes started by Avalanche-CLI.

```bash
avalanche network clean --hard
```

Next, look for any lingering AvalancheGo processes with:

```bash
ps aux | grep avalanchego
```

If any processes are running, you need to stop them before you can launch your VM with Avalanche-CLI.

<Callout type="warn">
If you're running a validator node on the same box you're using Avalanche-CLI, **don't** end any of these lingering AvalancheGo processes. This may shut down your validator and could affect your validation uptime.
</Callout>


Incompatible RPC Version for Custom VM[​](#incompatible-rpc-version-for-custom-vm "Direct link to heading")
-----------------------------------------------------------------------------------------------------------

If you're locally deploying a custom VM, you may run into this error message.

```bash
[~]$ avalanche blockchain deploy myblockchain

✔ Local Network
Deploying [myblockchain] to Local Network
Backend controller started, pid: 26388, output at: /Users/user/.avalanche-cli/runs/server_20221231_111605/avalanche-cli-backend
VMs ready.
Starting network...
.........
Blockchain has been deployed. Wait until network acknowledges...
..................................................................................
..................................................................................
......Error: failed to query network health: rpc error: code = DeadlineExceeded desc = context deadline exceeded
```

This error has many possible causes, but a common cause is usually due to **an RPC protocol version mismatch.**

AvalancheGo communicates with custom VMs over RPC using [gRPC](https://grpc.io/). gRPC defines a protocol specification shared by both AvalancheGo and the VM. **Both components must be running the same RPC version for VM deployment to work.**

Your custom VM's RPC version is set by the version of AvalancheGo that you import. By default, Avalanche-CLI creates local Avalalanche networks that run the latest AvalancheGo release.

### Example[​](#example "Direct link to heading")

Here's an example with real numbers from the AvalancheGo compatibility page:

- If the latest AvalancheGo release is version v1.10.11, then Avalanche-CLI deploys a network with RPC version 28.
- For your deploy to be successful, your VM must also have RPC version 28. Because only AvalancheGo versions v1.10.9, v1.10.10 and v1.10.11 supports RPC version 28, your VM **must** import one of those versions.

### Solution[​](#solution "Direct link to heading")

Error: `RPCChainVM protocol version mismatch between AvalancheGo and Virtual Machine plugin`

This error occurs when the RPCChainVM protocol version used by VMs like Subnet-EVM are incompatible with the protocol version of AvalancheGo.

If your VM has an RPC version mismatch, you have two options:

1.  Update the version of AvalancheGo you use in your VM. This is the correct long-term approach.
2.  Use Avalanche-CLI to deploy an older version of AvalancheGo by using the `--avalanchego-version` flag. Both the [`blockchain deploy`](/docs/tooling/cli-commands#deploy) and [`network start`](/docs/tooling/cli-commands#start) commands support setting the AvalancheGo version explicitly.

Although it's very important to keep your version of AvalancheGo up-to-date, this workaround helps you avoid broken builds in the short term.

<Callout type="warn">
You must upgrade to the latest AvalancheGo version when deploying publicly to Fuji Testnet or Avalanche Mainnet.
</Callout>


### More Information[​](#more-information "Direct link to heading")

Similar version matching is required in different tools on the ecosystem. Here is a compatibility table showing which RPCChainVM Version implements the more recent releases of AvalancheGo, Subnet-EVM, Precompile-EVM and HyperSDK.

|RPCChainVM|AvalancheGo       |Subnet-EVM     |Precompile-EVM |HyperSDK        |
|----------|------------------|---------------|---------------|----------------|
|26        |v1.10.1-v1.10.4   |v0.5.1-v0.5.2  |v0.1.0-v0.1.1  |v0.0.6-v0.0.9   |
|27        |v1.10.5-v1.10.8   |v0.5.3         |v0.1.2         |v0.0.10-v0.0.12 |
|28        |v1.10.9-v1.10.12  |v0.5.4-v0.5.6  |v0.1.3-v0.1.4  |v0.0.13-v0.0.15 |
|30        |v1.10.15-v1.10.17 |v0.5.9-v0.5.10 |v0.1.6-v0.1.7  |-               |
|29        |v1.10.13-v1.10.14 |v0.5.7-v0.5.8  |v0.1.5         |-               |
|31        |v1.10.18- v1.10.19|v0.5.11        |v0.1.8         |v0.0.16 (latest)|
|33        |v1.11.0           |v0.6.0-v0.6.1  |v0.2.0         |-               |
|34        |v1.11.1- v1.11.2  |v0.6.2         |-              |-               |
|35        |v1.11.3 (latest)  |v0.6.3 (latest)|v0.2.1 (latest)|-               |


You can view the full RPC compatibility broken down by release version for each tool here:

[AvalancheGo](https://github.com/ava-labs/avalanchego/blob/master/version/compatibility.json).

[Subnet-EVM](https://github.com/ava-labs/subnet-evm/blob/master/compatibility.json).

[Precompile-EVM](https://github.com/ava-labs/precompile-evm/blob/main/compatibility.json).

<Callout title="Note">
Updates to AvalancheGo's RPC version are **not** tied to its semantic version scheme. Minor AvalancheGo version bumps may include a breaking RPC version bump.
</Callout>

Fix for MacBook Air M1/M2: ‘Bad CPU type in executable' Error[​](#fix-for-macbook-air-m1m2-bad-cpu-type-in-executable-error "Direct link to heading")
-----------------------------------------------------------------------------------------------------------------------------------------------------

When running `avalanche blockchain deploy` via the Avalanche-CLI, the terminal may throw an error that contains the following:

```bash
zsh: bad CPU type in executable:
/Users/user.name/Downloads/build/avalanchego
```

This is because some Macs lack support for x86 binaries. Running the following command should fix this issue:

```bash
/usr/sbin/softwareupdate --install-rosetta
```


# View Avalanche L1s (/docs/tooling/avalanche-cli/maintain/view-avalanche-l1s)

---
title: View Avalanche L1s
description: CLI commands for viewing avalanche-l1s.
---

## List Avalanche L1 Configurations

You can list the Avalanche L1s you've created with: `avalanche blockchain list`

Example:

```bash
> avalanche blockchain list
+--------------+--------------+----------+---------------------------------------------------+------------+------------+-----------+
|    SUBNET    |    CHAIN     | CHAINID  |                       VMID                        |    TYPE    | VM VERSION | FROM REPO |
+--------------+--------------+----------+---------------------------------------------------+------------+------------+-----------+
| myblockchain | myblockchain |      111 | qDNV9vtxZYYNqm7TN1mYBuaaknLdefDbFK8bFmMLTJQJKaWjV | Subnet-EVM | v0.7.0     | false     |
+--------------+--------------+----------+---------------------------------------------------+------------+------------+-----------+
```

To see detailed information about your deployed Avalanche L1s, add the `--deployed` flag:

```bash
> avalanche blockchain list --deployed
+--------------+--------------+---------------------------------------------------+---------------+----------------+---------+
|    SUBNET    |    CHAIN     |                       VM ID                       | LOCAL NETWORK | FUJI (TESTNET) | MAINNET |
+--------------+--------------+---------------------------------------------------+---------------+----------------+---------+
| myblockchain | myblockchain | qDNV9vtxZYYNqm7TN1mYBuaaknLdefDbFK8bFmMLTJQJKaWjV | Yes           | No             | No      |
+--------------+--------------+---------------------------------------------------+---------------+----------------+---------+

```bash

## Describe Avalanche L1 Configurations

To see the details of a specific configuration, run: `avalanche blockchain describe <blockchainName>`

Example:

```bash
> avalanche blockchain describe myblockchain

+---------------------------------------------------------------------------------------------------------------------------------+
|                                                           MYBLOCKCHAIN                                                          |
+---------------+-----------------------------------------------------------------------------------------------------------------+
| Name          | myblockchain                                                                                                    |
+---------------+-----------------------------------------------------------------------------------------------------------------+
| VM ID         | qDNV9vtxZYYNqm7TN1mYBuaaknLdefDbFK8bFmMLTJQJKaWjV                                                               |
+---------------+-----------------------------------------------------------------------------------------------------------------+
| VM Version    | v0.7.0                                                                                                          |
+---------------+-----------------------------------------------------------------------------------------------------------------+
| Validation    | Proof Of Authority                                                                                              |
+---------------+--------------------------+--------------------------------------------------------------------------------------+
| Local Network | ChainID                  | 12345                                                                                |
|               +--------------------------+--------------------------------------------------------------------------------------+
|               | SubnetID                 | fvx83jt2BWyibBRL4SRMa6WzjWp7GSFUeUUeoeBe1AqJ5Ey5w                                    |
|               +--------------------------+--------------------------------------------------------------------------------------+
|               | BlockchainID (CB58)      | 2QGB9GbEhsFJLSRVii2mKs8dxugHzmK98G5391P2bvXSCb4sED                                   |
|               +--------------------------+--------------------------------------------------------------------------------------+
|               | BlockchainID (HEX)       | 0xb883b54815c84a3f0903dbccd289ed5563395dd61c189db626e2d2680546b990                   |
|               +--------------------------+--------------------------------------------------------------------------------------+
|               | RPC Endpoint             | http://127.0.0.1:60538/ext/bc/2QGB9GbEhsFJLSRVii2mKs8dxugHzmK98G5391P2bvXSCb4sED/rpc |
+---------------+--------------------------+--------------------------------------------------------------------------------------+

+------------------------------------------------------------------------------------+
|                                         ICM                                        |
+---------------+-----------------------+--------------------------------------------+
| Local Network | ICM Messenger Address | 0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf |
|               +-----------------------+--------------------------------------------+
|               | ICM Registry Address  | 0x695Ea5FbeBBdc99cA679F5fD7768f179d2281d74 |
+---------------+-----------------------+--------------------------------------------+

+-------------------------------+
|           TOKEN               |
+--------------+----------------+
| Token Name   | TUTORIAL Token |
+--------------+----------------+
| Token Symbol | TUTORIAL       |
+--------------+----------------+

+----------------------------------------------------------------------------------------------------------------------------------------+
|                                                        INITIAL TOKEN ALLOCATION                                                        |
+-------------------------+------------------------------------------------------------------+---------------+---------------------------+
| DESCRIPTION             | ADDRESS AND PRIVATE KEY                                          | AMOUNT (OWEN) | AMOUNT (WEI)              |
+-------------------------+------------------------------------------------------------------+---------------+---------------------------+
| Main funded account     | 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC                       | 1000000       | 1000000000000000000000000 |
| ewoq                    | 56289e99c94b6912bfc12adc093c9b51124f0dc54ac7a766b2bc5ccf558d8027 |               |                           |
+-------------------------+------------------------------------------------------------------+---------------+---------------------------+
| Used by ICM             | 0x001CBe3650FAD190d9ccBd57b289124F5131AA57                       | 600           | 600000000000000000000     |
| cli-teleporter-deployer | d00b93e1526d05a30b681911a3e0f5e5528add205880c1cafa4f84cdb2746b00 |               |                           |
+-------------------------+------------------------------------------------------------------+---------------+---------------------------+

+-----------------------------------------------------------------------------------------------------------------+
|                                                 SMART CONTRACTS                                                 |
+-----------------------+--------------------------------------------+--------------------------------------------+
| DESCRIPTION           | ADDRESS                                    | DEPLOYER                                   |
+-----------------------+--------------------------------------------+--------------------------------------------+
| Proxy Admin           | 0xC0fFEE1234567890aBCdeF1234567890abcDef34 | 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC |
+-----------------------+--------------------------------------------+--------------------------------------------+
| PoA Validator Manager | 0x0C0DEbA5E0000000000000000000000000000000 |                                            |
+-----------------------+--------------------------------------------+--------------------------------------------+
| Transparent Proxy     | 0x0Feedc0de0000000000000000000000000000000 |                                            |
+-----------------------+--------------------------------------------+--------------------------------------------+

+----------------------------------------------------------------------+
|                      INITIAL PRECOMPILE CONFIGS                      |
+------------+-----------------+-------------------+-------------------+
| PRECOMPILE | ADMIN ADDRESSES | MANAGER ADDRESSES | ENABLED ADDRESSES |
+------------+-----------------+-------------------+-------------------+
| Warp       | n/a             | n/a               | n/a               |
+------------+-----------------+-------------------+-------------------+

+--------------------------------------------------------------------------+
|                                   NODES                                  |
+-------+------------------------------------------+-----------------------+
| NAME  | NODE ID                                  | LOCALHOST ENDPOINT    |
+-------+------------------------------------------+-----------------------+
| node1 | NodeID-7Xhw2mDxuDS44j42TCB6U5579esbSt3Lg | http://127.0.0.1:9650 |
+-------+------------------------------------------+-----------------------+
| node2 | NodeID-MFrZFVCXPv5iCn6M9K6XduxGTYp891xXZ | http://127.0.0.1:9652 |
+-------+------------------------------------------+-----------------------+

+--------------------------------------------------------------------------------------------------------+
|                                            WALLET CONNECTION                                           |
+-----------------+--------------------------------------------------------------------------------------+
| Network RPC URL | http://127.0.0.1:60538/ext/bc/2QGB9GbEhsFJLSRVii2mKs8dxugHzmK98G5391P2bvXSCb4sED/rpc |
+-----------------+--------------------------------------------------------------------------------------+
| Network Name    | myblockchain                                                                         |
+-----------------+--------------------------------------------------------------------------------------+
| Chain ID        | 12345                                                                                |
+-----------------+--------------------------------------------------------------------------------------+
| Token Symbol    | TUTORIAL                                                                             |
+-----------------+--------------------------------------------------------------------------------------+
| Token Name      | TUTORIAL Token                                                                       |
+-----------------+--------------------------------------------------------------------------------------+

```

## Viewing a Genesis File

If you'd like to see the raw genesis file, supply the `--genesis` flag to the describe command: `avalanche blockchain describe <blockchainName> --genesis`

Example:

```bash
> avalanche blockchain describe myblockchain --genesis

{
    "config": {
        "berlinBlock": 0,
        "byzantiumBlock": 0,
        "chainId": 111,
        "constantinopleBlock": 0,
        "eip150Block": 0,
        "eip155Block": 0,
        "eip158Block": 0,
        "feeConfig": {
            "gasLimit": 12000000,
            "targetBlockRate": 2,
            "minBaseFee": 25000000000,
            "targetGas": 60000000,
            "baseFeeChangeDenominator": 36,
            "minBlockGasCost": 0,
            "maxBlockGasCost": 1000000,
            "blockGasCostStep": 200000
        },
        "homesteadBlock": 0,
        "istanbulBlock": 0,
        "londonBlock": 0,
        "muirGlacierBlock": 0,
        "petersburgBlock": 0,
        "warpConfig": {
            "blockTimestamp": 1734549536,
            "quorumNumerator": 67,
            "requirePrimaryNetworkSigners": true
        }
    },
    "nonce": "0x0",
    "timestamp": "0x67632020",
    "extraData": "0x",
    "gasLimit": "0xb71b00",
    "difficulty": "0x0",
    "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "coinbase": "0x0000000000000000000000000000000000000000",
    "alloc": {
        "001cbe3650fad190d9ccbd57b289124f5131aa57": {
            "balance": "0x2086ac351052600000"
        },
        "0c0deba5e0000000000000000000000000000000": {
            "code": "<PoA validator manager deployed bytecode>",
            "balance": "0x0",
            "nonce": "0x1"
        },
        "0feedc0de0000000000000000000000000000000": {
            "code": "<transparent proxy deployed bytecode>",
            "storage": {
                "0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc": "0x0000000000000000000000000c0deba5e0000000000000000000000000000000", //sslot for proxy implementation
                "0xb53127684a568b3173ae13b9f8a6016e243e63b6e8ee1178d6a717850b5d6103": "0x000000000000000000000000c0ffee1234567890abcdef1234567890abcdef34"  //sslot for proxy admin
            },
            "balance": "0x0",
            "nonce": "0x1"
        },
        "8db97c7cece249c2b98bdc0226cc4c2a57bf52fc": {
            "balance": "0xd3c21bcecceda1000000"
        },
        "c0ffee1234567890abcdef1234567890abcdef34": {
            "code": "<proxy admin deployed bytecode>",
            "storage": {
                "0x0000000000000000000000000000000000000000000000000000000000000000": "0x0000000000000000000000008db97c7cece249c2b98bdc0226cc4c2a57bf52fc" //sslot for owner
            },
            "balance": "0x0",
            "nonce": "0x1"
        }
    },
    "airdropHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "airdropAmount": null,
    "number": "0x0",
    "gasUsed": "0x0",
    "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "baseFeePerGas": null,
    "excessBlobGas": null,
    "blobGasUsed": null
}
```

# Ledger P-Chain Transfer (/docs/tooling/avalanche-cli/transactions/ledger-p-chain-transfer)

---
title: Ledger P-Chain Transfer
description: Transferring funds between P-Chain using Avalanche CLI.
---

Transferring funds between P-Chain wallets becomes necessary in certain situations:

1.  Funds need to be sent to the Avalanche L1 control key, which might have a zero balance due to fee payments. The Avalanche L1 control key requires funding to ensure proper support for Avalanche L1 operations.
2.  Funds need to be moved from one Ledger address index to another. A Ledger manages an infinite sequence of addresses all derived from a master private key and can sign for any of those addresses. Each one is referred to by an index, or the associated address. Avalanche-CLI usually expects to use index 0, but sometimes, the funds are in a different index. Occasionally, a transfer made to a ledger can be made to an address different from the default one used by the CLI.

To enable direct transfers between P-Chain addresses, use the command `avalanche key transfer`. This operation involves a series of import/export actions with the P-Chain and X-Chain. The fee for this operation is four times the typical import operation fee, which comes out to 0.004 AVAX. You can find more information about fees [here](/docs/api-reference/standards/guides/txn-fees).

<Callout title="Note">
The `key transfer` command can also be applied to the stored keys managed by the CLI. It enables moving funds from one stored key to another, and from a ledger to a stored key or the other way.
</Callout>

This how-to guide focuses on transferring funds between ledger accounts.

## Prerequisites

- [`Avalanche-CLI`](/docs/tooling/get-avalanche-cli) installed
- Multiple Ledger devices [configured for Avalanche](/docs/tooling/create-deploy-avalanche-l1s/deploy-on-mainnet#setting-up-your-ledger)

Example: Sending All Funds From One Ledger to Another[​](#example-sending-all-funds-from-one-ledger-to-another "Direct link to heading")
----------------------------------------------------------------------------------------------------------------------------------------

- Source address: ledger A, index 2 (the web wallet shows 4.5 AVAX for this ledger)
- Target address: ledger B, index 0 (the web wallet shows 0 AVAX for this ledger)

### Determine Sender Address Index[​](#determine-sender-address-index "Direct link to heading")

A ledger can manage an infinite amount of addresses derived from a main private key. Because of this, many operations require the user to specify an address index.

After confirming with a web wallet that 4.5 AVAX is available on p-chain address `P-avax10an3cucdfqru984pnvv6y0rspvvclz63e523m0`, connect ledger A.

With the avalanche app running, execute:

```bash
avalanche key list --mainnet --ledger 0,1,2,3,4,5
```

To see p-chain addresses and balances for the first 6 indices in the ledger derived owner addresses.

```bash
+--------+---------+-------------------------+-----------------------------------------------+---------+---------+
|  KIND  |  NAME   |          CHAIN          |                    ADDRESS                    | BALANCE | NETWORK |
+--------+---------+-------------------------+-----------------------------------------------+---------+---------+
| ledger | index 0 | P-Chain (Bech32 format) | P-avax1g8yucm7j0cnwwru4rp5lkzw6dpdxjmc2rfkqs9 |       0 | Mainnet |
+        +---------+                         +-----------------------------------------------+---------+---------+
|        | index 1 |                         | P-avax1drppshkst2ccygyq37m2z9e3ex2jhkd2txcm5r |       0 | Mainnet |
+        +---------+                         +-----------------------------------------------+---------+---------+
|        | index 2 |                         | P-avax10an3cucdfqru984pnvv6y0rspvvclz63e523m0 |     4.5 | Mainnet |
+        +---------+                         +-----------------------------------------------+---------+---------+
|        | index 3 |                         | P-avax1yfpm7v5y5rej2nu7t2r0ffgrlpfq36je0rc5k6 |       0 | Mainnet |
+        +---------+                         +-----------------------------------------------+---------+---------+
|        | index 4 |                         | P-avax17nqvwcqsa8ddgeww8gzmfe932pz2syaj2vyd89 |       0 | Mainnet |
+        +---------+                         +-----------------------------------------------+---------+---------+
|        | index 5 |                         | P-avax1jzvnd05vsfksrtatm2e3rzu6eux9a287493yf8 |       0 | Mainnet |
+--------+---------+-------------------------+-----------------------------------------------+---------+---------+
```

The address `P-avax10an3cucdfqru984pnvv6y0rspvvclz63e523m0` has 4.5 AVAX and is associated with index 2 of ledger A.

### Determine Receiver Address Index[​](#determine-receiver-address-index "Direct link to heading")

In this case the user wants to use index 0, the one CLI by default expects to contain funds.

For the transfer command, it is also needed to know the target p-chain address. Do the following to obtain it:

With the ledger B connected and the avalache app running, execute:

```bash
avalanche key list --mainnet --ledger 0
```

```bash
+--------+---------+-------------------------+-----------------------------------------------+---------+---------+
|  KIND  |  NAME   |          CHAIN          |                    ADDRESS                    | BALANCE | NETWORK |
+--------+---------+-------------------------+-----------------------------------------------+---------+---------+
| ledger | index 0 | P-Chain (Bech32 format) | P-avax1r4aceznjkz8ch4pmpqrmkq4f3sl952mdrdt6xm |       0 | Mainnet |
+--------+---------+-------------------------+-----------------------------------------------+---------+---------+
```

Target address to be used is `P-avax1r4aceznjkz8ch4pmpqrmkq4f3sl952mdrdt6xm`, containing 0 funds.

### Send the Transfer[​](#send-the-transfer "Direct link to heading")

A P-Chain to P-chain transfer is a two-part operation. There is no need for the two parts to be executed on the same machine, only for them to have some common params. For each part, the appropriate ledger (either source or target) must be connected to the machine executing it.

The first step moves the money out of the source account into a X-Chain account owner by the receiver. It needs to be signed by the sending ledger.

Enter the amount of AVAX to send to the recipient. This amount does not include fees.

Note that the sending ledger pays all the fees.

Then start the command:

```bash
avalanche key transfer
```

First step is to specify the network. `Mainnet` in this case:

```bash
Use the arrow keys to navigate: ↓ ↑ → ←
? Network to use:
  ▸ Mainnet
    Fuji
    Local Network
```

Next, the step of the transfer must be specified. Send in this case:

```bash
? Step of the transfer:
  ▸ Send
    Receive
```

Next, the key source for the sender address. That is, the key that is going to sign the sending transactions. Select `Use ledger`:

```bash
? Which key source should be used to  for the sender address?:
    Use stored key
  ▸ Use ledger
```

Next, the ledger index is asked for. Input `2`:

```bash
✗ Ledger index to use: 2
```

Next, the amount to be sent is asked for:

```bash
✗ Amount to send (AVAX units): 4.496
```

The, the target address is required:

```bash
✗ Receiver address: P-avax1r4aceznjkz8ch4pmpqrmkq4f3sl952mdrdt6xm
```

After that, a confirmation message is printed. Read carefully and choose `Yes`:

```bash
this operation is going to:
- send 4.496000000 AVAX from P-avax10an3cucdfqru984pnvv6y0rspvvclz63e523m0 to target address P-avax1r4aceznjkz8ch4pmpqrmkq4f3sl952mdrdt6xm
- take a fee of 0.004000000 AVAX from source address P-avax10an3cucdfqru984pnvv6y0rspvvclz63e523m0

Use the arrow keys to navigate: ↓ ↑ → ←
? Confirm transfer:
    No
  ▸ Yes
```

After this, the first part is completed:

### Receive the Transfer[​](#receive-the-transfer "Direct link to heading")

In this step, Ledger B signs the transaction to receive the funds. It imports the funds on the X-Chain before exporting them back to the desired P-Chain address.

Connect ledger B and execute avalanche app.

Then start the command:

```bash
avalanche key transfer
```

Specify the `Mainnet` network:

```bash
Use the arrow keys to navigate: ↓ ↑ → ←
? Network to use:
  ▸ Mainnet
    Fuji
    Local Network
```

Next, the step of the transfer must be specified. Receive in this case:

```bash
? Step of the transfer:
    Send
  ▸ Receive
```

Then, select Ledger as the key source that is going to sign the receiver operations.

```bash
? Which key source should be used to  for the receiver address?:
    Use stored key
  ▸ Use ledger
```

Next, the ledger index is asked for. Input `0`:

```bash
✗ Ledger index to use: 0
```

Next, the amount to receive is asked for:

```bash
✗ Amount to send (AVAX units): 4.496
```

After that, a confirmation message is printed. Select `Yes`:

```bash
this operation is going to:
- receive 4.496000000 AVAX at target address P-avax1r4aceznjkz8ch4pmpqrmkq4f3sl952mdrdt6xm:

Use the arrow keys to navigate: ↓ ↑ → ←
? Confirm transfer:
    No
  ▸ Yes
```

Finally, the second part of the operation is executed and the transfer is completed.

```bash
Issuing ImportTx P -> X
Issuing ExportTx X -> P
Issuing ImportTx X -> P
```

### Verifying Results of the Transfer Operation using `key list`[​](#verifying-results-of-the-transfer-operation-using-key-list "Direct link to heading")

First verify ledger A accounts. Connect ledger A and open the avalanche app:

```bash
avalanche key list --mainnet --ledger 0,1,2,3,4,5
```

With result:

```bash
+--------+---------+-------------------------+-----------------------------------------------+---------+---------+
|  KIND  |  NAME   |          CHAIN          |                    ADDRESS                    | BALANCE | NETWORK |
+--------+---------+-------------------------+-----------------------------------------------+---------+---------+
| ledger | index 0 | P-Chain (Bech32 format) | P-avax1g8yucm7j0cnwwru4rp5lkzw6dpdxjmc2rfkqs9 |       0 | Mainnet |
+        +---------+                         +-----------------------------------------------+---------+---------+
|        | index 1 |                         | P-avax1drppshkst2ccygyq37m2z9e3ex2jhkd2txcm5r |       0 | Mainnet |
+        +---------+                         +-----------------------------------------------+---------+---------+
|        | index 2 |                         | P-avax10an3cucdfqru984pnvv6y0rspvvclz63e523m0 |       0 | Mainnet |
+        +---------+                         +-----------------------------------------------+---------+---------+
|        | index 3 |                         | P-avax1yfpm7v5y5rej2nu7t2r0ffgrlpfq36je0rc5k6 |       0 | Mainnet |
+        +---------+                         +-----------------------------------------------+---------+---------+
|        | index 4 |                         | P-avax17nqvwcqsa8ddgeww8gzmfe932pz2syaj2vyd89 |       0 | Mainnet |
+        +---------+                         +-----------------------------------------------+---------+---------+
|        | index 5 |                         | P-avax1jzvnd05vsfksrtatm2e3rzu6eux9a287493yf8 |       0 | Mainnet |
+--------+---------+-------------------------+-----------------------------------------------+---------+---------+
```

Next, verify ledger B accounts. Connect ledger B and open the avalanche app:

```bash
avalanche key list --mainnet --ledger 0,1,2,3,4,5
```

With result:

```bash
+--------+---------+-------------------------+-----------------------------------------------+---------+---------+
|  KIND  |  NAME   |          CHAIN          |                    ADDRESS                    | BALANCE | NETWORK |
+--------+---------+-------------------------+-----------------------------------------------+---------+---------+
| ledger | index 0 | P-Chain (Bech32 format) | P-avax1r4aceznjkz8ch4pmpqrmkq4f3sl952mdrdt6xm |   4.496 | Mainnet |
+        +---------+                         +-----------------------------------------------+---------+---------+
|        | index 1 |                         | P-avax18e9qsm30du590lhkwydhmkfwhcc9999gvxcaez |       0 | Mainnet |
+        +---------+                         +-----------------------------------------------+---------+---------+
|        | index 2 |                         | P-avax1unkkjstggvdty5gtnfhc0mgnl7qxa52z2d4c9y |       0 | Mainnet |
+        +---------+                         +-----------------------------------------------+---------+---------+
|        | index 3 |                         | P-avax1ek7n0zky3py7prxcrgnmh44y3wm6lc7r7x5r8e |       0 | Mainnet |
+        +---------+                         +-----------------------------------------------+---------+---------+
|        | index 4 |                         | P-avax1rsz6nt6qht5ep37qjk7ht0u9h30mgfhehsmqea |       0 | Mainnet |
+        +---------+                         +-----------------------------------------------+---------+---------+
|        | index 5 |                         | P-avax17u5wm4tfex7xr27xlwejm28pyk84tj0jzp42zz |       0 | Mainnet |
+--------+---------+-------------------------+-----------------------------------------------+---------+---------+
```

### Recovery Steps[​](#recovery-steps "Direct link to heading")

As a multi step operation, the receiving part of the transfer can have intermediate errors, due for example to temporal network connections on the client side.

The CLI is going to capture errors and provide the user with a recovery message of the kind:

```bash
ERROR: restart from this step by using the same command with extra arguments: --receive-recovery-step 1
```

If this happen, the receiving operation should be started the same way, choosing the same options, but adding the extra suggested parameter:

```bash
avalanche key transfer --receive-recovery-step 1
```

Then, the CLI is going to resume where it left off.

# Send AVAX on C/P-Chain (/docs/tooling/avalanche-cli/transactions/native-send)

---
title: Send AVAX on C/P-Chain
description: Learn how to execute a native transfer on the C or P-Chain using the Avalanche CLI.
---

# Prerequisites

- Install the [Avalanche CLI](/docs/tooling/get-avalanche-cli).
- Use the CLI to [create a key](/docs/tooling/cli-commands#key-create).
- Fund the key with AVAX. You can use the [faucet](https://test.core.app/tools/testnet-faucet/?subnet=c&token=c) with coupon code `devrel-avax-0112` to get testnet AVAX. 
- *Optionally*, you can [export](/docs/tooling/cli-commands#key-export) your private key for use in scripting or other tools. 

## Initiate the `transfer` Command and Walk Through the Prompts

In your terminal, run the following command:

```zsh
avalanche key transfer
```

<Callout title="Note">

This command and all of its flags are documented [here](/docs/tooling/cli-commands#key-transfer).

</Callout>

You will be prompted to answer the following questions:

```zsh
? On what Network do you want to execute the transfer?:
  ▸ Mainnet
    Fuji Testnet
    Devnet
    Local Network
```
<Accordions>
<Accordion title="Note: Devnet">
If you select "Devnet", you must input the RPC URL. If your devnet's C-Chain RPC is `https://demo.avax-dev.network/ext/bc/C/rpc`, you should input the URL as: 

```zsh
✔ Devnet Endpoint: https://demo.avax-dev.network
```

</Accordion>
</Accordions>

Select the chain you want to transfer funds from:

```zsh
? Where are the funds to transfer?:
  ▸ P-Chain
    C-Chain
    My blockchain isn't listed
```

Select the chain you want to transfer funds to:

```zsh
? Destination Chain:
  ▸ P-Chain
    X-Chain
```

Select the step of the transfer process you want to execute:

```zsh
? Step of the transfer:
  ▸ Send
    Receive
```

<Callout title="Note">

If you are performing a native transfer where the sender and receiver address are on the same chain, you only need to complete a "send" transaction. 

If you wish to perform a cross-chain transfer (i.e. from C to P-Chain), you should abort this flow and reinitiate the command as `avalanche key transfer --fund-p-chain` or `avalanche key transfer --fund-x-chain`, completing both the "send" and "receive" flows with keys stored in the CLI.
You can fund your CLI-stored key with AVAX on the C-Chain using the [faucet](https://test.core.app/tools/testnet-faucet/?subnet=c&token=c) with coupon code `devrel-avax-0112`.

</Callout>

Select the sender address:

```zsh
? Which key should be used as the sender?:
  ▸ Use stored key
    Use ledger
? Which stored key should be used as the sender address?:
  ▸ DemoKey
    MyKey
    ewoq
```

Specify the amount to send, input the destination address: 
  
```zsh
✗ Amount to send (AVAX units): 100
✗ Destination address: P-avax1zgjx8zj7z7zj7z7zj7z7zj7z7zj7zj7zj7zj7e
```

Review the transaction details and confirm/abort:

```zsh
this operation is going to:
- send 100.000000000 AVAX from P-avax1gmuqt8xg9j4h88kj3hyprt23nf50azlfg8txn2 to destination address P-avax1f630gvct4ht35ragcheapnn2n5cv2tkmq73ec0
- take a fee of 0.001000000 AVAX from source address P-avax1gmuqt8xg9j4h88kj3hyprt23nf50azlfg8txn2
? Confirm transfer:
    No
  ▸ Yes
```

After a successful transfer, you can check your CLI keys' balances with the [command](/docs/tooling/cli-commands#key-list): `avalanche key list`.


# Precompile Configs (/docs/tooling/avalanche-cli/upgrade/avalanche-l1-precompile-config)

---
title: Precompile Configs
description: Learn how to upgrade your Subnet-EVM precompile configurations.
---

You can customize Subnet-EVM based Avalanche L1s after deployment by enabling and disabling precompiles. To do this, create a `upgrade.json` file and place it in the appropriate directory.

This document describes how to perform such network upgrades. It's specific for Subnet-EVM upgrades.

The document [Upgrade an Avalanche L1](/docs/avalanche-l1s/upgrade/considerations) describes all the background information required regarding Avalanche L1 upgrades.

<Callout type="warn">
It's very important that you have read and understood the previously linked document. Failing to do so can potentially grind your network to a halt.
</Callout>

This tutorial assumes that you have already [installed](/docs/tooling/get-avalanche-cli) Avalanche-CLI. It assumes you have already created and deployed an Avalanche L1 called `testblockchain`.

Generate the Upgrade File[​](#generate-the-upgrade-file "Direct link to heading")
---------------------------------------------------------------------------------

The [Precompiles](/docs/avalanche-l1s/upgrade/customize-avalanche-l1#network-upgrades-enabledisable-precompiles) documentation describes what files the network upgrade requires, and where to place them.

To generate a valid `upgrade.json` file, run:

```bash
avalanche blockchain upgrade generate testblockchain
```

If you didn't create `testblockchain` yet, you would see this result:

```bash
avalanche blockchain upgrade generate testblockchain
The provided Avalanche L1 name "testblockchain" does not exist
```

Again, it makes no sense to try the upgrade command if the Avalanche L1 doesn't exist. If that's the case, please go ahead and [create](/docs/tooling/create-avalanche-l1) the Avalanche L1 first.

If the Avalanche L1 definition exists, the tool launches a wizard. It may feel a bit redundant, but you first see some warnings, to draw focus to the dangers involved:

```bash
avalanche blockchain upgrade generate testblockchain
Performing a network upgrade requires coordinating the upgrade network-wide.
A network upgrade changes the rule set used to process and verify blocks, such that any node that
upgrades incorrectly or fails to upgrade by the time that upgrade goes into effect may become
out of sync with the rest of the network.

Any mistakes in configuring network upgrades or coordinating them on validators may cause the
network to halt and recovering may be difficult.
Please consult
https://build.avax.network/docs/subnets/customize-a-subnet#network-upgrades-enabledisable-precompiles
for more information
Use the arrow keys to navigate: ↓ ↑ → ←
? Press [Enter] to continue, or abort by choosing 'no':
  ▸ Yes
    No
```

Go ahead and select `Yes` if you understand everything and you agree.

You see a last note, before the actual configuration wizard starts:

```bash
Avalanchego and this tool support configuring multiple precompiles.
However, we suggest to only configure one per upgrade.

Use the arrow keys to navigate: ↓ ↑ → ←
? Select the precompile to configure:
  ▸ Contract Deployment Allow List
    Manage Fee Settings
    Native Minting
    Transaction Allow List
```

Refer to [Precompiles](/docs/avalanche-l1s/upgrade/customize-avalanche-l1#precompiles) for a description of available precompiles and how to configure them.

Make sure you understand precompiles thoroughly and how to configure them before attempting to continue.

For every precompile in the list, the wizard guides you to provide correct information by prompting relevant questions. For the sake of this tutorial, select `Transaction Allow List`. The document [Restricting Who Can Submit Transactions](/docs/avalanche-l1s/upgrade/customize-avalanche-l1#restricting-who-can-submit-transactions) describes what this precompile is about.

```bash
✔ Transaction Allow List
Set parameters for the "Manage Fee Settings" precompile
Use the arrow keys to navigate: ↓ ↑ → ←
? When should the precompile be activated?:
  ▸ In 5 minutes
    In 1 day
    In 1 week
    In 2 weeks
    Custom
```

This is actually common to all precompiles: they require an activation timestamp. If you think about it, it makes sense: you want a synchronized activation of your precompile. So think for a moment about when you want to set the activation timestamp to. You can select one of the suggested times in the future, or you can pick a custom one. After picking `Custom`, it shows the following prompt:

```bash
✔ Custom
✗ Enter the block activation UTC datetime in 'YYYY-MM-DD HH:MM:SS' format:
```

The format is `YYYY-MM-DD HH:MM:SS`, therefore `2023-03-31 14:00:00` would be a valid timestamp. Notice that the timestamp is in UTC. Please make sure you have converted the time from your timezone to UTC. Also notice the `✗` at the beginning of the line. The CLI tool does input validation, so if you provide a valid timestamp, the `x` disappears:

```bash
✔ Enter the block activation UTC datetime in 'YYYY-MM-DD HH:MM:SS' format: 2023-03-31 14:00:00
```

The timestamp must be in the **future**, so make sure you use such a timestamp should you be running this tutorial after `2023-03-31 14:00:00`.

After you provided the valid timestamp, proceed with the precompile specific configurations:

```bash
The chosen block activation time is 2023-03-31 14:00:00
Use the arrow keys to navigate: ↓ ↑ → ←
? Add 'adminAddresses'?:
  ▸ Yes
    No
```

This will enable the addresses added in this section to add other admins and/or add enabled addresses for transaction issuance. The addresses provided in this tutorial are fake.

<Callout type="warn">
However, make sure you or someone you trust have full control over the addresses. Otherwise, you might bring your Avalanche L1 to a halt.
</Callout>

```bash
✔ Yes
Use the arrow keys to navigate: ↓ ↑ → ←
? Provide 'adminAddresses':
  ▸ Add
    Delete
    Preview
    More Info
↓   Done
```

The prompting runs with a pattern used throughout the tool:

1. Select an operation:
    - `Add`: adds a new address to the current list
    - `Delete`: removes an address from the current list
    - `Preview`: prints the current list
2. `More info` prints additional information for better guidance, if available
3. Select `Done` when you completed the list

Go ahead and add your first address:

```bash
✔ Add
✔ Add an address: 0xaaaabbbbccccddddeeeeffff1111222233334444
```

Add another one:

```bash
✔ Add
Add an address: 0xaaaabbbbccccddddeeeeffff1111222233334444
✔ Add
✔ Add an address: 0x1111222233334444aaaabbbbccccddddeeeeffff
```

Select `Preview` this time to confirm the list is correct:

```bash
✔ Preview
0. 0xaaaAbbBBCccCDDddEeEEFFfF1111222233334444
1. 0x1111222233334444aAaAbbBBCCCCDdDDeEeEffff
Use the arrow keys to navigate: ↓ ↑ → ←
? Provide 'adminAddresses':
  ▸ Add
    Delete
    Preview
    More Info
↓   Done
```

If it looks good, select `Done` to continue:

```bash
✔ Done
Use the arrow keys to navigate: ↓ ↑ → ←
? Add 'enabledAddresses'?:
  ▸ Yes
    No
```

Add one such enabled address, these are addresses which can issue transactions:

```bash
✔ Add
✔ Add an address: 0x55554444333322221111eeeeaaaabbbbccccdddd█
```

After you added this address, and selected `Done`, the tool asks if you want to add another precompile:

```bash
✔ Done
Use the arrow keys to navigate: ↓ ↑ → ←
? Should we configure another precompile?:
  ▸ No
    Yes
```

If you needed to add another one, you would select `Yes` here. The wizard would guide you through the other available precompiles, excluding already configured ones.

To avoid making this tutorial too long, the assumption is you're done here. Select `No`, which ends the wizard.

This means you have successfully terminated the generation of the upgrade file, often called upgrade bytes. The tool stores them internally.

<Callout type="warn">
You shouldn't move files around manually. Use the `export` and `import` commands to get access to the files.
</Callout>

So at this point you can either:

- Deploy your upgrade bytes locally
- Export your upgrade bytes to a file, for installation on a validator running on another machine
- Import a file into a different machine running Avalanche-CLI

How To Upgrade a Local Network[​](#how-to-upgrade-a-local-network "Direct link to heading")
-------------------------------------------------------------------------------------------

The normal use case for this operation is that:

- You already created an Avalanche L1
- You already deployed the Avalanche L1 locally
- You already generated the upgrade file with the preceding command or imported into the tool
- This tool already started the network

If the preceding requirements aren't met, the network upgrade command fails.

Therefore, to apply your generated or imported upgrade configuration:

```bash
avalanche blockchain upgrade apply testblockchain
```

A number of checks run. For example, if you created the Avalanche L1 but didn't deploy it locally:

```bash
avalanche blockchain upgrade apply testblockchain
Error: no deployment target available
Usage:
  avalanche blockchain upgrade apply [blockchainName] [flags]

Flags:
      --avalanchego-chain-config-dir string   avalanchego's chain config file directory (default "/home/fabio/.avalanchego/chains")
      --config                                create upgrade config for future Avalanche L1 deployments (same as generate)
      --fuji fuji                             apply upgrade existing fuji deployment (alias for `testnet`)
  -h, --help                                  help for apply
      --local local                           apply upgrade existing local deployment
      --mainnet mainnet                       apply upgrade existing mainnet deployment
      --print                                 if true, print the manual config without prompting (for public networks only)
      --testnet testnet                       apply upgrade existing testnet deployment (alias for `fuji`)

Global Flags:
      --log-level string   log level for the application (default "ERROR")
```

Go ahead and [deploy](/docs/tooling/create-deploy-avalanche-l1s/deploy-locally) first your Avalanche L1 if that's your case.

If you already had deployed the Avalanche L1 instead, you see something like this:

```bash
avalanche blockchain upgrade apply testblockchain
Use the arrow keys to navigate: ↓ ↑ → ←
? What deployment would you like to upgrade:
  ▸ Existing local deployment
```

Select `Existing local deployment`. This installs the upgrade file on all nodes of your local network running in the background.

Et voilà. This is the output shown if all went well:

```bash
✔ Existing local deployment
.......
Network restarted and ready to use. Upgrade bytes have been applied to running nodes at these endpoints.
The next upgrade will go into effect 2023-03-31 09:00:00
+-------+------------+-----------------------------------------------------------------------------------+
| NODE  |     VM     |                                        URL                                        |
+-------+------------+-----------------------------------------------------------------------------------+
| node1 | testblockchain | http://0.0.0.0:9650/ext/bc/2YTRV2roEhgvwJz7D7vr33hUZscpaZgcYgUTjeMK9KH99NFnsH/rpc |
+-------+------------+-----------------------------------------------------------------------------------+
| node2 | testblockchain | http://0.0.0.0:9652/ext/bc/2YTRV2roEhgvwJz7D7vr33hUZscpaZgcYgUTjeMK9KH99NFnsH/rpc |
+-------+------------+-----------------------------------------------------------------------------------+
| node3 | testblockchain | http://0.0.0.0:9654/ext/bc/2YTRV2roEhgvwJz7D7vr33hUZscpaZgcYgUTjeMK9KH99NFnsH/rpc |
+-------+------------+-----------------------------------------------------------------------------------+
| node4 | testblockchain | http://0.0.0.0:9656/ext/bc/2YTRV2roEhgvwJz7D7vr33hUZscpaZgcYgUTjeMK9KH99NFnsH/rpc |
+-------+------------+-----------------------------------------------------------------------------------+
| node5 | testblockchain | http://0.0.0.0:9658/ext/bc/2YTRV2roEhgvwJz7D7vr33hUZscpaZgcYgUTjeMK9KH99NFnsH/rpc |
+-------+------------+-----------------------------------------------------------------------------------+
```

There is only so much the tool can do here for you. It installed the upgrade bytes _as-is_ as you configured respectively provided them to the tool. You should verify yourself that the upgrades were actually installed correctly, for example issuing some transactions - mind the timestamp!.

Apply the Upgrade to a Public Node (Fuji or Mainnet)[​](#apply-the-upgrade-to-a-public-node-fuji-or-mainnet "Direct link to heading")
-------------------------------------------------------------------------------------------------------------------------------------

For this scenario to work, you should also have deployed the Avalanche L1 to the public network (Fuji or Mainnet) with this tool. Otherwise, the tool won't know the details of the Avalanche L1, and won't be able to guide you.

Assuming the Avalanche L1 has been already deployed to Fuji, when running the `apply` command, the tool notices the deployment:

```bash
avalanche blockchain upgrade apply testblockchain
Use the arrow keys to navigate: ↓ ↑ → ←
? What deployment would you like to upgrade:
    Existing local deployment
  ▸ Fuji
```

If not, you would not find the `Fuji` entry here.

<Callout title="Note">
This scenario assumes that you are running the `fuji` validator on the same machine which is running Avalanche-CLI.
</Callout>

If this is the case, the tool tries to install the upgrade file at the expected destination. If you use default paths, it tries to install at `$HOME/.avalanchego/chains/`, creating the chain id directory, so that the file finally ends up at `$HOME/.avalanchego/chains/<chain-id>/upgrade.json`.

If you are _not_ using default paths, you can configure the path by providing the flag `--avalanchego-chain-config-dir` to the tool. For example:

```bash
avalanche blockchain upgrade apply testblockchain --avalanchego-chain-config-dir /path/to/your/chains
```

Make sure to identify correctly where your chain config dir is, or the node might fail to find it.

If all is correct, the file gets installed:

```bash
avalanche blockchain upgrade apply testblockchain
✔ Fuji
The chain config dir avalanchego uses is set at /home/fabio/.avalanchego/chains
Trying to install the upgrade files at the provided /home/fabio/.avalanchego/chains path
Successfully installed upgrade file
```

If however the node is _not_ running on this same machine where you are executing Avalanche-CLI, there is no point in running this command for a Fuji node. In this case, you might rather export the file and install it at the right location.

To see the instructions about how to go about this, add the `--print` flag:

```bash
avalanche blockchain upgrade apply testblockchain --print
✔ Fuji
To install the upgrade file on your validator:

1. Identify where your validator has the avalanchego chain config dir configured.
   The default is at $HOME/.avalanchego/chains (/home/user/.avalanchego/chains on this machine).
   If you are using a different chain config dir for your node, use that one.
2. Create a directory with the blockchainID in the configured chain-config-dir (e.g. $HOME/.avalanchego/chains/ExDKhjXqiVg7s35p8YJ56CJpcw6nJgcGCCE7DbQ4oBknZ1qXi) if doesn't already exist.
3. Create an `upgrade.json` file in the blockchain directory with the content of your upgrade file.
   This is the content of your upgrade file as configured in this tool:
{
    "precompileUpgrades": [
        {
            "txAllowListConfig": {
                "adminAddresses": [
                    "0xb3d82b1367d362de99ab59a658165aff520cbd4d"
                ],
                "enabledAddresses": null,
                "blockTimestamp": 1677550447
            }
        }
    ]
}

   ******************************************************************************************************************
   * Upgrades are tricky. The syntactic correctness of the upgrade file is important.                               *
   * The sequence of upgrades must be strictly observed.                                                            *
   * Make sure you understand https://build.avax.network/docs/nodes/configure/configs-flags#subnet-chain-configs  *
   * before applying upgrades manually.                                                                             *
   ******************************************************************************************************************
```

The instructions also show the content of your current upgrade file, so you can just select that if you wish. Or actually export the file.

Export the Upgrade File[​](#export-the-upgrade-file "Direct link to heading")
-----------------------------------------------------------------------------

If you have generated the upgrade file, you can export it:

```bash
avalanche blockchain upgrade export testblockchain
✔ Provide a path where we should export the file to: /tmp/testblockchain-upgrade.json
```

Just provide a valid path to the prompt, and the tool exports the file there.

```bash
avalanche blockchain upgrade export testblockchain
Provide a path where we should export the file to: /tmp/testblockchain-upgrade.json
Writing the upgrade bytes file to "/tmp/testblockchain-upgrade.json"...
File written successfully.
```

You can now take that file and copy it to validator nodes, see preceding instructions.

Import the Upgrade File[​](#import-the-upgrade-file "Direct link to heading")
-----------------------------------------------------------------------------

You or someone else might have generated the file elsewhere, or on another machine. And now you want to install it on the validator machine, using Avalanche-CLI.

You can import the file:

```bash
avalanche blockchain upgrade import testblockchain
Provide the path to the upgrade file to import: /tmp/testblockchain-upgrade.json
```

An existing file with the same path and filename would be overwritten.

After you have imported the file, you can `apply` it either to a local network or to a locally running validator. Follow the instructions for the appropriate use case.


# Virtual Machine (/docs/tooling/avalanche-cli/upgrade/avalanche-l1-virtual-machine)

---
title: Virtual Machine
description: This how-to guide explains how to upgrade the VM of an already-deployed Avalanche L1.
---

To upgrade a local Avalanche L1, you first need to pause the local network. To do so, run:

```bash
avalanche network stop
```

Next, you need to select the new VM to run your Avalanche L1 on. If you're running a Subnet-EVM Avalanche L1, you likely want to bump to the latest released version. If you're running a Custom VM, you'll want to choose another custom binary.

Start the upgrade wizard with:

```bash
avalanche blockchain upgrade vm <blockchainName>
```

where you replace `<blockchainName>` with the name of the Avalanche L1 you would like to upgrade.

## Selecting a VM Deployment to Upgrade

After starting the Avalanche L1 Upgrade Wizard, you should see something like this:

```bash
? What deployment would you like to upgrade:
  ▸ Update config for future deployments
    Existing local deployment
```

If you select the first option, Avalanche-CLI updates your Avalanche L1's config and any future calls to `avalanche blockchain deploy` use the new version you select. However, any existing local deployments continue to use the old version.

If you select the second option, the opposite occurs. The existing local deployment switches to the new VM but subsequent deploys use the original.

## Select a VM to Upgrade To

The next option asks you to select your new virtual machine.

```bash
? How would you like to update your Avalanche L1's virtual machine:
  ▸ Update to latest version
    Update to a specific version
    Update to a custom binary
```

If you're using the Subnet-EVM, you'll have the option to upgrade to the latest released version. You can also select a specific version or supply a custom binary. If your Avalanche L1 already uses a custom VM, you need to select another custom binary.

Once you select your VM, you should see something like:

```bash
Upgrade complete. Ready to restart the network.
```

## Restart the Network

<Callout title="Note">
If you are running multiple Avalanche L1s concurrently, you may need to update multiple Avalanche L1s to restart the network. All of your deployed must be using the same RPC Protocol version. You can see more details about this [here](/docs/tooling/maintain/troubleshooting#incompatible-rpc-version-for-custom-vm).
</Callout>

Finally, restart the network with:

```bash
avalanche network start
```

If the network starts correctly, your Avalanche L1 is now running the upgraded VM.


# Authentication (/docs/tooling/avalanche-sdk/chainkit/authentication)

---
title: Authentication
description: Authentication for the ChainKit SDK
icon: Lock
---
### Per-Client Security Schemes

This SDK supports the following security scheme globally:

| Name     | Type   | Scheme  |
| -------- | ------ | ------- |
| `apiKey` | apiKey | API key |

The ChainKit SDK can be used without an API key, but rate limits will be lower. Adding an API key allows for higher rate limits. To get an API key, create one via [Builder Console](/console/utilities/data-api-keys) and securely store it. Whether or not you use an API key, you can still interact with the SDK effectively, but the API key provides performance benefits for higher request volumes.

```javascript
import { Avalanche } from "@avalanche-sdk/chainkit";

const avalancheSDK = new Avalanche({
  apiKey: "<YOUR_API_KEY_HERE>",
  chainId: "43114",
  network: "mainnet",
});

async function run() {
  const result = await avalancheSDK.metrics.healthCheck();

  // Handle the result
  console.log(result);
}

run();
```

<Callout type="warning">
  Never hardcode your API key directly into your code. Instead, securely store
  it and retrieve it from an environment variable, a secrets manager, or a
  dedicated configuration storage mechanism. This ensures that sensitive
  information remains protected and is not exposed in version control or
  publicly accessible code.
</Callout>

# Custom HTTP Client (/docs/tooling/avalanche-sdk/chainkit/custom-http)

---
title: Custom HTTP Client
description: Custom HTTP Client for the ChainKit SDK
icon: Server
---

The TypeScript SDK makes API calls using an HTTPClient that wraps the native [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API). This client is a thin wrapper around `fetch` and provides the ability to attach hooks around the request lifecycle that can be used to modify the request or handle errors and response.

The `HTTPClient` constructor takes an optional `fetcher` argument that can be used to integrate a third-party HTTP client or when writing tests to mock out the HTTP client and feed in fixtures.

The following example shows how to use the `beforeRequest` hook to to add a custom header and a timeout to requests and how to use the `requestError` hook to log errors:

```javascript
import { Avalanche } from "@avalanche-sdk/chainkit";
import { HTTPClient } from "@avalanche-sdk/chainkit/lib/http";

const httpClient = new HTTPClient({
  // fetcher takes a function that has the same signature as native `fetch`.
  fetcher: (request) => {
    return fetch(request);
  },
});

httpClient.addHook("beforeRequest", (request) => {
  const nextRequest = new Request(request, {
    signal: request.signal || AbortSignal.timeout(5000),
  });

  nextRequest.headers.set("x-custom-header", "custom value");

  return nextRequest;
});

httpClient.addHook("requestError", (error, request) => {
  console.group("Request Error");
  console.log("Reason:", `${error}`);
  console.log("Endpoint:", `${request.method} ${request.url}`);
  console.groupEnd();
});

const sdk = new Avalanche({ httpClient });
```

# Error Handling (/docs/tooling/avalanche-sdk/chainkit/errors)

---
title: Error Handling
description: Error Handling for the ChainKit SDK
icon: Bug
---
All SDK methods return a response object or throw an error. If Error objects are specified in your OpenAPI Spec, the SDK will throw the appropriate Error type.

| Error Object               | Status Code | Content Type     |
| :------------------------- | :---------- | :--------------- |
| errors.BadRequest          | 400         | application/json |
| errors.Unauthorized        | 401         | application/json |
| errors.Forbidden           | 403         | application/json |
| errors.NotFound            | 404         | application/json |
| errors.TooManyRequests     | 429         | application/json |
| errors.InternalServerError | 500         | application/json |
| errors.BadGateway          | 502         | application/json |
| errors.ServiceUnavailable  | 503         | application/json |
| errors.SDKError            | 4xx-5xx     | /                |

Validation errors can also occur when either method arguments or data returned from the server do not match the expected format. The SDKValidationError that is thrown as a result will capture the raw value that failed validation in an attribute called `rawValue`. Additionally, a `pretty()` method is available on this error that can be used to log a nicely formatted string since validation errors can list many issues and the plain error string may be difficult read when debugging.

```javascript
import { Avalanche } from "@avalanche-sdk/chainkit";
import {
  BadGateway,
  BadRequest,
  Forbidden,
  InternalServerError,
  NotFound,
  SDKValidationError,
  ServiceUnavailable,
  TooManyRequests,
  Unauthorized,
} from "@avalanche-sdk/chainkit/models/errors";

const avalancheSDK = new Avalanche({
  apiKey: "<YOUR_API_KEY_HERE>",
  chainId: "43114",
  network: "mainnet",
});

async function run() {
  try {
    await avalancheSDK.data.nfts.reindex({
      address: "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E",
      tokenId: "145",
    });
  } catch (err) {
    switch (true) {
      case err instanceof SDKValidationError: {
        // Validation errors can be pretty-printed
        console.error(err.pretty());
        // Raw value may also be inspected
        console.error(err.rawValue);
        return;
      }
      case err instanceof BadRequest: {
        // Handle err.data$: BadRequestData
        console.error(err);
        return;
      }
      case err instanceof Unauthorized: {
        // Handle err.data$: UnauthorizedData
        console.error(err);
        return;
      }
      case err instanceof Forbidden: {
        // Handle err.data$: ForbiddenData
        console.error(err);
        return;
      }
      case err instanceof NotFound: {
        // Handle err.data$: NotFoundData
        console.error(err);
        return;
      }
      case err instanceof TooManyRequests: {
        // Handle err.data$: TooManyRequestsData
        console.error(err);
        return;
      }
      case err instanceof InternalServerError: {
        // Handle err.data$: InternalServerErrorData
        console.error(err);
        return;
      }
      case err instanceof BadGateway: {
        // Handle err.data$: BadGatewayData
        console.error(err);
        return;
      }
      case err instanceof ServiceUnavailable: {
        // Handle err.data$: ServiceUnavailableData
        console.error(err);
        return;
      }
      default: {
        throw err;
      }
    }
  }
}

run();
```

# Getting Started (/docs/tooling/avalanche-sdk/chainkit/getting-started)

---
title: Getting Started
description: Get started with the ChainKit SDK
icon: Rocket
---
### ChainKit SDK

The ChainKit SDK provides web3 application developers with multi-chain data related to Avalanche's primary network, Avalanche L1s, and Ethereum. With the Data API, you can easily build products that leverage real-time and historical transaction and transfer history, native and token balances, and various types of token metadata.

<Callout>
  **Migration Notice**: This SDK was previously known as the AvaCloud SDK. We
  have made namespace changes and will discontinue the AvaCloud SDK in favor of
  the ChainKit SDK. For migration guidance and specific method updates, please
  refer to the individual method documentation.
</Callout>

<img src="https://mintcdn.com/avalabs-47ea3976/5tYvr4aERqS4CNLz/images/chainkit-SDK.jpg?fit=max&auto=format&n=5tYvr4aERqS4CNLz&q=85&s=5ef81daf70200912ac6c1b505021c921" data-og-width="3968" width="3968" data-og-height="2452" height="2452" data-path="images/chainkit-SDK.jpg" data-optimize="true" data-opv="3" srcSet="https://mintcdn.com/avalabs-47ea3976/5tYvr4aERqS4CNLz/images/chainkit-SDK.jpg?w=280&fit=max&auto=format&n=5tYvr4aERqS4CNLz&q=85&s=17f99881ded8ce13a0df4784eb730562 280w, https://mintcdn.com/avalabs-47ea3976/5tYvr4aERqS4CNLz/images/chainkit-SDK.jpg?w=560&fit=max&auto=format&n=5tYvr4aERqS4CNLz&q=85&s=b64c64345a3586c1d73a1acdad757bb0 560w, https://mintcdn.com/avalabs-47ea3976/5tYvr4aERqS4CNLz/images/chainkit-SDK.jpg?w=840&fit=max&auto=format&n=5tYvr4aERqS4CNLz&q=85&s=606d74291aa14a9c98a169450b00ec9e 840w, https://mintcdn.com/avalabs-47ea3976/5tYvr4aERqS4CNLz/images/chainkit-SDK.jpg?w=1100&fit=max&auto=format&n=5tYvr4aERqS4CNLz&q=85&s=8cb8cb94c1851512eae03c1deaa71985 1100w, https://mintcdn.com/avalabs-47ea3976/5tYvr4aERqS4CNLz/images/chainkit-SDK.jpg?w=1650&fit=max&auto=format&n=5tYvr4aERqS4CNLz&q=85&s=855ca27fa8e66c64006f3d4623a7d8f6 1650w, https://mintcdn.com/avalabs-47ea3976/5tYvr4aERqS4CNLz/images/chainkit-SDK.jpg?w=2500&fit=max&auto=format&n=5tYvr4aERqS4CNLz&q=85&s=97d501a7bedbfc7c909e4b6b706bafe8 2500w" />

The SDK is currently available in TypeScript, with more languages coming soon. If you are interested in a language that is not listed, please reach out to us in the [#dev-tools](https://discord.com/channels/578992315641626624/1280920394236297257) channel in the [Avalanche Discord](https://discord.gg/avax).

<Cards>
  <Card title="NPM Package">
    [https://www.npmjs.com/package/@avalanche-sdk/chainkit](https://www.npmjs.com/package/@avalanche-sdk/chainkit)
  </Card>
  <Card title="GitHub Repository">
    [https://github.com/ava-labs/avalanche-sdk-typescript](https://github.com/ava-labs/avalanche-sdk-typescript)
  </Card>
</Cards>

### SDK Installation

<Tabs items={['npm', 'pnpm', 'bun', 'yarn']}>
  <Tab value="npm">
  ```bash
  npm add @avalanche-sdk/chainkit
  ```
</Tab>
<Tab value="pnpm">
  ```bash
  pnpm add @avalanche-sdk/chainkit
  ```
</Tab>
<Tab value="bun">
  ```bash
  bun add @avalanche-sdk/chainkit
  ```
</Tab>
<Tab value="yarn">
  ```bash
  yarn add @avalanche-sdk/chainkit zod
  ```
</Tab>
</Tabs>

### SDK Example Usage

```javascript
import { Avalanche } from "@avalanche-sdk/chainkit";

const avalancheSDK = new Avalanche({
    apiKey: "<YOUR_API_KEY_HERE>",
    chainId: "43114",
    network: "mainnet",
});

async function run() {
    const result = await avalancheSDK.metrics.healthCheck();

    // Handle the result
    console.log(result);
}

run();

```

Refer to the code samples provided for each route to see examples of how to use them in the SDK. Explore routes here [Data API](/docs/api-reference/data-api/getting-started),
[Metrics API](/docs/api-reference/metrics-api/getting-started) & [Webhooks API](/docs/api-reference/webhook-api/getting-started).

# Global Parameters (/docs/tooling/avalanche-sdk/chainkit/global-parameters)

---
title: Global Parameters
description: Global parameters for the ChainKit SDK
icon: Globe
---
Certain parameters are configured globally. These parameters may be set on the SDK client instance itself during initialization. When configured as an option during SDK initialization, These global values will be used as defaults on the operations that use them. When such operations are called, there is a place in each to override the global value, if needed.

For example, you can set `chainId` to `43114` at SDK initialization and then you do not have to pass the same value on calls to operations like getBlock. But if you want to do so you may, which will locally override the global setting. See the example code below for a demonstration.

### Available Globals

The following global parameters are available.

| Name      | Type                          | Required | Description                                              |
| :-------- | :---------------------------- | :------- | :------------------------------------------------------- |
| `chainId` | string                        | No       | A supported EVM chain id, chain alias, or blockchain id. |
| `network` | components.GlobalParamNetwork | No       | A supported network type, either mainnet or a testnet.   |

Example

```javascript
import { Avalanche } from "@avalanche-sdk/chainkit";

const avalancheSDK = new Avalanche({
  apiKey: "<YOUR_API_KEY_HERE>",
  chainId: "43114", // Sets chainId globally, will be used if not passed during method call.
  network: "mainnet",
});

async function run() {
  const result = await avalancheSDK.data.evm.blocks.get({
    blockId:
      "0x17533aeb5193378b9ff441d61728e7a2ebaf10f61fd5310759451627dfca2e7c",
    chainId: "<YOUR_CHAIN_ID>", // Override the globally set chain id.
  });

  // Handle the result
  console.log(result);
}

run();
```

# Pagination (/docs/tooling/avalanche-sdk/chainkit/pagination)

---
title: Pagination
description: Pagination for the ChainKit SDK
icon: StickyNote
---
Some of the endpoints in this SDK support pagination. To use pagination, you make your SDK calls as usual, but the returned response object will also be an async iterable that can be consumed using the `for await...of` syntax.

Here's an example of one such pagination call:

```javascript
import { Avalanche } from "@avalanche-sdk/chainkit";

const avalancheSDK = new Avalanche({
  apiKey: "<YOUR_API_KEY_HERE>",
  chainId: "43114",
  network: "mainnet",
});

async function run() {
  const result = await avalancheSDK.metrics.chains.list({
    network: "mainnet",
  });

  for await (const page of result) {
    // Handle the page
    console.log(page);
  }
}

run();
```

# Retries (/docs/tooling/avalanche-sdk/chainkit/retries)

---
title: Retries
description: Retries for the ChainKit SDK
icon: RotateCcw
---
Some of the endpoints in this SDK support retries. If you use the SDK without any configuration, it will fall back to the default retry strategy provided by the API. However, the default retry strategy can be overridden on a per-operation basis, or across the entire SDK.

To change the default retry strategy for a single API call, simply provide a retryConfig object to the call:

```javascript
import { Avalanche } from "@avalanche-sdk/chainkit";

const avalancheSDK = new Avalanche({
  apiKey: "<YOUR_API_KEY_HERE>",
  chainId: "43114",
  network: "mainnet",
});

async function run() {
  const result = await avalancheSDK.metrics.healthCheck({
    retries: {
      strategy: "backoff",
      backoff: {
        initialInterval: 1,
        maxInterval: 50,
        exponent: 1.1,
        maxElapsedTime: 100,
      },
      retryConnectionErrors: false,
    },
  });

  // Handle the result
  console.log(result);
}

run();
```

If you'd like to override the default retry strategy for all operations that support retries, you can provide a retryConfig at SDK initialization:

```javascript
import { Avalanche } from "@avalanche-sdk/chainkit";

const avalancheSDK = new Avalanche({
  retryConfig: {
    strategy: "backoff",
    backoff: {
      initialInterval: 1,
      maxInterval: 50,
      exponent: 1.1,
      maxElapsedTime: 100,
    },
    retryConnectionErrors: false,
  },
  apiKey: "<YOUR_API_KEY_HERE>",
  chainId: "43114",
  network: "mainnet",
});

async function run() {
  const result = await avalancheSDK.metrics.healthCheck();

  // Handle the result
  console.log(result);
}

run();
```

# Getting Started (/docs/tooling/avalanche-sdk/client/getting-started)

---
title: Getting Started
description: Getting Started with the Client SDK
icon: Rocket
---

### Client SDK

The main Avalanche client SDK for interacting with Avalanche nodes and building blockchain applications.

Features:

* Complete API coverage for P-Chain, X-Chain, and C-Chain.
* Full viem compatibility - anything you can do with viem works here.
* TypeScript-first design with full type safety.
* Abstractions over the JSON-RPC API to make your life easier.
* Wallet integration and transaction management.
* First-class APIs for interacting with Smart Contracts.
* Retrieve balances and UTXOs for addresses..
* Build, sign, and issue transactions to any chain.
* Perform cross-chain transfers between X, P and C chains.
* Add validators and delegators.
* Create subnets and blockchains, convert subnets to L1s.

The SDK is currently available in TypeScript, with more languages coming soon. If you are interested in a language that is not listed, please reach out to us in the [#dev-tools](https://discord.com/channels/578992315641626624/1280920394236297257) channel in the [Avalanche Discord](https://discord.gg/avax).

<Cards>
  <Card title="NPM Package">
    [https://www.npmjs.com/package/@avalanche-sdk/client](https://www.npmjs.com/package/@avalanche-sdk/client)
  </Card>
   <Card title="GitHub Repository">
    [https://github.com/ava-labs/avalanche-sdk-typescript](https://github.com/ava-labs/avalanche-sdk-typescript)
  </Card>
</Cards>

### SDK Installation

<Tabs items={['npm', 'pnpm', 'bun', 'yarn']}>
  <Tab value="npm">
  ```bash
  npm add @avalanche-sdk/client
  ```

  </Tab>
  <Tab value="pnpm">
  ```bash
  pnpm add @avalanche-sdk/client
  ```

  </Tab>
  <Tab value="bun">
  ```bash
  bun add @avalanche-sdk/client
  ```

  </Tab>
  <Tab value="yarn">
  ```bash
  yarn add @avalanche-sdk/client zod
  ```
  <Callout title="Note">
  Yarn does not install peer dependencies automatically. You will need
  to install zod as shown above.
  </Callout>

  </Tab>
</Tabs>

### SDK Example Usage

```javascript
import { createAvalancheClient } from '@avalanche-sdk/client'
import { avalanche } from '@avalanche-sdk/client/chains'

const client = createAvalancheClient({
  chain: avalanche,
  transport: {
    type: "http"
  }
})

// Get account balance
const balance = await client.getBalance({ 
  address: '0xA0Cf798816D4b9b9866b5330EEa46a18382f251e',
})

```

Refer to the code samples provided for each route to see examples of how to use them in the SDK. Explore routes here [Data API](/docs/api-reference/data-api/getting-started),
[Metrics API](/docs/api-reference/metrics-api/getting-started) & [Webhooks API](/docs/api-reference/webhook-api/getting-started).

# Getting Started (/docs/tooling/avalanche-sdk/interchain/getting-started)

---
title: Getting Started
description: Getting Started with the Interchain SDK
icon: Rocket
---

### Interchain SDK

Interchain SDK
The Interchain SDK is a TypeScript SDK for interacting with the Interchain Messaging Protocol (ICM) and Teleporter on Avalanche.


Features:

* Type-safe ICM client for sending cross-chain messages
* Works seamlessly with wallet clients
* Built-in support for Avalanche C-Chain and custom subnets
* Built-in support for Avalanche C-Chain and custom subnets

The SDK is currently available in TypeScript, with more languages coming soon. If you are interested in a language that is not listed, please reach out to us in the [#dev-tools](https://discord.com/channels/578992315641626624/1280920394236297257) channel in the [Avalanche Discord](https://discord.gg/avax).

<Cards>
  <Card title="NPM Package">
    [https://www.npmjs.com/package/@avalanche-sdk/interchain](https://www.npmjs.com/package/@avalanche-sdk/interchain)
  </Card>
   <Card title="GitHub Repository">
    [https://github.com/ava-labs/avalanche-sdk-typescript](https://github.com/ava-labs/avalanche-sdk-typescript)
  </Card>
</Cards>

### SDK Installation

<Tabs items={['npm', 'pnpm', 'bun', 'yarn']}>
  <Tab value="npm">
  ```bash
  npm add @avalanche-sdk/interchain
  ```

  </Tab>
  <Tab value="pnpm">
  ```bash
  pnpm add @avalanche-sdk/interchain
  ```

  </Tab>
  <Tab value="bun">
  ```bash
  bun add @avalanche-sdk/interchain
  ```

  </Tab>
  <Tab value="yarn">
  ```bash
  yarn add @avalanche-sdk/interchain zod
  ```
  <Callout title="Note">
  Yarn does not install peer dependencies automatically. You will need
  to install zod as shown above.
  </Callout>

  </Tab>
</Tabs>

### SDK Example Usage

```javascript
import { createWalletClient, http } from "viem";
import { createICMClient } from "@avalanche-sdk/interchain";
import { privateKeyToAccount } from "viem/accounts";
import * as dotenv from 'dotenv';

// Load environment variables
dotenv.config();

// these will be made available in a separate SDK soon
import { avalancheFuji, dispatch } from "@avalanche-sdk/interchain/chains";

// Get private key from environment
const privateKey = process.env.PRIVATE_KEY;
if (!privateKey) {
  throw new Error("PRIVATE_KEY not found in environment variables");
}

// Load your signer/account
const account = privateKeyToAccount(privateKey as `0x${string}`);

// Create a viem wallet client connected to Avalanche Fuji
const wallet = createWalletClient({
  transport: http('https://api.avax-test.network/ext/bc/C/rpc'),
  account,
});

// Initialize the ICM client
const icmClient = createICMClient(wallet);

// Send a message across chains
async function main() {
  try {
    const hash = await icmClient.sendMsg({
      sourceChain: avalancheFuji,
      destinationChain: dispatch,
      message: 'Hello from Avalanche Fuji to Dispatch Fuji!',
    });
    console.log('Message sent with hash:', hash);
  } catch (error) {
    console.error('Error sending message:', error);
    process.exit(1);
  }
}

main();

```

Refer to the code samples provided for each route to see examples of how to use them in the SDK. Explore routes here [Data API](/docs/api-reference/data-api/getting-started),
[Metrics API](/docs/api-reference/metrics-api/getting-started) & [Webhooks API](/docs/api-reference/webhook-api/getting-started).

# avax.getAtomicTx (/docs/rpcs/c-chain/avalanche/avax_getAtomicTx)

---
title: avax.getAtomicTx
full: true
_openapi:
  method: POST
  route: /ext/bc/C/avax#avax.getAtomicTx
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Returns the specified atomic transaction.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Returns the specified atomic transaction.

<APIPage document={"./public/openapi/coreth.yaml"} operations={[{"path":"/ext/bc/C/avax#avax.getAtomicTx","method":"post"}]} webhooks={[]} hasHead={false} />

# avax.getAtomicTxStatus (/docs/rpcs/c-chain/avalanche/avax_getAtomicTxStatus)

---
title: avax.getAtomicTxStatus
full: true
_openapi:
  method: POST
  route: /ext/bc/C/avax#avax.getAtomicTxStatus
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Returns the status of the specified atomic transaction.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Returns the status of the specified atomic transaction.

<APIPage document={"./public/openapi/coreth.yaml"} operations={[{"path":"/ext/bc/C/avax#avax.getAtomicTxStatus","method":"post"}]} webhooks={[]} hasHead={false} />

# avax.getUTXOs (/docs/rpcs/c-chain/avalanche/avax_getUTXOs)

---
title: avax.getUTXOs
full: true
_openapi:
  method: POST
  route: /ext/bc/C/avax#avax.getUTXOs
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Gets all UTXOs for the specified addresses.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Gets all UTXOs for the specified addresses.

<APIPage document={"./public/openapi/coreth.yaml"} operations={[{"path":"/ext/bc/C/avax#avax.getUTXOs","method":"post"}]} webhooks={[]} hasHead={false} />

# avax.issueTx (/docs/rpcs/c-chain/avalanche/avax_issueTx)

---
title: avax.issueTx
full: true
_openapi:
  method: POST
  route: /ext/bc/C/avax#avax.issueTx
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Issues a transaction to the network.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Issues a transaction to the network.

<APIPage document={"./public/openapi/coreth.yaml"} operations={[{"path":"/ext/bc/C/avax#avax.issueTx","method":"post"}]} webhooks={[]} hasHead={false} />

# eth_suggestPriceOptions (/docs/rpcs/c-chain/avalanche/eth_suggestPriceOptions)

---
title: eth_suggestPriceOptions
full: true
_openapi:
  method: POST
  route: /ext/bc/C/rpc#eth_suggestPriceOptions
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Returns suggested fee options (Coreth extension).
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Returns suggested fee options (Coreth extension).

<APIPage document={"./public/openapi/coreth.yaml"} operations={[{"path":"/ext/bc/C/rpc#eth_suggestPriceOptions","method":"post"}]} webhooks={[]} hasHead={false} />

# debug_getRawBlock (/docs/rpcs/c-chain/debug/debug_getRawBlock)

---
title: debug_getRawBlock
full: true
_openapi:
  method: POST
  route: /ext/bc/C/rpc#debug_getRawBlock
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >
          Returns RLP-encoded bytes of a single block by number or hash.


          **⚠️ Note:** This method is NOT available on public RPC endpoints. You
          must run your own node or use a dedicated node service to access debug
          methods.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Returns RLP-encoded bytes of a single block by number or hash.

**⚠️ Note:** This method is NOT available on public RPC endpoints. You must run your own node or use a dedicated node service to access debug methods.


<APIPage document={"./public/openapi/coreth.yaml"} operations={[{"path":"/ext/bc/C/rpc#debug_getRawBlock","method":"post"}]} webhooks={[]} hasHead={false} />

# debug_getRawTransaction (/docs/rpcs/c-chain/debug/debug_getRawTransaction)

---
title: debug_getRawTransaction
full: true
_openapi:
  method: POST
  route: /ext/bc/C/rpc#debug_getRawTransaction
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >
          Returns the bytes of the transaction for the given hash.


          **⚠️ Note:** This method is NOT available on public RPC endpoints. You
          must run your own node or use a dedicated node service to access debug
          methods.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Returns the bytes of the transaction for the given hash.

**⚠️ Note:** This method is NOT available on public RPC endpoints. You must run your own node or use a dedicated node service to access debug methods.


<APIPage document={"./public/openapi/coreth.yaml"} operations={[{"path":"/ext/bc/C/rpc#debug_getRawTransaction","method":"post"}]} webhooks={[]} hasHead={false} />

# eth_accounts (/docs/rpcs/c-chain/eth/eth_accounts)

---
title: eth_accounts
full: true
_openapi:
  method: POST
  route: /ext/bc/C/rpc#eth_accounts
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >
          Returns a list of addresses owned by the client.


          **Note:** Public RPC endpoints will return an empty array as they
          don't manage any accounts. This method only returns accounts when
          using a node you control with unlocked accounts.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Returns a list of addresses owned by the client.

**Note:** Public RPC endpoints will return an empty array as they don't manage any accounts. This method only returns accounts when using a node you control with unlocked accounts.


<APIPage document={"./public/openapi/coreth.yaml"} operations={[{"path":"/ext/bc/C/rpc#eth_accounts","method":"post"}]} webhooks={[]} hasHead={false} />

# eth_blockNumber (/docs/rpcs/c-chain/eth/eth_blockNumber)

---
title: eth_blockNumber
full: true
_openapi:
  method: POST
  route: /ext/bc/C/rpc#eth_blockNumber
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Returns the block number of the chain head.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Returns the block number of the chain head.

<APIPage document={"./public/openapi/coreth.yaml"} operations={[{"path":"/ext/bc/C/rpc#eth_blockNumber","method":"post"}]} webhooks={[]} hasHead={false} />

# eth_call (/docs/rpcs/c-chain/eth/eth_call)

---
title: eth_call
full: true
_openapi:
  method: POST
  route: /ext/bc/C/rpc#eth_call
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Executes a call without sending a transaction.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Executes a call without sending a transaction.

<APIPage document={"./public/openapi/coreth.yaml"} operations={[{"path":"/ext/bc/C/rpc#eth_call","method":"post"}]} webhooks={[]} hasHead={false} />

# eth_chainId (/docs/rpcs/c-chain/eth/eth_chainId)

---
title: eth_chainId
full: true
_openapi:
  method: POST
  route: /ext/bc/C/rpc#eth_chainId
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Returns the chain ID of the current network.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Returns the chain ID of the current network.

<APIPage document={"./public/openapi/coreth.yaml"} operations={[{"path":"/ext/bc/C/rpc#eth_chainId","method":"post"}]} webhooks={[]} hasHead={false} />

# eth_coinbase (/docs/rpcs/c-chain/eth/eth_coinbase)

---
title: eth_coinbase
full: true
_openapi:
  method: POST
  route: /ext/bc/C/rpc#eth_coinbase
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >
          Returns the client coinbase address.


          **Note:** On public RPC endpoints, this returns the node operator's
          coinbase address, not yours. This method is mainly useful when running
          your own node.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Returns the client coinbase address.

**Note:** On public RPC endpoints, this returns the node operator's coinbase address, not yours. This method is mainly useful when running your own node.


<APIPage document={"./public/openapi/coreth.yaml"} operations={[{"path":"/ext/bc/C/rpc#eth_coinbase","method":"post"}]} webhooks={[]} hasHead={false} />

# eth_estimateGas (/docs/rpcs/c-chain/eth/eth_estimateGas)

---
title: eth_estimateGas
full: true
_openapi:
  method: POST
  route: /ext/bc/C/rpc#eth_estimateGas
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Returns the lowest gas limit for a transaction to succeed.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Returns the lowest gas limit for a transaction to succeed.

<APIPage document={"./public/openapi/coreth.yaml"} operations={[{"path":"/ext/bc/C/rpc#eth_estimateGas","method":"post"}]} webhooks={[]} hasHead={false} />

# eth_feeHistory (/docs/rpcs/c-chain/eth/eth_feeHistory)

---
title: eth_feeHistory
full: true
_openapi:
  method: POST
  route: /ext/bc/C/rpc#eth_feeHistory
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Returns the fee market history.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Returns the fee market history.

<APIPage document={"./public/openapi/coreth.yaml"} operations={[{"path":"/ext/bc/C/rpc#eth_feeHistory","method":"post"}]} webhooks={[]} hasHead={false} />

# eth_gasPrice (/docs/rpcs/c-chain/eth/eth_gasPrice)

---
title: eth_gasPrice
full: true
_openapi:
  method: POST
  route: /ext/bc/C/rpc#eth_gasPrice
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Returns a suggestion for a legacy gas price.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Returns a suggestion for a legacy gas price.

<APIPage document={"./public/openapi/coreth.yaml"} operations={[{"path":"/ext/bc/C/rpc#eth_gasPrice","method":"post"}]} webhooks={[]} hasHead={false} />

# eth_getBalance (/docs/rpcs/c-chain/eth/eth_getBalance)

---
title: eth_getBalance
full: true
_openapi:
  method: POST
  route: /ext/bc/C/rpc#eth_getBalance
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Returns the balance of the account of given address.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Returns the balance of the account of given address.

<APIPage document={"./public/openapi/coreth.yaml"} operations={[{"path":"/ext/bc/C/rpc#eth_getBalance","method":"post"}]} webhooks={[]} hasHead={false} />

# eth_getBlockByHash (/docs/rpcs/c-chain/eth/eth_getBlockByHash)

---
title: eth_getBlockByHash
full: true
_openapi:
  method: POST
  route: /ext/bc/C/rpc#eth_getBlockByHash
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Returns the block for a given hash. Second param selects full
          transactions.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Returns the block for a given hash. Second param selects full transactions.

<APIPage document={"./public/openapi/coreth.yaml"} operations={[{"path":"/ext/bc/C/rpc#eth_getBlockByHash","method":"post"}]} webhooks={[]} hasHead={false} />

# eth_getBlockByNumber (/docs/rpcs/c-chain/eth/eth_getBlockByNumber)

---
title: eth_getBlockByNumber
full: true
_openapi:
  method: POST
  route: /ext/bc/C/rpc#eth_getBlockByNumber
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Returns the block for a given number. Second param selects full
          transactions.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Returns the block for a given number. Second param selects full transactions.

<APIPage document={"./public/openapi/coreth.yaml"} operations={[{"path":"/ext/bc/C/rpc#eth_getBlockByNumber","method":"post"}]} webhooks={[]} hasHead={false} />

# eth_getBlockTransactionCountByHash (/docs/rpcs/c-chain/eth/eth_getBlockTransactionCountByHash)

---
title: eth_getBlockTransactionCountByHash
full: true
_openapi:
  method: POST
  route: /ext/bc/C/rpc#eth_getBlockTransactionCountByHash
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Returns the number of transactions in a block from a block matching
          the given block hash.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Returns the number of transactions in a block from a block matching the given block hash.

<APIPage document={"./public/openapi/coreth.yaml"} operations={[{"path":"/ext/bc/C/rpc#eth_getBlockTransactionCountByHash","method":"post"}]} webhooks={[]} hasHead={false} />

# eth_getBlockTransactionCountByNumber (/docs/rpcs/c-chain/eth/eth_getBlockTransactionCountByNumber)

---
title: eth_getBlockTransactionCountByNumber
full: true
_openapi:
  method: POST
  route: /ext/bc/C/rpc#eth_getBlockTransactionCountByNumber
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Returns the number of transactions in a block matching the given block
          number.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Returns the number of transactions in a block matching the given block number.

<APIPage document={"./public/openapi/coreth.yaml"} operations={[{"path":"/ext/bc/C/rpc#eth_getBlockTransactionCountByNumber","method":"post"}]} webhooks={[]} hasHead={false} />

# eth_getCode (/docs/rpcs/c-chain/eth/eth_getCode)

---
title: eth_getCode
full: true
_openapi:
  method: POST
  route: /ext/bc/C/rpc#eth_getCode
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Returns code at a given address.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Returns code at a given address.

<APIPage document={"./public/openapi/coreth.yaml"} operations={[{"path":"/ext/bc/C/rpc#eth_getCode","method":"post"}]} webhooks={[]} hasHead={false} />

# eth_getFilterChanges (/docs/rpcs/c-chain/eth/eth_getFilterChanges)

---
title: eth_getFilterChanges
full: true
_openapi:
  method: POST
  route: /ext/bc/C/rpc#eth_getFilterChanges
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Polling method for a filter, which returns an array of logs which
          occurred since last poll.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Polling method for a filter, which returns an array of logs which occurred since last poll.

<APIPage document={"./public/openapi/coreth.yaml"} operations={[{"path":"/ext/bc/C/rpc#eth_getFilterChanges","method":"post"}]} webhooks={[]} hasHead={false} />

# eth_getFilterLogs (/docs/rpcs/c-chain/eth/eth_getFilterLogs)

---
title: eth_getFilterLogs
full: true
_openapi:
  method: POST
  route: /ext/bc/C/rpc#eth_getFilterLogs
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Returns an array of all logs matching filter with given id.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Returns an array of all logs matching filter with given id.

<APIPage document={"./public/openapi/coreth.yaml"} operations={[{"path":"/ext/bc/C/rpc#eth_getFilterLogs","method":"post"}]} webhooks={[]} hasHead={false} />

# eth_getLogs (/docs/rpcs/c-chain/eth/eth_getLogs)

---
title: eth_getLogs
full: true
_openapi:
  method: POST
  route: /ext/bc/C/rpc#eth_getLogs
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Returns logs matching the given filter object.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Returns logs matching the given filter object.

<APIPage document={"./public/openapi/coreth.yaml"} operations={[{"path":"/ext/bc/C/rpc#eth_getLogs","method":"post"}]} webhooks={[]} hasHead={false} />

# eth_getStorageAt (/docs/rpcs/c-chain/eth/eth_getStorageAt)

---
title: eth_getStorageAt
full: true
_openapi:
  method: POST
  route: /ext/bc/C/rpc#eth_getStorageAt
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Returns the value from a storage position at a given address.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Returns the value from a storage position at a given address.

<APIPage document={"./public/openapi/coreth.yaml"} operations={[{"path":"/ext/bc/C/rpc#eth_getStorageAt","method":"post"}]} webhooks={[]} hasHead={false} />

# eth_getTransactionByBlockHashAndIndex (/docs/rpcs/c-chain/eth/eth_getTransactionByBlockHashAndIndex)

---
title: eth_getTransactionByBlockHashAndIndex
full: true
_openapi:
  method: POST
  route: /ext/bc/C/rpc#eth_getTransactionByBlockHashAndIndex
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Returns information about a transaction by block hash and transaction
          index position.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Returns information about a transaction by block hash and transaction index position.

<APIPage document={"./public/openapi/coreth.yaml"} operations={[{"path":"/ext/bc/C/rpc#eth_getTransactionByBlockHashAndIndex","method":"post"}]} webhooks={[]} hasHead={false} />

# eth_getTransactionByBlockNumberAndIndex (/docs/rpcs/c-chain/eth/eth_getTransactionByBlockNumberAndIndex)

---
title: eth_getTransactionByBlockNumberAndIndex
full: true
_openapi:
  method: POST
  route: /ext/bc/C/rpc#eth_getTransactionByBlockNumberAndIndex
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Returns information about a transaction by block number and
          transaction index position.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Returns information about a transaction by block number and transaction index position.

<APIPage document={"./public/openapi/coreth.yaml"} operations={[{"path":"/ext/bc/C/rpc#eth_getTransactionByBlockNumberAndIndex","method":"post"}]} webhooks={[]} hasHead={false} />

# eth_getTransactionByHash (/docs/rpcs/c-chain/eth/eth_getTransactionByHash)

---
title: eth_getTransactionByHash
full: true
_openapi:
  method: POST
  route: /ext/bc/C/rpc#eth_getTransactionByHash
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Returns the information about a transaction requested by transaction
          hash.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Returns the information about a transaction requested by transaction hash.

<APIPage document={"./public/openapi/coreth.yaml"} operations={[{"path":"/ext/bc/C/rpc#eth_getTransactionByHash","method":"post"}]} webhooks={[]} hasHead={false} />

# eth_getTransactionCount (/docs/rpcs/c-chain/eth/eth_getTransactionCount)

---
title: eth_getTransactionCount
full: true
_openapi:
  method: POST
  route: /ext/bc/C/rpc#eth_getTransactionCount
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Returns the number of transactions sent from an address.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Returns the number of transactions sent from an address.

<APIPage document={"./public/openapi/coreth.yaml"} operations={[{"path":"/ext/bc/C/rpc#eth_getTransactionCount","method":"post"}]} webhooks={[]} hasHead={false} />

# eth_getTransactionReceipt (/docs/rpcs/c-chain/eth/eth_getTransactionReceipt)

---
title: eth_getTransactionReceipt
full: true
_openapi:
  method: POST
  route: /ext/bc/C/rpc#eth_getTransactionReceipt
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Returns the receipt of a transaction by transaction hash.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Returns the receipt of a transaction by transaction hash.

<APIPage document={"./public/openapi/coreth.yaml"} operations={[{"path":"/ext/bc/C/rpc#eth_getTransactionReceipt","method":"post"}]} webhooks={[]} hasHead={false} />

# eth_maxPriorityFeePerGas (/docs/rpcs/c-chain/eth/eth_maxPriorityFeePerGas)

---
title: eth_maxPriorityFeePerGas
full: true
_openapi:
  method: POST
  route: /ext/bc/C/rpc#eth_maxPriorityFeePerGas
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Returns a suggestion for a tip cap for dynamic fee transactions.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Returns a suggestion for a tip cap for dynamic fee transactions.

<APIPage document={"./public/openapi/coreth.yaml"} operations={[{"path":"/ext/bc/C/rpc#eth_maxPriorityFeePerGas","method":"post"}]} webhooks={[]} hasHead={false} />

# eth_newBlockFilter (/docs/rpcs/c-chain/eth/eth_newBlockFilter)

---
title: eth_newBlockFilter
full: true
_openapi:
  method: POST
  route: /ext/bc/C/rpc#eth_newBlockFilter
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >
          Creates a filter in the node, to notify when a new block arrives.


          **⚠️ Note:** Filter methods may not be available or may have limited
          functionality on public RPC endpoints as they require server-side
          state management.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Creates a filter in the node, to notify when a new block arrives.

**⚠️ Note:** Filter methods may not be available or may have limited functionality on public RPC endpoints as they require server-side state management.


<APIPage document={"./public/openapi/coreth.yaml"} operations={[{"path":"/ext/bc/C/rpc#eth_newBlockFilter","method":"post"}]} webhooks={[]} hasHead={false} />

# eth_newFilter (/docs/rpcs/c-chain/eth/eth_newFilter)

---
title: eth_newFilter
full: true
_openapi:
  method: POST
  route: /ext/bc/C/rpc#eth_newFilter
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >
          Creates a filter object, based on filter options, to notify when the
          state changes (logs).


          **⚠️ Note:** Filter methods may not be available or may have limited
          functionality on public RPC endpoints as they require server-side
          state management.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Creates a filter object, based on filter options, to notify when the state changes (logs).

**⚠️ Note:** Filter methods may not be available or may have limited functionality on public RPC endpoints as they require server-side state management.


<APIPage document={"./public/openapi/coreth.yaml"} operations={[{"path":"/ext/bc/C/rpc#eth_newFilter","method":"post"}]} webhooks={[]} hasHead={false} />

# eth_newPendingTransactionFilter (/docs/rpcs/c-chain/eth/eth_newPendingTransactionFilter)

---
title: eth_newPendingTransactionFilter
full: true
_openapi:
  method: POST
  route: /ext/bc/C/rpc#eth_newPendingTransactionFilter
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >
          Creates a filter in the node, to notify when new pending transactions
          arrive.


          **⚠️ Note:** Filter methods may not be available or may have limited
          functionality on public RPC endpoints as they require server-side
          state management.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Creates a filter in the node, to notify when new pending transactions arrive.

**⚠️ Note:** Filter methods may not be available or may have limited functionality on public RPC endpoints as they require server-side state management.


<APIPage document={"./public/openapi/coreth.yaml"} operations={[{"path":"/ext/bc/C/rpc#eth_newPendingTransactionFilter","method":"post"}]} webhooks={[]} hasHead={false} />

# eth_protocolVersion (/docs/rpcs/c-chain/eth/eth_protocolVersion)

---
title: eth_protocolVersion
full: true
_openapi:
  method: POST
  route: /ext/bc/C/rpc#eth_protocolVersion
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Returns the current ethereum protocol version.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Returns the current ethereum protocol version.

<APIPage document={"./public/openapi/coreth.yaml"} operations={[{"path":"/ext/bc/C/rpc#eth_protocolVersion","method":"post"}]} webhooks={[]} hasHead={false} />

# eth_sendRawTransaction (/docs/rpcs/c-chain/eth/eth_sendRawTransaction)

---
title: eth_sendRawTransaction
full: true
_openapi:
  method: POST
  route: /ext/bc/C/rpc#eth_sendRawTransaction
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Submits a signed raw transaction.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Submits a signed raw transaction.

<APIPage document={"./public/openapi/coreth.yaml"} operations={[{"path":"/ext/bc/C/rpc#eth_sendRawTransaction","method":"post"}]} webhooks={[]} hasHead={false} />

# eth_sign (/docs/rpcs/c-chain/eth/eth_sign)

---
title: eth_sign
full: true
_openapi:
  method: POST
  route: /ext/bc/C/rpc#eth_sign
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >
          Signs data with a given address.


          **⚠️ Security Note:** This method is typically disabled on public RPC
          endpoints for security reasons. It requires access to private keys and
          should only be used on nodes you control.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Signs data with a given address.

**⚠️ Security Note:** This method is typically disabled on public RPC endpoints for security reasons. It requires access to private keys and should only be used on nodes you control.


<APIPage document={"./public/openapi/coreth.yaml"} operations={[{"path":"/ext/bc/C/rpc#eth_sign","method":"post"}]} webhooks={[]} hasHead={false} />

# eth_uninstallFilter (/docs/rpcs/c-chain/eth/eth_uninstallFilter)

---
title: eth_uninstallFilter
full: true
_openapi:
  method: POST
  route: /ext/bc/C/rpc#eth_uninstallFilter
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Uninstalls a filter with given id.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Uninstalls a filter with given id.

<APIPage document={"./public/openapi/coreth.yaml"} operations={[{"path":"/ext/bc/C/rpc#eth_uninstallFilter","method":"post"}]} webhooks={[]} hasHead={false} />

# net_version (/docs/rpcs/c-chain/net/net_version)

---
title: net_version
full: true
_openapi:
  method: POST
  route: /ext/bc/C/rpc#net_version
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Returns the current network ID as a string.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Returns the current network ID as a string.

<APIPage document={"./public/openapi/coreth.yaml"} operations={[{"path":"/ext/bc/C/rpc#net_version","method":"post"}]} webhooks={[]} hasHead={false} />

# personal_newAccount (/docs/rpcs/c-chain/personal/personal_newAccount)

---
title: personal_newAccount
full: true
_openapi:
  method: POST
  route: /ext/bc/C/rpc#personal_newAccount
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >
          Creates a new account with the given password.


          **⚠️ Security Note:** This method is NOT available on public RPC
          endpoints for security reasons. Personal methods manage private keys
          and must only be used on nodes you control.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Creates a new account with the given password.

**⚠️ Security Note:** This method is NOT available on public RPC endpoints for security reasons. Personal methods manage private keys and must only be used on nodes you control.


<APIPage document={"./public/openapi/coreth.yaml"} operations={[{"path":"/ext/bc/C/rpc#personal_newAccount","method":"post"}]} webhooks={[]} hasHead={false} />

# personal_unlockAccount (/docs/rpcs/c-chain/personal/personal_unlockAccount)

---
title: personal_unlockAccount
full: true
_openapi:
  method: POST
  route: /ext/bc/C/rpc#personal_unlockAccount
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >
          Unlocks an account with the given password and optional duration.


          **⚠️ Security Note:** This method is NOT available on public RPC
          endpoints for security reasons. Personal methods manage private keys
          and must only be used on nodes you control.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Unlocks an account with the given password and optional duration.

**⚠️ Security Note:** This method is NOT available on public RPC endpoints for security reasons. Personal methods manage private keys and must only be used on nodes you control.


<APIPage document={"./public/openapi/coreth.yaml"} operations={[{"path":"/ext/bc/C/rpc#personal_unlockAccount","method":"post"}]} webhooks={[]} hasHead={false} />

# txpool_status (/docs/rpcs/c-chain/txpool/txpool_status)

---
title: txpool_status
full: true
_openapi:
  method: POST
  route: /ext/bc/C/rpc#txpool_status
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >
          Returns transaction pool status.


          **⚠️ Note:** This method may be restricted or rate-limited on public
          RPC endpoints. Consider running your own node for unrestricted access.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Returns transaction pool status.

**⚠️ Note:** This method may be restricted or rate-limited on public RPC endpoints. Consider running your own node for unrestricted access.


<APIPage document={"./public/openapi/coreth.yaml"} operations={[{"path":"/ext/bc/C/rpc#txpool_status","method":"post"}]} webhooks={[]} hasHead={false} />

# web3_clientVersion (/docs/rpcs/c-chain/web3/web3_clientVersion)

---
title: web3_clientVersion
full: true
_openapi:
  method: POST
  route: /ext/bc/C/rpc#web3_clientVersion
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Returns the client version.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Returns the client version.

<APIPage document={"./public/openapi/coreth.yaml"} operations={[{"path":"/ext/bc/C/rpc#web3_clientVersion","method":"post"}]} webhooks={[]} hasHead={false} />

# Banff Changes (/docs/rpcs/other/guides/banff-changes)

---
title: Banff Changes
description: This document specifies the changes in Avalanche “Banff”, which was released in AvalancheGo v1.9.x.
---
Block Changes[​](#block-changes "Direct link to heading")
---------------------------------------------------------

### Apricot[​](#apricot "Direct link to heading")

Apricot allows the following block types with the following content:

- _Standard Blocks_ may contain multiple transactions of the following types:
    - CreateChainTx
    - CreateSubnetTx
    - ImportTx
    - ExportTx
- _Proposal Blocks_ may contain a single transaction of the following types:
    - AddValidatorTx
    - AddDelegatorTx
    - AddSubnetValidatorTx
    - RewardValidatorTx
    - AdvanceTimeTx
- _Options Blocks_, that is _Commit Block_ and _Abort Block_ do not contain any transactions.

Each block has a header containing:

- ParentID
- Height

### Banff[​](#banff "Direct link to heading")

Banff allows the following block types with the following content:

- _Standard Blocks_ may contain multiple transactions of the following types:
    
    - CreateChainTx
    - CreateSubnetTx
    - ImportTx
    - ExportTx
    - AddValidatorTx
    - AddDelegatorTx
    - AddSubnetValidatorTx
    - _RemoveSubnetValidatorTx_
    - _TransformSubnetTx_
    - _AddPermissionlessValidatorTx_
    - _AddPermissionlessDelegatorTx_
- _Proposal Blocks_ may contain a single transaction of the following types:
    
    - RewardValidatorTx
- _Options blocks_, that is _Commit Block_ and _Abort Block_ do not contain any transactions.
    

Note that each block has an header containing:

- ParentID
- Height
- _Time_

So the two main differences with respect to Apricot are:

- _AddValidatorTx_, _AddDelegatorTx_, _AddSubnetValidatorTx_ are included into Standard Blocks rather than Proposal Blocks so that they don't need to be voted on (that is followed by a Commit/Abort Block).
- New Transaction types: _RemoveSubnetValidatorTx_, _TransformSubnetTx_, _AddPermissionlessValidatorTx_, and _AddPermissionlessDelegatorTx_ have been added into Standard Blocks.
- Block timestamp is explicitly serialized into block header, to allow chain time update.

### New Transactions[​](#new-transactions "Direct link to heading")

#### RemoveSubnetValidatorTx[​](#removesubnetvalidatortx "Direct link to heading")

```
type RemoveSubnetValidatorTx struct {
	BaseTx `serialize:"true"`
	// The node to remove from the Avalanche L1.
	NodeID ids.NodeID `serialize:"true" json:"nodeID"`
	// The Avalanche L1 to remove the node from.
	Subnet ids.ID `serialize:"true" json:"subnet"`
	// Proves that the issuer has the right to remove the node from the Avalanche L1.
SubnetAuth verify.Verifiable `serialize:"true" json:"subnetAuthorization"`
}
```

#### TransformSubnetTx[​](#transformsubnettx "Direct link to heading")

```
type TransformSubnetTx struct {
	// Metadata, inputs and outputs
	BaseTx `serialize:"true"`
	// ID of the Subnet to transform
	// Restrictions:
	// - Must not be the Primary Network ID
	Subnet ids.ID `serialize:"true" json:"subnetID"`
	// Asset to use when staking on the Avalanche L1
	// Restrictions:
	// - Must not be the Empty ID
	// - Must not be the AVAX ID
	AssetID ids.ID `serialize:"true" json:"assetID"`
	// Amount to initially specify as the current supply
	// Restrictions:
	// - Must be > 0
	InitialSupply uint64 `serialize:"true" json:"initialSupply"`
	// Amount to specify as the maximum token supply
	// Restrictions:
	// - Must be >= [InitialSupply]
	MaximumSupply uint64 `serialize:"true" json:"maximumSupply"`
	// MinConsumptionRate is the rate to allocate funds if the validator's stake
	// duration is 0
	MinConsumptionRate uint64 `serialize:"true" json:"minConsumptionRate"`
	// MaxConsumptionRate is the rate to allocate funds if the validator's stake
	// duration is equal to the minting period
	// Restrictions:
	// - Must be >= [MinConsumptionRate]
	// - Must be <= [reward.PercentDenominator]
	MaxConsumptionRate uint64 `serialize:"true" json:"maxConsumptionRate"`
	// MinValidatorStake is the minimum amount of funds required to become a
	// validator.
	// Restrictions:
	// - Must be > 0
	// - Must be <= [InitialSupply]
	MinValidatorStake uint64 `serialize:"true" json:"minValidatorStake"`
	// MaxValidatorStake is the maximum amount of funds a single validator can
	// be allocated, including delegated funds.
	// Restrictions:
	// - Must be >= [MinValidatorStake]
	// - Must be <= [MaximumSupply]
	MaxValidatorStake uint64 `serialize:"true" json:"maxValidatorStake"`
	// MinStakeDuration is the minimum number of seconds a staker can stake for.
	// Restrictions:
	// - Must be > 0
	MinStakeDuration uint32 `serialize:"true" json:"minStakeDuration"`
	// MaxStakeDuration is the maximum number of seconds a staker can stake for.
	// Restrictions:
	// - Must be >= [MinStakeDuration]
	// - Must be <= [GlobalMaxStakeDuration]
	MaxStakeDuration uint32 `serialize:"true" json:"maxStakeDuration"`
	// MinDelegationFee is the minimum percentage a validator must charge a
	// delegator for delegating.
	// Restrictions:
	// - Must be <= [reward.PercentDenominator]
	MinDelegationFee uint32 `serialize:"true" json:"minDelegationFee"`
	// MinDelegatorStake is the minimum amount of funds required to become a
	// delegator.
	// Restrictions:
	// - Must be > 0
	MinDelegatorStake uint64 `serialize:"true" json:"minDelegatorStake"`
	// MaxValidatorWeightFactor is the factor which calculates the maximum
	// amount of delegation a validator can receive.
	// Note: a value of 1 effectively disables delegation.
	// Restrictions:
	// - Must be > 0
	MaxValidatorWeightFactor byte `serialize:"true" json:"maxValidatorWeightFactor"`
	// UptimeRequirement is the minimum percentage a validator must be online
	// and responsive to receive a reward.
	// Restrictions:
	// - Must be <= [reward.PercentDenominator]
	UptimeRequirement uint32 `serialize:"true" json:"uptimeRequirement"`
	// Authorizes this transformation
SubnetAuth verify.Verifiable `serialize:"true" json:"subnetAuthorization"`
}
```

#### AddPermissionlessValidatorTx[​](#addpermissionlessvalidatortx "Direct link to heading")

```
type AddPermissionlessValidatorTx struct {
	// Metadata, inputs and outputs
	BaseTx `serialize:"true"`
	// Describes the validator
	Validator validator.Validator `serialize:"true" json:"validator"`
	// ID of the Avalanche L1 this validator is validating
	Subnet ids.ID `serialize:"true" json:"subnet"`
	// Where to send staked tokens when done validating
	StakeOuts []*avax.TransferableOutput `serialize:"true" json:"stake"`
	// Where to send validation rewards when done validating
	ValidatorRewardsOwner fx.Owner `serialize:"true" json:"validationRewardsOwner"`
	// Where to send delegation rewards when done validating
	DelegatorRewardsOwner fx.Owner `serialize:"true" json:"delegationRewardsOwner"`
	// Fee this validator charges delegators as a percentage, times 10,000
	// For example, if this validator has DelegationShares=300,000 then they
	// take 30% of rewards from delegators
	DelegationShares uint32 `serialize:"true" json:"shares"`
}
```

#### AddPermissionlessDelegatorTx[​](#addpermissionlessdelegatortx "Direct link to heading")

```
type AddPermissionlessDelegatorTx struct {
	// Metadata, inputs and outputs
	BaseTx `serialize:"true"`
	// Describes the validator
	Validator validator.Validator `serialize:"true" json:"validator"`
	// ID of the Avalanche L1 this validator is validating
	Subnet ids.ID `serialize:"true" json:"subnet"`
	// Where to send staked tokens when done validating
	Stake []*avax.TransferableOutput `serialize:"true" json:"stake"`
	// Where to send staking rewards when done validating
	RewardsOwner fx.Owner `serialize:"true" json:"rewardsOwner"`
}
```

#### New TypeIDs[​](#new-typeids "Direct link to heading")

```
ApricotProposalBlock = 0
ApricotAbortBlock = 1
ApricotCommitBlock = 2
ApricotStandardBlock = 3
ApricotAtomicBlock = 4

secp256k1fx.TransferInput = 5
secp256k1fx.MintOutput = 6
secp256k1fx.TransferOutput = 7
secp256k1fx.MintOperation = 8
secp256k1fx.Credential = 9
secp256k1fx.Input = 10
secp256k1fx.OutputOwners = 11

AddValidatorTx = 12
AddSubnetValidatorTx = 13
AddDelegatorTx = 14
CreateChainTx = 15
CreateSubnetTx = 16
ImportTx = 17
ExportTx = 18
AdvanceTimeTx = 19
RewardValidatorTx = 20

stakeable.LockIn = 21
stakeable.LockOut = 22

RemoveSubnetValidatorTx = 23
TransformSubnetTx = 24
AddPermissionlessValidatorTx = 25
AddPermissionlessDelegatorTx = 26

EmptyProofOfPossession = 27
BLSProofOfPossession   = 28

BanffProposalBlock = 29
BanffAbortBlock = 30
BanffCommitBlock = 31
BanffStandardBlock = 32

```



# Flow of a Single Blockchain (/docs/rpcs/other/guides/blockchain-flow)

---
title: Flow of a Single Blockchain
---
![](/images/flow1.png)

Intro[​](#intro "Direct link to heading")
-----------------------------------------

The Avalanche network consists of 3 built-in blockchains: X-Chain, C-Chain, and P-Chain. The X-Chain is used to manage assets and uses the Avalanche consensus protocol. The C-Chain is used to create and interact with smart contracts and uses the Snowman consensus protocol. The P-Chain is used to coordinate validators and stake and also uses the Snowman consensus protocol. At the time of writing, the Avalanche network has ~1200 validators. A set of validators makes up an Avalanche L1. Avalanche L1s can validate 1 or more chains. It is a common misconception that 1 Avalanche L1 = 1 chain and this is shown by the primary Avalanche L1 of Avalanche which is made up of the X-Chain, C-Chain, and P-Chain.

A node in the Avalanche network can either be a validator or a non-validator. A validator stakes AVAX tokens and participates in consensus to earn rewards. A non-validator does not participate in consensus or have any AVAX staked but can be used as an API server. Both validators and non-validators need to have their own copy of the chain and need to know the current state of the network. At the time of writing, there are ~1200 validators and ~1800 non-validators.

Each blockchain on Avalanche has several components: the virtual machine, database, consensus engine, sender, and handler. These components help the chain run smoothly. Blockchains also interact with the P2P layer and the chain router to send and receive messages.

Peer-to-Peer (P2P)[​](#peer-to-peer-p2p "Direct link to heading")
-----------------------------------------------------------------

### Outbound Messages[​](#outbound-messages "Direct link to heading")

[The `OutboundMsgBuilder` interface](https://github.com/ava-labs/avalanchego/blob/master/message/outbound_msg_builder.go) specifies methods that build messages of type `OutboundMessage`. Nodes communicate to other nodes by sending `OutboundMessage` messages.

All messaging functions in `OutboundMsgBuilder` can be categorized as follows:

- **Handshake**
    - Nodes need to be on a certain version before they can be accepted into the network.
- **State Sync**
    - A new node can ask other nodes for the current state of the network. It only syncs the required state for a specific block.
- **Bootstrapping**
    - Nodes can ask other nodes for blocks to build their own copy of the chain. A node can fetch all blocks from the locally last accepted block to the current last accepted block in the network.
- **Consensus**
    - Once a node is up to tip they can participate in consensus! During consensus, a node conducts a poll to several different small random samples of the validator set. They can communicate decisions on whether or not they have accepted/rejected a block.
- **App**
    - VMs communicate application-specific messages to other nodes through app messages. A common example is mempool gossiping.

Currently, AvalancheGo implements its own message serialization to communicate. In the future, AvalancheGo will use protocol buffers to communicate.

### Network[​](#network "Direct link to heading")

[The networking interface](https://github.com/ava-labs/avalanchego/blob/master/network/network.go) is shared across all chains. It implements functions from the `ExternalSender` interface. The two functions it implements are `Send` and `Gossip`. `Send` sends a message of type `OutboundMessage` to a specific set of nodes (specified by an array of `NodeIDs`). `Gossip` sends a message of type `OutboundMessage` to a random group of nodes in an Avalanche L1 (can be a validator or a non-validator). Gossiping is used to push transactions across the network. The networking protocol uses TLS to pass messages between peers.

Along with sending and gossiping, the networking library is also responsible for making connections and maintaining connections. Any node, either a validator or non-validator, will attempt to connect to the primary network.

Router[​](#router "Direct link to heading")
-------------------------------------------

[The `ChainRouter`](https://github.com/ava-labs/avalanchego/blob/master/snow/networking/router/chain_router.go) routes all incoming messages to its respective blockchain using `ChainID`. It does this by pushing all the messages onto the respective Chain handler's queue. The `ChainRouter` references all existing chains on the network such as the X-chain, C-chain, P-chain and possibly any other chain. The `ChainRouter` handles timeouts as well. When sending messages on the P2P layer, timeouts are registered on the sender and cleared on the `ChainRouter` side when a response is received. If no response is received, then it triggers a timeout. Because timeouts are handled on the `ChainRouter` side, the handler is reliable. Timeouts are triggered when peers do not respond and the `ChainRouter` will still notify the handler of failure cases. The timeout manager within `ChainRouter` is also adaptive. If the network is experiencing long latencies, timeouts will then be adjusted as well.

Handler[​](#handler "Direct link to heading")
---------------------------------------------

The main function of [the `Handler`](https://github.com/ava-labs/avalanchego/blob/master/snow/networking/handler/handler.go) is to pass messages from the network to the consensus engine. It receives these messages from the `ChainRouter`. It passes messages by pushing them onto a sync or Async queue (depends on message type). Messages are then popped from the queue, parsed, and routed to the correct function in consensus engine. This can be one of the following.

- **State sync message (sync queue)**
- **Bootstrapping message (sync queue)**
- **Consensus message (sync queue)**
- **App message (Async queue)**

Sender[​](#sender "Direct link to heading")
-------------------------------------------

The main role of [the `sender`](https://github.com/ava-labs/avalanchego/blob/master/snow/networking/sender/sender.go) is to build and send outbound messages. It is actually a very thin wrapper around the normal networking code. The main difference here is that sender registers timeouts and tells the router to expect a response message. The timer starts on the sender side. If there is no response, sender will send a failed response to the router. If a node is repeatedly unresponsive, that node will get benched and the sender will immediately start marking those messages as failed. If a sufficient amount of network deems the node benched, it might not get rewards (as a validator).

Consensus Engine[​](#consensus-engine "Direct link to heading")
---------------------------------------------------------------

Consensus is defined as getting a group of distributed systems to agree on an outcome. In the case of the Avalanche network, consensus is achieved when validators are in agreement with the state of the blockchain. The novel consensus algorithm is documented in the [white paper](https://assets.website-files.com/5d80307810123f5ffbb34d6e/6009805681b416f34dcae012_Avalanche%20Consensus%20Whitepaper.pdf). There are two main consensus algorithms: Avalanche and [Snowman](https://github.com/ava-labs/avalanchego/blob/master/snow/consensus/snowman/consensus.go). The engine is responsible for adding proposing a new block to consensus, repeatedly polling the network for decisions (accept/reject), and communicating that decision to the `Sender`.

Blockchain Creation[​](#blockchain-creation "Direct link to heading")
---------------------------------------------------------------------

[The `Manager`](https://github.com/ava-labs/avalanchego/blob/master/chains/manager.go) is what kick-starts everything in regards to blockchain creation, starting with the P-Chain. Once the P-Chain finishes bootstrapping, it will kickstart C-Chain and X-Chain and any other chains. The `Manager`'s job is not done yet, if a create-chain transaction is seen by a validator, a whole new process to create a chain will be started by the `Manager`. This can happen dynamically, long after the 3 chains in the Primary Network have been created and bootstrapped.


# Issuing API Calls (/docs/rpcs/other/guides/issuing-api-calls)

---
title: Issuing API Calls
description: This guide explains how to make calls to APIs exposed by Avalanche nodes.
---

Endpoints[​](#endpoints "Direct link to heading")
-------------------------------------------------

An API call is made to an endpoint, which is a URL, made up of the base URI which is the address and the port of the node, and the path the particular endpoint the API call is on.

### Base URL[​](#base-url "Direct link to heading")

The base of the URL is always:

`[node-ip]:[http-port]`

where

- `node-ip` is the IP address of the node the call is to.
- `http-port` is the port the node listens on for HTTP calls. This is specified by [command-line argument](/docs/nodes/configure/configs-flags#http-server) `http-port` (default value `9650`).

For example, if you're making RPC calls on the local node, the base URL might look like this: `127.0.0.1:9650`.

If you're making RPC calls to remote nodes, then the instead of `127.0.0.1` you should use the public IP of the server where the node is. Note that by default the node will only accept API calls on the local interface, so you will need to set up the [`http-host`](/docs/nodes/configure/configs-flags#--http-host-string) config flag on the node. Also, you will need to make sure the firewall and/or security policy allows access to the `http-port` from the internet.


<Callout type="warn">
When setting up RPC access to a node, make sure you don't leave the `http-port` accessible to everyone! There are malicious actors that scan for nodes that have unrestricted access to their RPC port and then use those nodes for spamming them with resource-intensive queries which can knock the node offline. Only allow access to your node's RPC port from known IP addresses!
</Callout>
### Endpoint Path[​](#endpoint-path "Direct link to heading")

Each API's documentation specifies what endpoint path a user should make calls to in order to access the API's methods.

In general, they are formatted like:

So for the Admin API, the endpoint path is `/ext/admin`, for the Info API it is `/ext/info` and so on. Note that some APIs have additional path components, most notably the chain RPC endpoints which includes the Avalanche L1 chain RPCs. We'll go over those in detail in the next section.

So, in combining the base URL and the endpoint path we get the complete URL for making RPC calls. For example, to make a local RPC call on the Info API, the full URL would be:

```
http://127.0.0.1:9650/ext/info
```

Primary Network and Avalanche L1 RPC calls[​](#primary-network-and-avalanche-l1-rpc-calls "Direct link to heading")
-------------------------------------------------------------------------------------------------------

Besides the APIs that are local to the node, like Admin or Metrics APIs, nodes also expose endpoints for talking to particular chains that are either part of the Primary Network (the X, P and C chains), or part of any Avalanche L1s the node might be syncing or validating.

In general, chain endpoints are formatted as:

### Primary Network Endpoints[​](#primary-network-endpoints "Direct link to heading")

The Primary Network consists of three chains: X, P and C chain. As those chains are present on every node, there are also convenient aliases defined that can be used instead of the full blockchainIDs. So, the endpoints look like:

### C-Chain and Subnet-EVM Endpoints[​](#c-chain-and-subnet-evm-endpoints "Direct link to heading")

C-Chain and many Avalanche L1s run a version of the EthereumVM (EVM). EVM exposes its own endpoints, which are also accessible on the node: JSON-RPC, and Websocket.

#### JSON-RPC EVM Endpoints[​](#json-rpc-evm-endpoints "Direct link to heading")

To interact with C-Chain EVM via the JSON-RPC use the endpoint:

To interact with Avalanche L1 instances of the EVM via the JSON-RPC endpoint:

```
/ext/bc/[blockchainID]/rpc
```

where `blockchainID` is the ID of the blockchain running the EVM. So for example, the RPC URL for the DFK Network (an Avalanche L1 that runs the DeFi Kingdoms:Crystalvale game) running on a local node would be:

```
http://127.0.0.1/ext/bc/q2aTwKuyzgs8pynF7UXBZCU7DejbZbZ6EUyHr3JQzYgwNPUPi/rpc
```

Or for the WAGMI Avalanche L1 on the Fuji testnet:

```
http://127.0.0.1/ext/bc/2ebCneCbwthjQ1rYT41nhd7M76Hc6YmosMAQrTFhBq8qeqh6tt/rpc
```

#### Websocket EVM Endpoints[​](#websocket-evm-endpoints "Direct link to heading")

To interact with C-Chain via the websocket endpoint, use:

To interact with other instances of the EVM via the websocket endpoint:

where `blockchainID` is the ID of the blockchain running the EVM. For example, to interact with the C-Chain's Ethereum APIs via websocket on localhost you can use:

```
ws://127.0.0.1:9650/ext/bc/C/ws
```


<Callout title="Note">
When using the [Public API](/docs/tooling/rpc-providers) or another host that supports HTTPS, use `https://` or `wss://` instead of `http://` or `ws://`.

Also, note that the [public API](/docs/tooling/rpc-providers#using-the-public-api-nodes) only supports C-Chain websocket API calls for API methods that don't exist on the C-Chain's HTTP API.
</Callout>


Making a JSON RPC Request[​](#making-a-json-rpc-request "Direct link to heading")
---------------------------------------------------------------------------------

Most of the built-in APIs use the [JSON RPC 2.0](https://www.jsonrpc.org/specification) format to describe their requests and responses. Such APIs include the Platform API and the X-Chain API.

Suppose we want to call the `getTxStatus` method of the [X-Chain API](/docs/api-reference/x-chain/api). The X-Chain API documentation tells us that the endpoint for this API is `/ext/bc/X`.

That means that the endpoint we send our API call to is:

`[node-ip]:[http-port]/ext/bc/X`

The X-Chain API documentation tells us that the signature of `getTxStatus` is:

[`avm.getTxStatus`](/docs/api-reference/x-chain/api#avmgettxstatus)`(txID:bytes) -> (status:string)`

where:

- Argument `txID` is the ID of the transaction we're getting the status of.
- Returned value `status` is the status of the transaction in question.

To call this method, then:

```
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :4,
    "method" :"avm.getTxStatus",
    "params" :{
        "txID":"2QouvFWUbjuySRxeX5xMbNCuAaKWfbk5FeEa2JmoF85RKLk2dD"
    }
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/bc/X
```

- `jsonrpc` specifies the version of the JSON RPC protocol. (In practice is always 2.0)
- `method` specifies the service (`avm`) and method (`getTxStatus`) that we want to invoke.
- `params` specifies the arguments to the method.
- `id` is the ID of this request. Request IDs should be unique.

That's it!

### JSON RPC Success Response[​](#json-rpc-success-response "Direct link to heading")

If the call is successful, the response will look like this:

```
{
  "jsonrpc": "2.0",
  "result": {
    "Status": "Accepted"
  },
  "id": 1
}
```

- `id` is the ID of the request that this response corresponds to.
- `result` is the returned values of `getTxStatus`.

### JSON RPC Error Response[​](#json-rpc-error-response "Direct link to heading")

If the API method invoked returns an error then the response will have a field `error` in place of `result`. Additionally, there is an extra field, `data`, which holds additional information about the error that occurred.

Such a response would look like:

```
{
    "jsonrpc": "2.0",
    "error": {
        "code": -32600,
        "message": "[Some error message here]",
        "data": [Object with additional information about the error]
    },
    "id": 1
}
```

Other API Formats[​](#other-api-formats "Direct link to heading")
-----------------------------------------------------------------

Some APIs may use a standard other than JSON RPC 2.0 to format their requests and responses. Such extension should specify how to make calls and parse responses to them in their documentation.

Sending and Receiving Bytes[​](#sending-and-receiving-bytes "Direct link to heading")
-------------------------------------------------------------------------------------

Unless otherwise noted, when bytes are sent in an API call/response, they are in hex representation. However, Transaction IDs (TXIDs), ChainIDs, and subnetIDs are in [CB58](https://support.avalabs.org/en/articles/4587395-what-is-cb58) representation, a base-58 encoding with a checksum.


# Transaction Fees (/docs/rpcs/other/guides/txn-fees)

---
title: Transaction Fees
---

In order to prevent spam, transactions on Avalanche require the payment of a transaction fee. The fee is paid in AVAX. **The transaction fee is burned (destroyed forever).**

When you issue a transaction through Avalanche's API, the transaction fee is automatically deducted from one of the addresses you control. 

The [avalanchego wallet](https://github.com/ava-labs/avalanchego/blob/master/wallet/chain) contains example code written in golang for building and signing transactions on all three mainnet chains. 

X-Chain Fees[​](#fee-schedule)
-------------------------------------------------------

The X-Chain currently operates under a fixed fee mechanism. This table shows the X-Chain transaction fee schedule:

```
+----------+---------------------------+--------------------------------+
| Chain    | Transaction Type          | Mainnet Transaction Fee (AVAX) |
+----------+---------------------------+--------------------------------+
| X        | Send                      |                          0.001 |
+----------+---------------------------+--------------------------------+
| X        | Create Asset              |                           0.01 |
+----------+---------------------------+--------------------------------+
| X        | Mint Asset                |                          0.001 |
+----------+---------------------------+--------------------------------+
| X        | Import AVAX               |                          0.001 |
+----------+---------------------------+--------------------------------+
| X        | Export AVAX               |                          0.001 |
+----------+---------------------------+--------------------------------+
```

C-Chain Fees[​](#c-chain-fees)
-------------------------------------------------------

The Avalanche C-Chain uses an algorithm to determine the "base fee" for a transaction. The base fee increases when network utilization is above the target utilization and decreases when network utilization is below the target.

### Dynamic Fee Transactions[​](#dynamic-fee-transactions )

Transaction fees for non-atomic transactions are based on Ethereum's EIP-1559 style Dynamic Fee Transactions, which consists of a gas fee cap and a gas tip cap.

The fee cap specifies the maximum price the transaction is willing to pay per unit of gas. The tip cap (also called the priority fee) specifies the maximum amount above the base fee that the transaction is willing to pay per unit of gas. Therefore, the effective gas price paid by a transaction will be `min(gasFeeCap, baseFee + gasTipCap)`. Unlike in Ethereum, where the priority fee is paid to the miner that produces the block, in Avalanche both the base fee and the priority fee are burned. For legacy transactions, which only specify a single gas price, the gas price serves as both the gas fee cap and the gas tip cap.

Use the [`eth_baseFee`](/docs/api-reference/c-chain/api#eth_basefee) API method to estimate the base fee for the next block. If more blocks are produced in between the time that you construct your transaction and it is included in a block, the base fee could be different from the base fee estimated by the API call, so it is important to treat this value as an estimate.

Next, use [eth\_maxPriorityFeePerGas](/docs/api-reference/c-chain/api#eth_maxpriorityfeepergas) API call to estimate the priority fee needed to be included in a block. This API call will look at the most recent blocks and see what tips have been paid by recent transactions in order to be included in the block.

Transactions are ordered by the priority fee, then the timestamp (oldest first).

Based off of this information, you can specify the `gasFeeCap` and `gasTipCap` to your liking based on how you prioritize getting your transaction included as quickly as possible vs. minimizing the price paid per unit of gas.

#### Base Fee[​](#base-fee)

The base fee can go as low as 1 nAVAX (Gwei) and has no upper bound. You can use the [`eth_baseFee`](/docs/api-reference/c-chain/api#eth_basefee) and [eth\_maxPriorityFeePerGas](/docs/api-reference/c-chain/api#eth_maxpriorityfeepergas) API methods, or [Snowtrace's C-Chain Gas Tracker](https://snowtrace.io/gastracker), to estimate the gas price to use in your transactions.

#### Further Readings[​](#further-readings)

- [Adjusting Gas Price During High Network Activity](/docs/dapps/advanced-tutorials/manually-adjust-gas-price)
- [Sending Transactions with Dynamic Fees using JavaScript](/docs/dapps/advanced-tutorials/dynamic-gas-fees)

### Atomic Transaction Fees[​](#atomic-transaction-fees)

C-Chain atomic transactions (that is imports and exports from/to other chains) charge dynamic fees based on the amount of gas used by the transaction and the base fee of the block that includes the atomic transaction.

Gas Used:

```
+---------------------+-------+
| Item                : Gas   |
+---------------------+-------+
| Unsigned Tx Byte    : 1     |
+---------------------+-------+
| Signature           : 1000  |
+---------------------+-------+
| Per Atomic Tx       : 10000 |
+---------------------+-------+
```

Therefore, the gas used by an atomic transaction is `1 * len(unsignedTxBytes) + 1,000 * numSignatures + 10,000`

The TX fee additionally takes the base fee into account. Due to the fact that atomic transactions use units denominated in 9 decimal places, the base fee must be converted to 9 decimal places before calculating the actual fee paid by the transaction. Therefore, the actual fee is: `gasUsed * baseFee (converted to 9 decimals)`.


P-Chain Fees[​](#p-chain-fees)
-------------------------------------------------------

The Avalanche P-Chain utilizes a dynamic fee mechanism to optimize transaction costs and network utilization. This system adapts fees based on gas consumption to maintain a target utilization rate.

### Dimensions of Gas Consumption
Gas consumption is measured across four dimensions:

1. **Bandwidth** The transaction size in bytes.
2. **Reads** The number of state/database reads.
3. **Writes** The number of state/database writes.
4. **Compute** The compute time in microseconds.

The total gas consumed ($G$) by a transaction is:

```math
G = B + 1000R + 1000W + 4C
```

The current fee dimension weight configurations as well as the parameter configurations of the P-Chain can be read at any time with the [`platform.getFeeConfig`](/docs/api-reference/p-chain/api#platformgetfeeconfig) API endpoint. 

### Fee Adjustment Mechanism
Fees adjust dynamically based on excess gas consumption, the difference between current gas usage and the target gas rate. The exponential adjustment ensures consistent reactivity regardless of the current gas price. Fee changes scale proportionally with excess gas consumption, maintaining fairness and network stability. The technical specification of this mechanism is documented in [ACP-103](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/103-dynamic-fees/README.md#mechanism).



# X-Chain Migration (/docs/rpcs/other/guides/x-chain-migration)

---
title: X-Chain Migration
---
Overview[​](#overview "Direct link to heading")
-----------------------------------------------

This document summarizes all of the changes made to the X-Chain API to support Avalanche Cortina (v1.10.0), which migrates the X-Chain to run Snowman++. In summary, the core transaction submission and confirmation flow is unchanged, however, there are new APIs that must be called to index all transactions.

Transaction Broadcast and Confirmation[​](#transaction-broadcast-and-confirmation "Direct link to heading")
-----------------------------------------------------------------------------------------------------------

The transaction format on the X-Chain does not change in Cortina. This means that wallets that have already integrated with the X-Chain don't need to change how they sign transactions. Additionally, there is no change to the format of the [avm.issueTx](/docs/api-reference/x-chain/api#avmissuetx) or the [avm.getTx](/docs/api-reference/x-chain/api#avmgettx) API.

However, the [avm.getTxStatus](/docs/api-reference/x-chain/api#avmgettxstatus) endpoint is now deprecated and its usage should be replaced with [avm.getTx](/docs/api-reference/x-chain/api#avmgettx) (which only returns accepted transactions for AvalancheGo >= v1.9.12). [avm.getTxStatus](/docs/api-reference/x-chain/api#avmgettxstatus) will still work up to and after the Cortina activation if you wish to migrate after the network upgrade has occurred.

Vertex -> Block Indexing[​](#vertex---block-indexing "Direct link to heading")
------------------------------------------------------------------------------

Before Cortina, indexing the X-Chain required polling the `/ext/index/X/vtx` endpoint to fetch new vertices. During the Cortina activation, a “stop vertex” will be produced using a [new codec version](https://github.com/ava-labs/avalanchego/blob/c27721a8da1397b218ce9e9ec69839b8a30f9860/snow/engine/avalanche/vertex/codec.go#L17-L18) that will contain no transactions. This new vertex type will be the [same format](https://github.com/ava-labs/avalanchego/blob/c27721a8da1397b218ce9e9ec69839b8a30f9860/snow/engine/avalanche/vertex/stateless_vertex.go#L95-L102) as previous vertices. To ensure historical data can still be accessed in Cortina, the `/ext/index/X/vtx` will remain accessible even though it will no longer be populated with chain data.


<Callout title="Note">
The index for the X-chain tx and vtx endpoints will never increase again. The index for the X-chain blocks will increase as new blocks are added.
</Callout>

After Cortina activation, you will need to migrate to using the new _ext/index/X/block_ endpoint (shares the same semantics as [/ext/index/P/block](/docs/api-reference/index-api#p-chain-blocks)) to continue indexing X-Chain activity. Because X-Chain ordering is deterministic in Cortina, this means that X-Chain blocks across all heights will be consistent across all nodes and will include a timestamp. Here is an example of iterating over these blocks in Golang:

```
package main

import (
	"context"
	"fmt"
	"log"
	"time"

	"github.com/ava-labs/avalanchego/indexer"
	"github.com/ava-labs/avalanchego/vms/proposervm/block"
	"github.com/ava-labs/avalanchego/wallet/chain/x"
	"github.com/ava-labs/avalanchego/wallet/subnet/primary"
)

func main() {
	var (
		uri       = fmt.Sprintf("%s/ext/index/X/block", primary.LocalAPIURI)
		client    = indexer.NewClient(uri)
		ctx       = context.Background()
		nextIndex uint64
	)
	for {
		log.Printf("polling for next accepted block")
		container, err := client.GetContainerByIndex(ctx, nextIndex)
		if err != nil {
			time.Sleep(time.Second)
			continue
		}

		proposerVMBlock, err := block.Parse(container.Bytes)
		if err != nil {
			log.Fatalf("failed to parse proposervm block: %s\n", err)
		}

		avmBlockBytes := proposerVMBlock.Block()
		avmBlock, err := x.Parser.ParseBlock(avmBlockBytes)
		if err != nil {
			log.Fatalf("failed to parse avm block: %s\n", err)
		}

		acceptedTxs := avmBlock.Txs()
		log.Printf("accepted block %s with %d transactions", avmBlock.ID(), len(acceptedTxs))

		for _, tx := range acceptedTxs {
			log.Printf("accepted transaction %s", tx.ID())
		}

		nextIndex++
	}
}
```

After Cortina activation, it will also be possible to fetch X-Chain blocks directly without enabling the Index API. You can use the [avm.getBlock](/docs/api-reference/x-chain/api#avmgetblock), [avm.getBlockByHeight](/docs/api-reference/x-chain/api#avmgetblockbyheight), and [avm.getHeight](/docs/api-reference/x-chain/api#avmgetheight) endpoints to do so. This, again, will be similar to the [P-Chain semantics](/docs/api-reference/p-chain/api#platformgetblock).

Deprecated API Calls[​](#deprecated-api-calls "Direct link to heading")
-----------------------------------------------------------------------

This long-term deprecation effort will better align usage of AvalancheGo with its purpose, to be a minimal and efficient runtime that supports only what is required to validate the Primary Network and Avalanche L1s. Integrators should make plans to migrate to tools and services that are better optimized for serving queries over Avalanche Network state and avoid keeping any keys on the node itself.


<Callout title="Note">
This deprecation ONLY applies to APIs that AvalancheGo exposes over the HTTP port. Transaction types with similar names to these APIs are NOT being deprecated.
</Callout>
- ipcs
    - ipcs.publishBlockchain
    - ipcs.unpublishBlockchain
    - ipcs.getPublishedBlockchains
- keystore
    - keystore.createUser
    - keystore.deleteUser
    - keystore.listUsers
    - keystore.importUser
    - keystore.exportUser
- avm/pubsub
- avm
    - avm.getAddressTxs
    - avm.getBalance
    - avm.getAllBalances
    - avm.createAsset
    - avm.createFixedCapAsset
    - avm.createVariableCapAsset
    - avm.createNFTAsset
    - avm.createAddress
    - avm.listAddresses
    - avm.exportKey
    - avm.importKey
    - avm.mint
    - avm.sendNFT
    - avm.mintNFT
    - avm.import
    - avm.export
    - avm.send
    - avm.sendMultiple
- avm/wallet
    - wallet.issueTx
    - wallet.send
    - wallet.sendMultiple
- platform
    - platform.exportKey
    - platform.importKey
    - platform.getBalance
    - platform.createAddress
    - platform.listAddresses
    - platform.getSubnets
    - platform.addValidator
    - platform.addDelegator
    - platform.addSubnetValidator
    - platform.createSubnet
    - platform.exportAVAX
    - platform.importAVAX
    - platform.createBlockchain
    - platform.getBlockchains
    - platform.getStake
    - platform.getMaxStakeAmount
    - platform.getRewardUTXOs

Cortina FAQ[​](#cortina-faq "Direct link to heading")
-----------------------------------------------------

### Do I Have to Upgrade my Node?[​](#do-i-have-to-upgrade-my-node "Direct link to heading")

If you don't upgrade your validator to `v1.10.0` before the Avalanche Mainnet activation date, your node will be marked as offline and other nodes will report your node as having lower uptime, which may jeopardize your staking rewards.

### Is There any Change in Hardware Requirements?[​](#is-there-any-change-in-hardware-requirements "Direct link to heading")

No.

### Will Updating Decrease my Validator's Uptime?[​](#will-updating-decrease-my-validators-uptime "Direct link to heading")

No. As a reminder, you can check your validator's estimated uptime using the [`info.uptime` API call](/docs/api-reference/info-api#infouptime).

### I Think Something Is Wrong. What Should I Do?[​](#i-think-something-is-wrong-what-should-i-do "Direct link to heading")

First, make sure that you've read the documentation thoroughly and checked the [FAQs](https://support.avax.network/en/). If you don't see an answer to your question, go to our [Discord](https://discord.com/invite/RwXY7P6) server and search for your question. If it has not already been asked, please post it in the appropriate channel.


# Avalanche Network Protocol (/docs/rpcs/other/standards/avalanche-network-protocol)

---
title: Avalanche Network Protocol 
---

Overview[​](#overview "Direct link to heading")
-----------------------------------------------

Avalanche network defines the core communication format between Avalanche nodes. It uses the [primitive serialization](/docs/api-reference/standards/serialization-primitives) format for payload packing.

`"Containers"` are mentioned extensively in the description. A Container is simply a generic term for blocks.

This document describes the protocol for peer-to-peer communication using Protocol Buffers (proto3). The protocol defines a set of messages exchanged between peers in a peer-to-peer network. Each message is represented by the `Message` proto message, which can encapsulate various types of messages, including network messages, state-sync messages, bootstrapping messages, consensus messages, and application messages.

Message[​](#message "Direct link to heading")
---------------------------------------------

The `Message` proto message is the main container for all peer-to-peer communication. It uses the `oneof` construct to represent different message types. The supported compression algorithms include Gzip and Zstd.

```
message Message {
  oneof message {
    bytes compressed_gzip = 1;
    bytes compressed_zstd = 2;
    // ... (other compression algorithms can be added)
    Ping ping = 11;
    Pong pong = 12;
    Version version = 13;
    PeerList peer_list = 14;
    // ... (other message types)
  }
}
```

### Compression[​](#compression "Direct link to heading")

The `compressed_gzip` and `compressed_zstd` fields are used for Gzip and Zstd compression, respectively, of the encapsulated message. These fields are set only if the message type supports compression.

Network Messages[​](#network-messages "Direct link to heading")
---------------------------------------------------------------

### Ping[​](#ping "Direct link to heading")

The `Ping` message reports a peer's perceived uptime percentage.

```
message Ping {
  uint32 uptime = 1;
  repeated SubnetUptime subnet_uptimes = 2;
}
```

- `uptime`: Uptime percentage on the primary network \[0, 100\].
- `subnet_uptimes`: Uptime percentages on Avalanche L1s.

### Pong[​](#pong "Direct link to heading")

The `Pong` message is sent in response to a `Ping` with the perceived uptime of the peer.

```
message Pong {
  uint32 uptime = 1; // Deprecated: uptime is now sent in Ping
  repeated SubnetUptime subnet_uptimes = 2; // Deprecated: uptime is now sent in Ping
}
```

### Version[​](#version "Direct link to heading")

The `Version` message is the first outbound message sent to a peer during the p2p handshake.

```
message Version {
  uint32 network_id = 1;
  uint64 my_time = 2;
  bytes ip_addr = 3;
  uint32 ip_port = 4;
  string my_version = 5;
  uint64 my_version_time = 6;
  bytes sig = 7;
  repeated bytes tracked_subnets = 8;
}
```

- `network_id`: Network identifier (e.g., local, testnet, Mainnet).
- `my_time`: Unix timestamp when the `Version` message was created.
- `ip_addr`: IP address of the peer.
- `ip_port`: IP port of the peer.
- `my_version`: Avalanche client version.
- `my_version_time`: Timestamp of the IP.
- `sig`: Signature of the peer IP port pair at a provided timestamp.
- `tracked_subnets`: Avalanche L1s the peer is tracking.

### PeerList[​](#peerlist "Direct link to heading")

The `PeerList` message contains network-level metadata for a set of validators.

```
message PeerList {
  repeated ClaimedIpPort claimed_ip_ports = 1;
}
```

- `claimed_ip_ports`: List of claimed IP and port pairs.

### PeerListAck[​](#peerlistack "Direct link to heading")

The `PeerListAck` message is sent in response to `PeerList` to acknowledge the subset of peers that the peer will attempt to connect to.

```
message PeerListAck {
  reserved 1; // deprecated; used to be tx_ids
  repeated PeerAck peer_acks = 2;
}
```

- `peer_acks`: List of acknowledged peers.

State-Sync Messages[​](#state-sync-messages "Direct link to heading")
---------------------------------------------------------------------

### GetStateSummaryFrontier[​](#getstatesummaryfrontier "Direct link to heading")

The `GetStateSummaryFrontier` message requests a peer's most recently accepted state summary.

```
message GetStateSummaryFrontier {
  bytes chain_id = 1;
  uint32 request_id = 2;
  uint64 deadline = 3;
}
```

- `chain_id`: Chain being requested from.
- `request_id`: Unique identifier for this request.
- `deadline`: Timeout (ns) for this request.

### StateSummaryFrontier[​](#statesummaryfrontier "Direct link to heading")

The `StateSummaryFrontier` message is sent in response to a `GetStateSummaryFrontier` request.

```
message StateSummaryFrontier {
  bytes chain_id = 1;
  uint32 request_id = 2;
  bytes summary = 3;
}
```

- `chain_id`: Chain being responded from.
- `request_id`: Request ID of the original `GetStateSummaryFrontier` request.
- `summary`: The requested state summary.

### GetAcceptedStateSummary[​](#getacceptedstatesummary "Direct link to heading")

The `GetAcceptedStateSummary` message requests a set of state summaries at specified block heights.

```
message GetAcceptedStateSummary {
  bytes chain_id = 1;
  uint32 request_id = 2;
  uint64 deadline = 3;
  repeated uint64 heights = 4;
}
```

- `chain_id`: Chain being requested from.
- `request_id`: Unique identifier for this request.
- `deadline`: Timeout (ns) for this request.
- `heights`: Heights being requested.

### AcceptedStateSummary[​](#acceptedstatesummary "Direct link to heading")

The `AcceptedStateSummary` message is sent in response to `GetAcceptedStateSummary`.

```
message AcceptedStateSummary {
  bytes chain_id = 1;
  uint32 request_id = 2;
  repeated bytes summary_ids = 3;
}
```

- `chain_id`: Chain being responded from.
- `request_id`: Request ID of the original `GetAcceptedStateSummary` request.
- `summary_ids`: State summary IDs.

Bootstrapping Messages[​](#bootstrapping-messages "Direct link to heading")
---------------------------------------------------------------------------

### GetAcceptedFrontier[​](#getacceptedfrontier "Direct link to heading")

The `GetAcceptedFrontier` message requests the accepted frontier from a peer.

```
message GetAcceptedFrontier {
  bytes chain_id = 1;
  uint32 request_id = 2;
  uint64 deadline = 3;
  EngineType engine_type = 4;
}
```

- `chain_id`: Chain being requested from.
- `request_id`: Unique identifier for this request.
- `deadline`: Timeout (ns) for this request.
- `engine_type`: Consensus type the remote peer should use to handle this message.

### AcceptedFrontier[​](#acceptedfrontier "Direct link to heading")

The `AcceptedFrontier` message contains the remote peer's last accepted frontier.

```
message AcceptedFrontier {
  reserved 4; // Until Cortina upgrade is activated
  bytes chain_id = 1;
  uint32 request_id = 2;
  bytes container_id = 3;
}
```

- `chain_id`: Chain being responded from.
- `request_id`: Request ID of the original `GetAcceptedFrontier` request.
- `container_id`: The ID of the last accepted frontier.

### GetAccepted[​](#getaccepted "Direct link to heading")

The `GetAccepted` message sends a request with the sender's accepted frontier to a remote peer.

```
message GetAccepted {
  bytes chain_id = 1;
  uint32 request_id = 2;
  uint64 deadline = 3;
  repeated bytes container_ids = 4;
  EngineType engine_type = 5;
}
```

- `chain_id`: Chain being requested from.
- `request_id`: Unique identifier for this message.
- `deadline`: Timeout (ns) for this request.
- `container_ids`: The

sender's accepted frontier.

- `engine_type`: Consensus type to handle this message.

### Accepted[​](#accepted "Direct link to heading")

The `Accepted` message is sent in response to `GetAccepted`.

```
message Accepted {
  reserved 4; // Until Cortina upgrade is activated
  bytes chain_id = 1;
  uint32 request_id = 2;
  repeated bytes container_ids = 3;
}
```

- `chain_id`: Chain being responded from.
- `request_id`: Request ID of the original `GetAccepted` request.
- `container_ids`: Subset of container IDs from the `GetAccepted` request that the sender has accepted.

### GetAncestors[​](#getancestors "Direct link to heading")

The `GetAncestors` message requests the ancestors for a given container.

```
message GetAncestors {
  bytes chain_id = 1;
  uint32 request_id = 2;
  uint64 deadline = 3;
  bytes container_id = 4;
  EngineType engine_type = 5;
}
```

- `chain_id`: Chain being requested from.
- `request_id`: Unique identifier for this request.
- `deadline`: Timeout (ns) for this request.
- `container_id`: Container for which ancestors are being requested.
- `engine_type`: Consensus type to handle this message.

### Ancestors[​](#ancestors "Direct link to heading")

The `Ancestors` message is sent in response to `GetAncestors`.

```
message Ancestors {
  reserved 4; // Until Cortina upgrade is activated
  bytes chain_id = 1;
  uint32 request_id = 2;
  repeated bytes containers = 3;
}
```

- `chain_id`: Chain being responded from.
- `request_id`: Request ID of the original `GetAncestors` request.
- `containers`: Ancestry for the requested container.

Consensus Messages[​](#consensus-messages "Direct link to heading")
-------------------------------------------------------------------

### Get[​](#get "Direct link to heading")

The `Get` message requests a container from a remote peer.

```
message Get {
  bytes chain_id = 1;
  uint32 request_id = 2;
  uint64 deadline = 3;
  bytes container_id = 4;
  EngineType engine_type = 5;
}
```

- `chain_id`: Chain being requested from.
- `request_id`: Unique identifier for this request.
- `deadline`: Timeout (ns) for this request.
- `container_id`: Container being requested.
- `engine_type`: Consensus type to handle this message.

### Put[​](#put "Direct link to heading")

The `Put` message is sent in response to `Get` with the requested block.

```
message Put {
  bytes chain_id = 1;
  uint32 request_id = 2;
  bytes container = 3;
  EngineType engine_type = 4;
}
```

- `chain_id`: Chain being responded from.
- `request_id`: Request ID of the original `Get` request.
- `container`: Requested container.
- `engine_type`: Consensus type to handle this message.

### PushQuery[​](#pushquery "Direct link to heading")

The `PushQuery` message requests the preferences of a remote peer given a container.

```
message PushQuery {
  bytes chain_id = 1;
  uint32 request_id = 2;
  uint64 deadline = 3;
  bytes container = 4;
  EngineType engine_type = 5;
  uint64 requested_height = 6;
}
```

- `chain_id`: Chain being requested from.
- `request_id`: Unique identifier for this request.
- `deadline`: Timeout (ns) for this request.
- `container`: Container being gossiped.
- `engine_type`: Consensus type to handle this message.
- `requested_height`: Requesting peer's last accepted height.

### PullQuery[​](#pullquery "Direct link to heading")

The `PullQuery` message requests the preferences of a remote peer given a container id.

```
message PullQuery {
  bytes chain_id = 1;
  uint32 request_id = 2;
  uint64 deadline = 3;
  bytes container_id = 4;
  EngineType engine_type = 5;
  uint64 requested_height = 6;
}
```

- `chain_id`: Chain being requested from.
- `request_id`: Unique identifier for this request.
- `deadline`: Timeout (ns) for this request.
- `container_id`: Container id being gossiped.
- `engine_type`: Consensus type to handle this message.
- `requested_height`: Requesting peer's last accepted height.

### Chits[​](#chits "Direct link to heading")

The `Chits` message contains the preferences of a peer in response to a `PushQuery` or `PullQuery` message.

```
message Chits {
  bytes chain_id = 1;
  uint32 request_id = 2;
  bytes preferred_id = 3;
  bytes accepted_id = 4;
  bytes preferred_id_at_height = 5;
}
```

- `chain_id`: Chain being responded from.
- `request_id`: Request ID of the original `PushQuery`/`PullQuery` request.
- `preferred_id`: Currently preferred block.
- `accepted_id`: Last accepted block.
- `preferred_id_at_height`: Currently preferred block at the requested height.

Application Messages[​](#application-messages "Direct link to heading")
-----------------------------------------------------------------------

### AppRequest[​](#apprequest "Direct link to heading")

The `AppRequest` message is a VM-defined request.

```
message AppRequest {
  bytes chain_id = 1;
  uint32 request_id = 2;
  uint64 deadline = 3;
  bytes app_bytes = 4;
}
```

- `chain_id`: Chain being requested from.
- `request_id`: Unique identifier for this request.
- `deadline`: Timeout (ns) for this request.
- `app_bytes`: Request body.

### AppResponse[​](#appresponse "Direct link to heading")

The `AppResponse` message is a VM-defined response sent in response to `AppRequest`.

```
message AppResponse {
  bytes chain_id = 1;
  uint32 request_id = 2;
  bytes app_bytes = 3;
}
```

- `chain_id`: Chain being responded from.
- `request_id`: Request ID of the original `AppRequest`.
- `app_bytes`: Response body.

### AppGossip[​](#appgossip "Direct link to heading")

The `AppGossip` message is a VM-defined message.

```
message AppGossip {
  bytes chain_id = 1;
  bytes app_bytes = 2;
}
```

- `chain_id`: Chain the message is for.
- `app_bytes`: Message body.


# Cryptographic Primitives (/docs/rpcs/other/standards/cryptographic-primitives)

---
title: Cryptographic Primitives
---

Avalanche uses a variety of cryptographic primitives for its different functions. This file summarizes the type and kind of cryptography used at the network and blockchain layers.

## Cryptography in the Network Layer

Avalanche uses Transport Layer Security, TLS, to protect node-to-node communications from eavesdroppers. TLS combines the practicality of public-key cryptography with the efficiency of symmetric-key cryptography. This has resulted in TLS becoming the standard for internet communication. Whereas most classical consensus protocols employ public-key cryptography to prove receipt of messages to third parties, the novel Snow\* consensus family does not require such proofs. This enables Avalanche to employ TLS in authenticating stakers and eliminates the need for costly public-key cryptography for signing network messages.

### TLS Certificates

Avalanche does not rely on any centralized third-parties, and in particular, it does not use certificates issued by third-party authenticators. All certificates used within the network layer to identify endpoints are self-signed, thus creating a self-sovereign identity layer. No third parties are ever involved.

### TLS Addresses

To avoid posting the full TLS certificate to the P-Chain, the certificate is first hashed. For consistency, Avalanche employs the same hashing mechanism for the TLS certificates as is used in Bitcoin. Namely, the DER representation of the certificate is hashed with sha256, and the result is then hashed with ripemd160 to yield a 20-byte identifier for stakers.

This 20-byte identifier is represented by "NodeID-" followed by the data's [CB58](https://support.avalabs.org/en/articles/4587395-what-is-cb58) encoded string.

## Cryptography in the Avalanche Virtual Machine

The Avalanche virtual machine uses elliptic curve cryptography, specifically `secp256k1`, for its signatures on the blockchain.

This 32-byte identifier is represented by "PrivateKey-" followed by the data's [CB58](https://support.avalabs.org/en/articles/4587395-what-is-cb58) encoded string.

### Secp256k1 Addresses

Avalanche is not prescriptive about addressing schemes, choosing to instead leave addressing up to each blockchain.

The addressing scheme of the X-Chain and the P-Chain relies on secp256k1. Avalanche follows a similar approach as Bitcoin and hashes the ECDSA public key. The 33-byte compressed representation of the public key is hashed with sha256 **once**. The result is then hashed with ripemd160 to yield a 20-byte address.

Avalanche uses the convention `chainID-address` to specify which chain an address exists on. `chainID` may be replaced with an alias of the chain. When transmitting information through external applications, the CB58 convention is required.

### Bech32

Addresses on the X-Chain and P-Chain use the [Bech32](http://support.avalabs.org/en/articles/4587392-what-is-bech32) standard outlined in [BIP 0173](https://en.bitcoin.it/wiki/BIP_0173). There are four parts to a Bech32 address scheme. In order of appearance:

- A human-readable part (HRP). On Mainnet this is `avax`.
- The number `1`, which separates the HRP from the address and error correction code.
- A base-32 encoded string representing the 20 byte address.
- A 6-character base-32 encoded error correction code.

Additionally, an Avalanche address is prefixed with the alias of the chain it exists on, followed by a dash. For example, X-Chain addresses are prefixed with `X-`.

The following regular expression matches addresses on the X-Chain, P-Chain and C-Chain for Mainnet, Fuji and localhost. Note that all valid Avalanche addresses will match this regular expression, but some strings that are not valid Avalanche addresses may match this regular expression.

```
^([XPC]|[a-km-zA-HJ-NP-Z1-9]{36,72})-[a-zA-Z]{1,83}1[qpzry9x8gf2tvdw0s3jn54khce6mua7l]{38}$
```

Read more about Avalanche's [addressing scheme](https://support.avalabs.org/en/articles/4596397-what-is-an-address).

<Accordions>
<Accordion title="Bech32 and NetworkID Mapping">
For example the following Bech32 address, `X-avax19rknw8l0grnfunjrzwxlxync6zrlu33y2jxhrg`, is composed like so:

1.  HRP: `avax`
2.  Separator: `1`
3.  Address: `9rknw8l0grnfunjrzwxlxync6zrlu33y`
4.  Checksum: `2jxhrg`

Depending on the `networkID`, the encoded addresses will have a distinctive HRP per each network.

- 0 - X-`custom`19rknw8l0grnfunjrzwxlxync6zrlu33yeg5dya
- 1 - X-`avax`19rknw8l0grnfunjrzwxlxync6zrlu33y2jxhrg
- 2 - X-`cascade`19rknw8l0grnfunjrzwxlxync6zrlu33ypmtvnh
- 3 - X-`denali`19rknw8l0grnfunjrzwxlxync6zrlu33yhc357h
- 4 - X-`everest`19rknw8l0grnfunjrzwxlxync6zrlu33yn44wty
- 5 - X-`fuji`19rknw8l0grnfunjrzwxlxync6zrlu33yxqzg0h
- 1337 - X-`custom`19rknw8l0grnfunjrzwxlxync6zrlu33yeg5dya
- 12345 - X-`local`19rknw8l0grnfunjrzwxlxync6zrlu33ynpm3qq

Here's the mapping of `networkID` to bech32 HRP.

```
  0: "custom",
  1: "avax",
  2: "cascade",
  3: "denali",
  4: "everest",
  5: "fuji",
  1337: "custom",
  12345: "local"
```
</Accordion>
</Accordions>

### Secp256k1 Recoverable Signatures

Recoverable signatures are stored as the 65-byte **`[R || S || V]`** where **`V`** is 0 or 1 to allow quick public key recoverability. **`S`** must be in the lower half of the possible range to prevent signature malleability. Before signing a message, the message is hashed using sha256.

### Secp256k1 Example

Suppose Rick and Morty are setting up a secure communication channel. Morty creates a new public-private key pair.

Private Key: `0x98cb077f972feb0481f1d894f272c6a1e3c15e272a1658ff716444f465200070`

Public Key (33-byte compressed): `0x02b33c917f2f6103448d7feb42614037d05928433cb25e78f01a825aa829bb3c27`

Because of Rick's infinite wisdom, he doesn't trust himself with carrying around Morty's public key, so he only asks for Morty's address. Morty follows the instructions, SHA256's his public key, and then ripemd160's that result to produce an address.

SHA256(Public Key): `0x28d7670d71667e93ff586f664937f52828e6290068fa2a37782045bffa7b0d2f`

Address: `0xe8777f38c88ca153a6fdc25942176d2bf5491b89`

Morty is quite confused because a public key should be safe to be public knowledge. Rick belches and explains that hashing the public key protects the private key owner from potential future security flaws in elliptic curve cryptography. In the event cryptography is broken and a private key can be derived from a public key, users can transfer their funds to an address that has never signed a transaction before, preventing their funds from being compromised by an attacker. This enables coin owners to be protected while the cryptography is upgraded across the clients.

Later, once Morty has learned more about Rick's backstory, Morty attempts to send Rick a message. Morty knows that Rick will only read the message if he can verify it was from him, so he signs the message with his private key.

Message: `0x68656c702049276d207472617070656420696e206120636f6d7075746572`

Message Hash: `0x912800c29d554fb9cdce579c0abba991165bbbc8bfec9622481d01e0b3e4b7da`

Message Signature: `0xb52aa0535c5c48268d843bd65395623d2462016325a86f09420c81f142578e121d11bd368b88ca6de4179a007e6abe0e8d0be1a6a4485def8f9e02957d3d72da01`

Morty was never seen again.

### Signed Messages

A standard for interoperable generic signed messages based on the Bitcoin Script format and Ethereum format.

```
sign(sha256(length(prefix) + prefix + length(message) + message))
```

The prefix is simply the string `\x1AAvalanche Signed Message:\n`, where `0x1A` is the length of the prefix text and `length(message)` is an [integer](/docs/api-reference/standards/serialization-primitives#integer) of the message size.

### Gantt Pre-Image Specification

```
+---------------+-----------+------------------------------+
| prefix        : [26]byte  |                     26 bytes |
+---------------+-----------+------------------------------+
| messageLength : int       |                      4 bytes |
+---------------+-----------+------------------------------+
| message       : []byte    |          size(message) bytes |
+---------------+-----------+------------------------------+
                            |       26 + 4 + size(message) |
                            +------------------------------+
```

### Example

As an example we will sign the message "Through consensus to the stars"

```
// prefix size: 26 bytes
0x1a
// prefix: Avalanche Signed Message:\n
0x41 0x76 0x61 0x6c 0x61 0x6e 0x63 0x68 0x65 0x20 0x53 0x69 0x67 0x6e 0x65 0x64 0x20 0x4d 0x65 0x73 0x73 0x61 0x67 0x65 0x3a 0x0a
// msg size: 30 bytes
0x00 0x00 0x00 0x1e
// msg: Through consensus to the stars
54 68 72 6f 75 67 68 20 63 6f 6e 73 65 6e 73 75 73 20 74 6f 20 74 68 65 20 73 74 61 72 73
```

After hashing with `sha256` and signing the pre-image we return the value [cb58](https://support.avalabs.org/en/articles/4587395-what-is-cb58) encoded: `4Eb2zAHF4JjZFJmp4usSokTGqq9mEGwVMY2WZzzCmu657SNFZhndsiS8TvL32n3bexd8emUwiXs8XqKjhqzvoRFvghnvSN`. Here's an example using [Core web](https://core.app/tools/signing-tools/sign/).

<Callout title="Note">
A full guide on how to sign messages with Core web can be found [here](https://support.avax.network/en/articles/7206948-core-web-how-do-i-use-the-signing-tools).
</Callout>

![Sign message](/images/cryptography1.png)

## Cryptography in Ethereum Virtual Machine

Avalanche nodes support the full Ethereum Virtual Machine (EVM) and precisely duplicate all of the cryptographic constructs used in Ethereum. This includes the Keccak hash function and the other mechanisms used for cryptographic security in the EVM.

## Cryptography in Other Virtual Machines

Since Avalanche is an extensible platform, we expect that people will add additional cryptographic primitives to the system over time.


# Serialization Primitives (/docs/rpcs/other/standards/serialization-primitives)

---
title: Serialization Primitives
---

Avalanche uses a simple, uniform, and elegant representation for all internal data. This document describes how primitive types are encoded on the Avalanche platform. Transactions are encoded in terms of these basic primitive types.

Byte[​](#byte "Direct link to heading")
---------------------------------------

Bytes are packed as-is into the message payload.

Example:

```
Packing:
    0x01
Results in:
    [0x01]
```

Short[​](#short "Direct link to heading")
-----------------------------------------

Shorts are packed in BigEndian format into the message payload.

Example:

```
Packing:
    0x0102
Results in:
    [0x01, 0x02]
```

Integer[​](#integer "Direct link to heading")
---------------------------------------------

Integers are 32-bit values packed in BigEndian format into the message payload.

Example:

```
Packing:
    0x01020304
Results in:
    [0x01, 0x02, 0x03, 0x04]
```

Long Integers[​](#long-integers "Direct link to heading")
---------------------------------------------------------

Long integers are 64-bit values packed in BigEndian format into the message payload.

Example:

```
Packing:
    0x0102030405060708
Results in:
    [0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08]
```

IP Addresses[​](#ip-addresses "Direct link to heading")
-------------------------------------------------------

IP addresses are represented as 16-byte IPv6 format, with the port appended into the message payload as a Short. IPv4 addresses are padded with 12 bytes of leading 0x00s.

IPv4 example:

```
Packing:
    "127.0.0.1:9650"
Results in:
    [
        0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
        0x00, 0x00, 0xff, 0xff, 0x7f, 0x00, 0x00, 0x01,
        0x25, 0xb2,
    ]
```

IPv6 example:

```
Packing:
    "[2001:0db8:ac10:fe01::]:12345"
Results in:
    [
        0x20, 0x01, 0x0d, 0xb8, 0xac, 0x10, 0xfe, 0x01,
        0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00,
        0x30, 0x39,
    ]
```

Fixed-Length Array[​](#fixed-length-array "Direct link to heading")
-------------------------------------------------------------------

Fixed-length arrays, whose length is known ahead of time and by context, are packed in order.

Byte array example:

```
Packing:
    [0x01, 0x02]
Results in:
    [0x01, 0x02]
```

Integer array example:

```
Packing:
    [0x03040506]
Results in:
    [0x03, 0x04, 0x05, 0x06]
```

Variable Length Array[​](#variable-length-array "Direct link to heading")
-------------------------------------------------------------------------

The length of the array is prefixed in Integer format, followed by the packing of the array contents in Fixed Length Array format.

Byte array example:

```
Packing:
    [0x01, 0x02]
Results in:
    [0x00, 0x00, 0x00, 0x02, 0x01, 0x02]
```

Int array example:

```
Packing:
    [0x03040506]
Results in:
    [0x00, 0x00, 0x00, 0x01, 0x03, 0x04, 0x05, 0x06]
```

String[​](#string "Direct link to heading")
-------------------------------------------

A String is packed similarly to a variable-length byte array. However, the length prefix is a short rather than an int. Strings are encoded in UTF-8 format.

Example:

```
Packing:
    "Avax"
Results in:
    [0x00, 0x04, 0x41, 0x76, 0x61, 0x78]

```



# platform.getBalance (/docs/rpcs/p-chain/balances-&-utxos/platform_getBalance)

---
title: platform.getBalance
full: true
_openapi:
  method: POST
  route: /ext/bc/P#platform.getBalance
  toc: []
  structuredData:
    headings: []
    contents:
      - content: GetBalance gets the balance of an address
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

GetBalance gets the balance of an address

<APIPage document={"./public/openapi/platformvm.yaml"} operations={[{"path":"/ext/bc/P#platform.getBalance","method":"post"}]} webhooks={[]} hasHead={false} />

# platform.getUTXOs (/docs/rpcs/p-chain/balances-&-utxos/platform_getUTXOs)

---
title: platform.getUTXOs
full: true
_openapi:
  method: POST
  route: /ext/bc/P#platform.getUTXOs
  toc: []
  structuredData:
    headings: []
    contents:
      - content: GetUTXOs returns the UTXOs controlled by the given addresses
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

GetUTXOs returns the UTXOs controlled by the given addresses

<APIPage document={"./public/openapi/platformvm.yaml"} operations={[{"path":"/ext/bc/P#platform.getUTXOs","method":"post"}]} webhooks={[]} hasHead={false} />

# platform.getBlockchainStatus (/docs/rpcs/p-chain/blockchains/platform_getBlockchainStatus)

---
title: platform.getBlockchainStatus
full: true
_openapi:
  method: POST
  route: /ext/bc/P#platform.getBlockchainStatus
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          GetBlockchainStatus gets the status of a blockchain with the ID
          [args.BlockchainID].
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

GetBlockchainStatus gets the status of a blockchain with the ID [args.BlockchainID].

<APIPage document={"./public/openapi/platformvm.yaml"} operations={[{"path":"/ext/bc/P#platform.getBlockchainStatus","method":"post"}]} webhooks={[]} hasHead={false} />

# platform.getBlockchains (/docs/rpcs/p-chain/blockchains/platform_getBlockchains)

---
title: platform.getBlockchains
full: true
_openapi:
  method: POST
  route: /ext/bc/P#platform.getBlockchains
  toc: []
  structuredData:
    headings: []
    contents:
      - content: GetBlockchains returns all of the blockchains that exist
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

GetBlockchains returns all of the blockchains that exist

<APIPage document={"./public/openapi/platformvm.yaml"} operations={[{"path":"/ext/bc/P#platform.getBlockchains","method":"post"}]} webhooks={[]} hasHead={false} />

# platform.validatedBy (/docs/rpcs/p-chain/blockchains/platform_validatedBy)

---
title: platform.validatedBy
full: true
_openapi:
  method: POST
  route: /ext/bc/P#platform.validatedBy
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          ValidatedBy returns the ID of the Subnet that validates
          [args.BlockchainID]
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

ValidatedBy returns the ID of the Subnet that validates [args.BlockchainID]

<APIPage document={"./public/openapi/platformvm.yaml"} operations={[{"path":"/ext/bc/P#platform.validatedBy","method":"post"}]} webhooks={[]} hasHead={false} />

# platform.validates (/docs/rpcs/p-chain/blockchains/platform_validates)

---
title: platform.validates
full: true
_openapi:
  method: POST
  route: /ext/bc/P#platform.validates
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Validates returns the IDs of the blockchains validated by
          [args.SubnetID]
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Validates returns the IDs of the blockchains validated by [args.SubnetID]

<APIPage document={"./public/openapi/platformvm.yaml"} operations={[{"path":"/ext/bc/P#platform.validates","method":"post"}]} webhooks={[]} hasHead={false} />

# platform.getBlock (/docs/rpcs/p-chain/blocks/platform_getBlock)

---
title: platform.getBlock
full: true
_openapi:
  method: POST
  route: /ext/bc/P#platform.getBlock
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Calls the platform.getBlock method
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Calls the platform.getBlock method

<APIPage document={"./public/openapi/platformvm.yaml"} operations={[{"path":"/ext/bc/P#platform.getBlock","method":"post"}]} webhooks={[]} hasHead={false} />

# platform.getBlockByHeight (/docs/rpcs/p-chain/blocks/platform_getBlockByHeight)

---
title: platform.getBlockByHeight
full: true
_openapi:
  method: POST
  route: /ext/bc/P#platform.getBlockByHeight
  toc: []
  structuredData:
    headings: []
    contents:
      - content: GetBlockByHeight returns the block at the given height.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

GetBlockByHeight returns the block at the given height.

<APIPage document={"./public/openapi/platformvm.yaml"} operations={[{"path":"/ext/bc/P#platform.getBlockByHeight","method":"post"}]} webhooks={[]} hasHead={false} />

# platform.getCurrentSupply (/docs/rpcs/p-chain/chain-info/platform_getCurrentSupply)

---
title: platform.getCurrentSupply
full: true
_openapi:
  method: POST
  route: /ext/bc/P#platform.getCurrentSupply
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          GetCurrentSupply returns an upper bound on the supply of AVAX in the
          system
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

GetCurrentSupply returns an upper bound on the supply of AVAX in the system

<APIPage document={"./public/openapi/platformvm.yaml"} operations={[{"path":"/ext/bc/P#platform.getCurrentSupply","method":"post"}]} webhooks={[]} hasHead={false} />

# platform.getHeight (/docs/rpcs/p-chain/chain-info/platform_getHeight)

---
title: platform.getHeight
full: true
_openapi:
  method: POST
  route: /ext/bc/P#platform.getHeight
  toc: []
  structuredData:
    headings: []
    contents:
      - content: GetHeight returns the height of the last accepted block
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

GetHeight returns the height of the last accepted block

<APIPage document={"./public/openapi/platformvm.yaml"} operations={[{"path":"/ext/bc/P#platform.getHeight","method":"post"}]} webhooks={[]} hasHead={false} />

# platform.getProposedHeight (/docs/rpcs/p-chain/chain-info/platform_getProposedHeight)

---
title: platform.getProposedHeight
full: true
_openapi:
  method: POST
  route: /ext/bc/P#platform.getProposedHeight
  toc: []
  structuredData:
    headings: []
    contents:
      - content: GetProposedHeight returns the current ProposerVM height
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

GetProposedHeight returns the current ProposerVM height

<APIPage document={"./public/openapi/platformvm.yaml"} operations={[{"path":"/ext/bc/P#platform.getProposedHeight","method":"post"}]} webhooks={[]} hasHead={false} />

# platform.getTimestamp (/docs/rpcs/p-chain/chain-info/platform_getTimestamp)

---
title: platform.getTimestamp
full: true
_openapi:
  method: POST
  route: /ext/bc/P#platform.getTimestamp
  toc: []
  structuredData:
    headings: []
    contents:
      - content: GetTimestamp returns the current timestamp on chain.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

GetTimestamp returns the current timestamp on chain.

<APIPage document={"./public/openapi/platformvm.yaml"} operations={[{"path":"/ext/bc/P#platform.getTimestamp","method":"post"}]} webhooks={[]} hasHead={false} />

# platform.getFeeConfig (/docs/rpcs/p-chain/fees/platform_getFeeConfig)

---
title: platform.getFeeConfig
full: true
_openapi:
  method: POST
  route: /ext/bc/P#platform.getFeeConfig
  toc: []
  structuredData:
    headings: []
    contents:
      - content: GetFeeConfig returns the dynamic fee config of the chain.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

GetFeeConfig returns the dynamic fee config of the chain.

<APIPage document={"./public/openapi/platformvm.yaml"} operations={[{"path":"/ext/bc/P#platform.getFeeConfig","method":"post"}]} webhooks={[]} hasHead={false} />

# platform.getFeeState (/docs/rpcs/p-chain/fees/platform_getFeeState)

---
title: platform.getFeeState
full: true
_openapi:
  method: POST
  route: /ext/bc/P#platform.getFeeState
  toc: []
  structuredData:
    headings: []
    contents:
      - content: GetFeeState returns the current fee state of the chain.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

GetFeeState returns the current fee state of the chain.

<APIPage document={"./public/openapi/platformvm.yaml"} operations={[{"path":"/ext/bc/P#platform.getFeeState","method":"post"}]} webhooks={[]} hasHead={false} />

# platform.getValidatorFeeConfig (/docs/rpcs/p-chain/fees/platform_getValidatorFeeConfig)

---
title: platform.getValidatorFeeConfig
full: true
_openapi:
  method: POST
  route: /ext/bc/P#platform.getValidatorFeeConfig
  toc: []
  structuredData:
    headings: []
    contents:
      - content: GetValidatorFeeConfig returns the validator fee config of the chain.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

GetValidatorFeeConfig returns the validator fee config of the chain.

<APIPage document={"./public/openapi/platformvm.yaml"} operations={[{"path":"/ext/bc/P#platform.getValidatorFeeConfig","method":"post"}]} webhooks={[]} hasHead={false} />

# platform.getValidatorFeeState (/docs/rpcs/p-chain/fees/platform_getValidatorFeeState)

---
title: platform.getValidatorFeeState
full: true
_openapi:
  method: POST
  route: /ext/bc/P#platform.getValidatorFeeState
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          GetValidatorFeeState returns the current validator fee state of the
          chain.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

GetValidatorFeeState returns the current validator fee state of the chain.

<APIPage document={"./public/openapi/platformvm.yaml"} operations={[{"path":"/ext/bc/P#platform.getValidatorFeeState","method":"post"}]} webhooks={[]} hasHead={false} />

# platform.getRewardUTXOs (/docs/rpcs/p-chain/rewards/platform_getRewardUTXOs)

---
title: platform.getRewardUTXOs
full: true
_openapi:
  method: POST
  route: /ext/bc/P#platform.getRewardUTXOs
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          GetRewardUTXOs returns the UTXOs that were rewarded after the provided
          transaction's staking period ended.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

GetRewardUTXOs returns the UTXOs that were rewarded after the provided transaction's staking period ended.

<APIPage document={"./public/openapi/platformvm.yaml"} operations={[{"path":"/ext/bc/P#platform.getRewardUTXOs","method":"post"}]} webhooks={[]} hasHead={false} />

# platform.getMinStake (/docs/rpcs/p-chain/staking/platform_getMinStake)

---
title: platform.getMinStake
full: true
_openapi:
  method: POST
  route: /ext/bc/P#platform.getMinStake
  toc: []
  structuredData:
    headings: []
    contents:
      - content: GetMinStake returns the minimum staking amount in nAVAX.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

GetMinStake returns the minimum staking amount in nAVAX.

<APIPage document={"./public/openapi/platformvm.yaml"} operations={[{"path":"/ext/bc/P#platform.getMinStake","method":"post"}]} webhooks={[]} hasHead={false} />

# platform.getStake (/docs/rpcs/p-chain/staking/platform_getStake)

---
title: platform.getStake
full: true
_openapi:
  method: POST
  route: /ext/bc/P#platform.getStake
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          GetStake returns the amount of nAVAX that [args.Addresses] have
          cumulatively staked on the Primary Network. This method assumes that
          each stake output has only owner This method assumes only AVAX can be
          staked This method only concerns itself with the Primary Network, not
          subnets TODO: Improve the performance of this method by maintaining
          this data in a data structure rather than re-calculating it by
          iterating over stakers
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

GetStake returns the amount of nAVAX that [args.Addresses] have cumulatively staked on the Primary Network. This method assumes that each stake output has only owner This method assumes only AVAX can be staked This method only concerns itself with the Primary Network, not subnets TODO: Improve the performance of this method by maintaining this data in a data structure rather than re-calculating it by iterating over stakers

<APIPage document={"./public/openapi/platformvm.yaml"} operations={[{"path":"/ext/bc/P#platform.getStake","method":"post"}]} webhooks={[]} hasHead={false} />

# platform.getTotalStake (/docs/rpcs/p-chain/staking/platform_getTotalStake)

---
title: platform.getTotalStake
full: true
_openapi:
  method: POST
  route: /ext/bc/P#platform.getTotalStake
  toc: []
  structuredData:
    headings: []
    contents:
      - content: GetTotalStake returns the total amount staked on the Primary Network
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

GetTotalStake returns the total amount staked on the Primary Network

<APIPage document={"./public/openapi/platformvm.yaml"} operations={[{"path":"/ext/bc/P#platform.getTotalStake","method":"post"}]} webhooks={[]} hasHead={false} />

# platform.getStakingAssetID (/docs/rpcs/p-chain/subnets/platform_getStakingAssetID)

---
title: platform.getStakingAssetID
full: true
_openapi:
  method: POST
  route: /ext/bc/P#platform.getStakingAssetID
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          GetStakingAssetID returns the assetID of the token used to stake on
          the provided subnet
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

GetStakingAssetID returns the assetID of the token used to stake on the provided subnet

<APIPage document={"./public/openapi/platformvm.yaml"} operations={[{"path":"/ext/bc/P#platform.getStakingAssetID","method":"post"}]} webhooks={[]} hasHead={false} />

# platform.getSubnet (/docs/rpcs/p-chain/subnets/platform_getSubnet)

---
title: platform.getSubnet
full: true
_openapi:
  method: POST
  route: /ext/bc/P#platform.getSubnet
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Calls the platform.getSubnet method
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Calls the platform.getSubnet method

<APIPage document={"./public/openapi/platformvm.yaml"} operations={[{"path":"/ext/bc/P#platform.getSubnet","method":"post"}]} webhooks={[]} hasHead={false} />

# platform.getSubnets (/docs/rpcs/p-chain/subnets/platform_getSubnets)

---
title: platform.getSubnets
full: true
_openapi:
  method: POST
  route: /ext/bc/P#platform.getSubnets
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          GetSubnets returns the subnets whose ID are in [args.IDs] The response
          will include the primary network
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

GetSubnets returns the subnets whose ID are in [args.IDs] The response will include the primary network

<APIPage document={"./public/openapi/platformvm.yaml"} operations={[{"path":"/ext/bc/P#platform.getSubnets","method":"post"}]} webhooks={[]} hasHead={false} />

# platform.getTx (/docs/rpcs/p-chain/transactions/platform_getTx)

---
title: platform.getTx
full: true
_openapi:
  method: POST
  route: /ext/bc/P#platform.getTx
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Calls the platform.getTx method
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Calls the platform.getTx method

<APIPage document={"./public/openapi/platformvm.yaml"} operations={[{"path":"/ext/bc/P#platform.getTx","method":"post"}]} webhooks={[]} hasHead={false} />

# platform.getTxStatus (/docs/rpcs/p-chain/transactions/platform_getTxStatus)

---
title: platform.getTxStatus
full: true
_openapi:
  method: POST
  route: /ext/bc/P#platform.getTxStatus
  toc: []
  structuredData:
    headings: []
    contents:
      - content: GetTxStatus gets a tx's status
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

GetTxStatus gets a tx's status

<APIPage document={"./public/openapi/platformvm.yaml"} operations={[{"path":"/ext/bc/P#platform.getTxStatus","method":"post"}]} webhooks={[]} hasHead={false} />

# platform.issueTx (/docs/rpcs/p-chain/transactions/platform_issueTx)

---
title: platform.issueTx
full: true
_openapi:
  method: POST
  route: /ext/bc/P#platform.issueTx
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Calls the platform.issueTx method
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Calls the platform.issueTx method

<APIPage document={"./public/openapi/platformvm.yaml"} operations={[{"path":"/ext/bc/P#platform.issueTx","method":"post"}]} webhooks={[]} hasHead={false} />

# platform.getCurrentValidators (/docs/rpcs/p-chain/validators/platform_getCurrentValidators)

---
title: platform.getCurrentValidators
full: true
_openapi:
  method: POST
  route: /ext/bc/P#platform.getCurrentValidators
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          GetCurrentValidators returns the current validators. If a single
          nodeID is provided, full delegators information is also returned.
          Otherwise only delegators' number and total weight is returned.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

GetCurrentValidators returns the current validators. If a single nodeID is provided, full delegators information is also returned. Otherwise only delegators' number and total weight is returned.

<APIPage document={"./public/openapi/platformvm.yaml"} operations={[{"path":"/ext/bc/P#platform.getCurrentValidators","method":"post"}]} webhooks={[]} hasHead={false} />

# platform.getL1Validator (/docs/rpcs/p-chain/validators/platform_getL1Validator)

---
title: platform.getL1Validator
full: true
_openapi:
  method: POST
  route: /ext/bc/P#platform.getL1Validator
  toc: []
  structuredData:
    headings: []
    contents:
      - content: GetL1Validator returns the L1 validator if it exists
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

GetL1Validator returns the L1 validator if it exists

<APIPage document={"./public/openapi/platformvm.yaml"} operations={[{"path":"/ext/bc/P#platform.getL1Validator","method":"post"}]} webhooks={[]} hasHead={false} />

# platform.getValidatorsAt (/docs/rpcs/p-chain/validators/platform_getValidatorsAt)

---
title: platform.getValidatorsAt
full: true
_openapi:
  method: POST
  route: /ext/bc/P#platform.getValidatorsAt
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          GetValidatorsAt returns the weights of the validator set of a provided
          subnet at the specified height.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

GetValidatorsAt returns the weights of the validator set of a provided subnet at the specified height.

<APIPage document={"./public/openapi/platformvm.yaml"} operations={[{"path":"/ext/bc/P#platform.getValidatorsAt","method":"post"}]} webhooks={[]} hasHead={false} />

# platform.sampleValidators (/docs/rpcs/p-chain/validators/platform_sampleValidators)

---
title: platform.sampleValidators
full: true
_openapi:
  method: POST
  route: /ext/bc/P#platform.sampleValidators
  toc: []
  structuredData:
    headings: []
    contents:
      - content: SampleValidators returns a sampling of the list of current validators
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

SampleValidators returns a sampling of the list of current validators

<APIPage document={"./public/openapi/platformvm.yaml"} operations={[{"path":"/ext/bc/P#platform.sampleValidators","method":"post"}]} webhooks={[]} hasHead={false} />

# avm.getAssetDescription (/docs/rpcs/x-chain/chain/avm_getAssetDescription)

---
title: avm.getAssetDescription
full: true
_openapi:
  method: POST
  route: /ext/bc/X#avm.getAssetDescription
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >-
          Get information about an asset including name, symbol, and
          denomination.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Get information about an asset including name, symbol, and denomination.

<APIPage document={"./public/openapi/xchain.yaml"} operations={[{"path":"/ext/bc/X#avm.getAssetDescription","method":"post"}]} webhooks={[]} hasHead={false} />

# avm.getBlock (/docs/rpcs/x-chain/chain/avm_getBlock)

---
title: avm.getBlock
full: true
_openapi:
  method: POST
  route: /ext/bc/X#avm.getBlock
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Returns the block with the given id.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Returns the block with the given id.

<APIPage document={"./public/openapi/xchain.yaml"} operations={[{"path":"/ext/bc/X#avm.getBlock","method":"post"}]} webhooks={[]} hasHead={false} />

# avm.getBlockByHeight (/docs/rpcs/x-chain/chain/avm_getBlockByHeight)

---
title: avm.getBlockByHeight
full: true
_openapi:
  method: POST
  route: /ext/bc/X#avm.getBlockByHeight
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Returns block at the given height.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Returns block at the given height.

<APIPage document={"./public/openapi/xchain.yaml"} operations={[{"path":"/ext/bc/X#avm.getBlockByHeight","method":"post"}]} webhooks={[]} hasHead={false} />

# avm.getHeight (/docs/rpcs/x-chain/chain/avm_getHeight)

---
title: avm.getHeight
full: true
_openapi:
  method: POST
  route: /ext/bc/X#avm.getHeight
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Returns the height of the last accepted block.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Returns the height of the last accepted block.

<APIPage document={"./public/openapi/xchain.yaml"} operations={[{"path":"/ext/bc/X#avm.getHeight","method":"post"}]} webhooks={[]} hasHead={false} />

# avm.getTx (/docs/rpcs/x-chain/chain/avm_getTx)

---
title: avm.getTx
full: true
_openapi:
  method: POST
  route: /ext/bc/X#avm.getTx
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Returns the specified transaction.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Returns the specified transaction.

<APIPage document={"./public/openapi/xchain.yaml"} operations={[{"path":"/ext/bc/X#avm.getTx","method":"post"}]} webhooks={[]} hasHead={false} />

# avm.getTxFee (/docs/rpcs/x-chain/chain/avm_getTxFee)

---
title: avm.getTxFee
full: true
_openapi:
  method: POST
  route: /ext/bc/X#avm.getTxFee
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Get the transaction fees of the network.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Get the transaction fees of the network.

<APIPage document={"./public/openapi/xchain.yaml"} operations={[{"path":"/ext/bc/X#avm.getTxFee","method":"post"}]} webhooks={[]} hasHead={false} />

# avm.getUTXOs (/docs/rpcs/x-chain/chain/avm_getUTXOs)

---
title: avm.getUTXOs
full: true
_openapi:
  method: POST
  route: /ext/bc/X#avm.getUTXOs
  toc: []
  structuredData:
    headings: []
    contents:
      - content: >
          Gets the UTXOs that reference a given address. If sourceChain is
          specified, 

          then it will retrieve the atomic UTXOs exported from that chain to the
          X Chain.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Gets the UTXOs that reference a given address. If sourceChain is specified, 
then it will retrieve the atomic UTXOs exported from that chain to the X Chain.


<APIPage document={"./public/openapi/xchain.yaml"} operations={[{"path":"/ext/bc/X#avm.getUTXOs","method":"post"}]} webhooks={[]} hasHead={false} />

# avm.issueTx (/docs/rpcs/x-chain/chain/avm_issueTx)

---
title: avm.issueTx
full: true
_openapi:
  method: POST
  route: /ext/bc/X#avm.issueTx
  toc: []
  structuredData:
    headings: []
    contents:
      - content: Send a signed transaction to the network.
---

{/* This file was generated by Fumadocs. Do not edit this file directly. Any changes should be made by running the generation command again. */}

Send a signed transaction to the network.

<APIPage document={"./public/openapi/xchain.yaml"} operations={[{"path":"/ext/bc/X#avm.issueTx","method":"post"}]} webhooks={[]} hasHead={false} />

# Welcome to the Course (/academy/avacloudapis)

---
title: Welcome to the Course
description: Learn about AvaCloud APIs and the AvaCloud SDK.
updated: 2024-09-03
authors: [owenwahlgren]
icon: Smile
---

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-banner/avacloudapis-ThOanH9UQJiAizv9gKtgFufXxRywkQ.jpg)
## Why Take This Course?

[AvaCloud APIs](https://developers.avacloud.io/introduction), built by [AvaCloud](https://avacloud.io/), provides Web3 developers with multi-chain data from Avalanche’s primary network and other Avalanche L1s. With the AvaCloud API, you can easily build products that utilize real-time and historical transaction data, transfer records, native and token balances, and various types of token metadata.

## Course Content

- [AvaCloud API Overview](/academy/avacloudapis/02-overview/01-about)
- [Environment Setup](/academy/avacloudapis/03-environment-setup/01-avacloud-account)
- [Build an ERC-20 Token Balance App](/academy/avacloudapis/04-erc20-token-balance-app/01-overview)
- [Build a Wallet Portfolio App](/academy/avacloudapis/05-wallet-portfolio-app/01-overview)
- [Build a Basic Block Explorer](/academy/avacloudapis/06-block-explorer-app/01-overview)

## Prerequisites

A general understanding of web development is required. While you won't need to write a lot of code, familiarity with key concepts is important.

- **TypeScript:** Understanding of common concepts, as all exercises will use TypeScript.
- **React:** Basic understanding of React is required, as all exercises will use React.
- **NextJS:** Basic understanding of NextJS is required, as all exercises will use NextJS.

## Learning Outcomes

By the end of this course, you will:

- Be familiar with the AvaCloud API including the [Data API](https://developers.avacloud.io/data-api/overview) and [Webhooks API](https://developers.avacloud.io/webhooks-api/overview).
- Learn how to use the [AvaCloudSDK](https://github.com/ava-labs/avacloud-sdk-typescript) to interact with [AvaCloud APIs](https://developers.avacloud.io/introduction).
- Build multiple web apps using the [AvaCloudSDK](https://github.com/ava-labs/avacloud-sdk-typescript).



# Course Completion Certificate (/academy/avalanche-fundamentals/get-certificate)

---
title: Course Completion Certificate
updated: 2024-09-09
authors: [ashucoder9]
icon: BadgeCheck
---

import CertificatePage from '@/components/quizzes/certificates';

You've made it to the end of the course. Let's check your progress and get your certificate.

<CertificatePage courseId="avalanche-fundamentals"/>

Thank you for participating in this course. We hope you found it informative and enjoyable!

# Welcome to the Course (/academy/avalanche-fundamentals)

---
title: Welcome to the Course
description: Learn about the basics of Avalanche.
updated: 2024-05-31
authors: [ashucoder9]
icon: Smile
---

Welcome to the Avalanche Fundamentals, an online course introducing you to the exciting world of the Avalanche technology! This course will provide you with a comprehensive understanding of the basic concepts making Avalanche unique.

Throughout, you'll learn the key features and benefits of the platform, plus how to build on it. You can also ask our expert instructors questions.

By the end of these courses, you'll have the knowledge and skills to leverage the power of blockchain technology for your own projects and applications. We're excited to have you join us on this journey and can't wait to see what you'll create with Avalanche!

## Prerequisites

This course is for people with some blockchain knowledge. Check out this [guide](/guides/what-is-a-blockchain) to review what a blockchain is.

Familiarity with the basic design of modern distributed software systems and common blockchain systems such as Bitcoin and Ethereum is also recommended. You do not need to know how to write code to successfully complete this course.

Having these prerequisites will help you better understand the course material and engage in the activities. If you don't know whether you have the necessary foundation for this course, please contact the course instructor for guidance.


## Learning Outcomes

By the end of this course, you will:

- Understand how Avalanche consensus works and what makes it different.
- Understand how Avalanche L1s enable scalability, customizability, and independence.
- Understand the Primary Network, a special Avalanche L1, and how to interact with it.
- Understand how Virtual Machines enable developers to create more optimized and capable blockchain systems and to tackle completely new use cases unachievable with previous solutions.

You can evaluate your own understanding of the material through quizzes and claim a certificate for successful completion at the end.

Overall, this course aims to provide a foundational understanding of Avalanche. By completing it, you will be better prepared to take on more advanced courses focused on building on Avalanche.

# Course Completion Certificate (/academy/blockchain-fundamentals/get-certificate)

---
title: Course Completion Certificate
updated: 2025-30-10
authors: [ashucoder9]
icon: BadgeCheck
---

import CertificatePage from '@/components/quizzes/certificates';

You've made it to the end of the course. Let's check your progress and get your certificate.

<CertificatePage courseId="blockchain-fundamentals"/>

Thank you for participating in this course. We hope you found it informative and enjoyable!

# Welcome to the Course (/academy/blockchain-fundamentals)

---
title: Welcome to the Course
description: Learn about the basics of blockchain technology.
updated: 2025-10-30
authors: [ashucoder9]
icon: Smile
---

Welcome to the Blockchain Fundamentals, an online course introducing you to blockchain! This course will provide you with a comprehensive understanding of the basic concepts of blockchains.

By the end of these courses, you'll have the knowledge and skills to leverage the power of blockchain technology for your own projects and applications. We're excited to have you join us on this journey and can't wait to see what you'll create with Avalanche!

## Course Content

We will cover the following topics in this course:

- What is a Blockchain?
- Deep Dive into Payments
- Cryptography: Signature schemes
- Consensus Mechanisms
- Sybil Defense Mechanisms
- Smart contracts
- Tokenomics
- Virtual Machines

## Prerequisites

Anyone can take this course!

## Learning Outcomes

By the end of this course, you will have a good understanding of the basic concepts of blockchain technology.

You can evaluate your own understanding of the material through quizzes and claim a certificate for successful completion at the end.



# Decentralization (/academy/blockchain-fundamentals/xx-decentralization)

---
title: Decentralization
description: TBD
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---


## Moving from a centralized Entity to a Collective of Validators

Blockchain systems achieve decentralization through the use of a network of validators, sometimes referred to as nodes, miners, or stakers, depending on the underlying consensus mechanism. Validators are responsible for verifying and securing transactions, maintaining the integrity of the blockchain, and ensuring that the system remains decentralized and trustless. Decentralization is achieved by distributing the responsibility of maintaining the network across numerous independent participants.

Decentralization in blockchain is achieved through a network of validators. These are independent entities that run the blockchain software, perform computations, and ensure the integrity of the blockchain. Here’s how it works:

Computation Execution: Each validator independently performs the same computation. For example, let's consider a simple computation: 5 + 3.
Consensus Process: After performing the computation, validators share their results with each other. They then use a process called consensus to agree on the correct result. You can think of it as a election, where all validators vote on the correct answer.
The consensus process ensures that all validators reach an agreement on the correct result, given that the majority is honest. This agreement is crucial for maintaining the integrity and security of the blockchain. If a validator tries to cheat or provide an incorrect result, the other validators will detect the discrepancy, and the cheating validator will be penalized.

# Tokens (/academy/blockchain-fundamentals/xx-tokens)

---
title: Tokens
description: TBD
updated: 2024-05-31
authors: [martineckardt]
icon: Notebook
---

Tokens are a concept that existed in societies for a long time. 

Tokens can be used to represent value. The most common valuable tokens we use every day are fiat currencies, like the US dollar. But there are also other kinds of tokens, such as points or miles in loyalty programs. Today we can also tokenize other assets, such as property titles.

## Fungible Tokens

Fungibility means that different tokens can be considered of equal value. Let's take for example two one dollar bills. Most people will not care if they get one or the other. They both offer the same utility. 

## Non-Fungible Tokens

Non-fungible tokens are not considered equal. The most prominent use cases are Art-NFTs. While the tokens may follow a standard of how they can be transfered, they may not be interchangeable. Two pieces of art may have very different values.

# Welcome to the Course (/academy/customizing-evm)

---
title: Welcome to the Course
description: Learn how to customize the Ethereum Virtual Machine.
updated: 2024-09-27
authors: [ashucoder9, owenwahlgren]
icon: Smile
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

## Why take this Course?

A significant innovation in blockchain is the development of multi-chain systems, such as Avalanche, which provide a significant improvement in scalability, interoperability, and flexibility. At the core of these multi-chain systems is the ability to run multiple blockchains powered by different virtual machines simultaneously. Each VM of a chain is optimized for specialized use cases, thereby boosting the network's overall performance.


Configuring and modifying the EVM is an efficient way to create a specialized virtual machine, as it allows developers to build upon years of active community work and leverage the extensive ecosystem surrounding the EVM, including wallets, explorers, and development frameworks.
## Course Content

<Steps>
<Step>

### EVM Basics & Precompiles

In the first section of the course we will go through some basic concepts of the EVM, such as the account-based model, keys, addresses, transactions, and blocks. Furthermore, we will explain what a precompile is and show you how to interact with a precompile on the Fuji testnet.
</Step>
<Step>
### Development Environment Setup

We will explore various ways to set up a development environment for building customized EVMs. You'll learn about GitHub Codespaces and Development Containers (`.devcontainer`). If you choose a local setup, you'll install a code editor, the Go language, configure your shell, and install additional dependencies.
</Step>
<Step>
### Hands-On Exercises

The following sections contain hands-on exercises where you customize the EVM. The difficulty of the customizations will increase from section to section. Find out more about each exercise by clicking its name below:

<Accordions>
    <Accordion title="Create your own EVM Blockchain">

    - Learn how the Avalanche Network Runner Works
    - Create a your own Avalanche Network
    - Create an EVM Blockchain on your network 
    - Connect Core Wallet to your blockchain

    </Accordion>
    <Accordion title="Customize the EVM with chainConfig">

    - Learn what the genesis block is and how the data is structured
    - Create a custom gas fee structure for your blockchain
    - Define the initial token allocation at launch
    - Configure pre-installed precompiles
    - Create the blockchain and connect to it

    </Accordion>
    <Accordion title="Build a Hash Function Precompile">

    Learn about the basic building blocks of a precompile by building a precompile for the md5 hash function:

    - Generate boilerplate code for the precompile from a solidity interface
    - Learn how to unpack inputs and pack outputs into 32 byte arrays
    - Configure and register your md5 precompile
    - Create a new blockchain, connect to it and interact with your precompile

    </Accordion>
    <Accordion title="Build a Calculator Precompile">

    Learn to build more complex precompiles by building a calculator precompile and master the following skills in addition to the previous section:
    
    - Unpack multiple inputs and pack multiple outputs into 32 byte arrays
    - Set a gas cost for your precompile
    - Add go tests for your precompile

    </Accordion>
    <Accordion title="Build a Counter Stateful Precompile">

    Learn to build stateful precompiles by building a counter precompile and master the following skills in addition to the previous sections:
    
    - Read from and write to the EVM state
    - Define the initial state in the precompileConfig
    - Add solidity tests for your precompile

    </Accordion>
    <Accordion title="Build a Permissioned Precompile (Coming Soon)">

    Learn to build permissioned precompiles by building a XXX precompile and master the following skills in addition to the previous sections:
    
    - Add permissions to only allow certain addresses to interact with the precompile 
    - Define the initial permissions in the precompileConfig
    - Change the permissions on the fly

    </Accordion>

</Accordions>
</Step>
</Steps>

## Prerequisites

### Avalanche

This course is intended for people with a solid understanding of the basic concepts of Avalanche. You should be familiar with these concepts:

1. **Virtual Machines**: What they are and what VM customization means
2. **Blockchains**: What the components are of a blockchain and how they interact, specifically how Avalanche L1s leverage precompiles.

If some of this is not clear, I strongly recommend taking the [Avalanche Fundamentals](/academy/avalanche-fundamentals) and [Multi-Chain Architecture](/academy/multi-chain-architecture) courses first.

### Coding

You will need a general understanding of software development. You won't have to write a lot of code, but you will have to be able to understand some. Therefore, we recommend:

1. **Solidity**: Basic knowledge, familiarity with types and interfaces. Familiarity with Foundry will help in advanced sections. 
2. **Go**: You don't necessarily need to know Go, but should have some experience with an advanced object-oriented and typed language (C, C++, Java, Typescript)
3. **Testing**: It will help you in later sections if you are generally familiar with the concept of unit testing

## Learning Outcomes

By the end of this course, students will be able to:

- Understand what Precompiles are and when to use them.
- Understand how developing precompiles allows developers to create more optimized and capable blockchain systems, enabling them to address entirely new use cases that were previously unattainable.
- Apply the knowledge gained in the course by building multiple precompiles


![](/wolfie/wolfie-hack.png)


# Welcome to the course (/academy/encrypted-erc)

---
title: Welcome to the course
description: Learn about the encrypted-ERC (eERC) token standard from AvaCloud.
updated: 2025-07-21
authors: [alejandro99so]
icon: Lock
---

Welcome to the **eERC Token Standard** course! This course is designed to give you a deep understanding of encrypted ERC (eERC), a privacy preserving ERC-20 like token standard developed by AvaCloud, enabling confidential transactions on EVM-compatible blockchains. By the end of this course, you will understand the privacy limitations of traditional token standards, how eERC solves them, and how to create and integrate your own private tokens.

## Course Content

### 1. What is a Digital Asset?
- **Standards**: ERC-20, ERC-721, ERC-1155
- **Current Uses**: How companies, DeFi protocols, and projects are using them today.
- **Limitations**: Challenges companies face when trying to adopt these standards (scalability, privacy, compliance).

### 2. Real Privacy
- **How Private is the Blockchain?**: Transparency vs confidentiality.
- **Compliance**: Why regulatory alignment matters for privacy tokens.
- **Necessities Solved with Privacy**: Situations where privacy is essential (e.g., sensitive transactions, enterprise use).

### 3. Encrypted Tokens
- **What Kind of Privacy Does eERC Provide?**: Hidden balances, confidential transfers.
- **Comparison: ERC-20 vs eERC**: Feature-by-feature breakdown.
- **Technology Behind eERC**: Zero-knowledge proofs and homomorphic encryption.

### 4. Usability of eERC
- **Standalone vs Converter Contract**: When to use each mode.
- **Use Cases**: From DeFi to regulated financial institutions.

### 5. eERC Contracts Flow
- **Step-by-Step**: Creating your own eERC token and considerations.
- **Kinds of ZKProof to Use**: Selection criteria based on use case.
- **User Flow**: How to interact with eERC as an end user.

---

## Prerequisites

Before starting this course, you should have:

### Blockchain Fundamentals
Familiarity with EVM-based blockchains and ERC token standards.

### Development Tools
Basic knowledge of Solidity and comfort using TypeScript will help, especially when working with the Privacy functions.

---

## Learning Outcomes

By the end of this course, you will:

- Understand the **purpose and innovation** behind the eERC standard.
- Compare **traditional ERC standards** with encrypted ERC for privacy and compliance.
- Identify the **key benefits, architecture, and technical underpinnings** of eERC.
- Differentiate between **Standalone** and **Converter** implementation modes.
- Recognize **real-world use cases** where privacy and auditability are essential.
- Create and deploy your own **eERC token** following a step-by-step process.
- Understand how to **interact with eERC as a user** in different scenarios.


# Course Completion Certificate (/academy/icm-chainlink/certificate)

---
title: Course Completion Certificate
updated: 2024-10-11
authors: [owenwahlgren]
icon: BadgeCheck
---

import CertificatePage from '@/components/quizzes/certificates';

You've made it to the end of the course. Let's check your progress and get your certificate.

<CertificatePage courseId="interchain-messaging"/>

Thank you for participating in this course. We hope you found it informative and enjoyable!

# Welcome to the course (/academy/icm-chainlink)

---
title: Welcome to the course
description: Enable Chainlink services on L1 networks that do not have direct Chainlink support.
updated: 2024-05-31
authors: [martineckardt]
icon: Smile
---

In this course, you will learn how to integrate your own blockchain with the Chainlink services that are deployed on C-chain. To do this, we will use Avalanche Interchain Messaging and Chainlink VRF.

## Why Take This Course?

As the blockchain ecosystem grows, developers require robust tools to build secure, scalable, and innovative applications. Chainlink provides a suite of decentralized services, including VRF (Verifiable Random Function), Automation, Chainlink Functions, and CCIP (Cross-Chain Interoperability Protocol), to empower developers in creating high-performance, trustless applications. These services are not integrated by default on Avalanche L1 chains. However, Avalanche’s Interchain Messaging (ICM) enables developers to consume Chainlink services, typically available on the C-Chain, directly within their own L1 environments.

This course equips you with the knowledge to integrate all Chainlink services into your Avalanche L1 blockchain. You will start with Chainlink VRF and progressively expand to advanced features like Automation for task scheduling, Functions for off-chain data computations, and CCIP for bridging data between Ethereum and Avalanche. We suggest you to revisit this course as we will keep on adding new content.

## Course Content

### Introduction

Overview of Chainlink services and their role in decentralized applications. Importance of integrating these tools into Avalanche L1 chains.

### Chainlink VRF

Explanation of VRF and its use cases. Deploying VRF on Avalanche L1 and verifying randomness.

### Chainlink Functions

Overview of off-chain computation and API integrations. Implementing Functions for real-time data feeds.

### Chainlink Automation

Using Automation for task scheduling. Examples include automated smart contracts and dynamic pricing.

### Chainlink CCIP

Bridging data and assets between Ethereum and Avalanche L1. Practical applications such as cross-chain governance and token transfers.


## Prerequisites

Avalanche Interchain Messaging (ICM): A solid understanding of Avalanche’s ICM protocol is essential. You should have completed the ICM course, which covers:
- The fundamentals of cross-chain communication in Avalanche
- Message formats and flows
- Security techniques for interchain messaging

Blockchain and Development Knowledge
- Solidity: Familiarity with the language’s key concepts, especially those related to smart contract interactions and randomness.
- Oracles: While we will cover the basic components of Chainlink's VRF, having a sense of oracles is desirable.

If any of this is unclear, we strongly recommend taking the Avalanche Interchain Messaging course first.

## Learning Outcomes

By the end of this course, students will:

- Understand the mechanics of Chainlink VRF and other Chainlink Services and its significance in decentralized applications.
- Gain proficiency in setting up Avalanche L1 chains with Chainlink services enabled.
- Integrate Chainlink VRF with Avalanche ICM for secure cross-chain randomness.
- Use Chainlink functions for Off-chain data integration with on-chain logic.
- Automated smart contract operations
- Cross-Chain communication with ecosystems outside Avalanche trough Chainlink's CCIP
- Apply best practices to ensure reliability, security, and cost-efficiency in their applications.

This course prepares developers to leverage Chainlink’s powerful suite of tools for building next-generation blockchain solutions on Avalanche L1.


# Course Completion Certificate (/academy/interchain-messaging/certificate)

---
title: Course Completion Certificate
updated: 2024-10-11
authors: [owenwahlgren]
icon: BadgeCheck
---

import CertificatePage from '@/components/quizzes/certificates';

You've made it to the end of the course. Let's check your progress and get your certificate.

<CertificatePage courseId="interchain-messaging"/>

Thank you for participating in this course. We hope you found it informative and enjoyable!

# Welcome to the course (/academy/interchain-messaging)

---
title: Welcome to the course
description: Learn about Interchain Messaging, the interoperability protocol of Avalanche.
updated: 2025-05-13
authors: [martineckardt, nicolasarnedo]
icon: Smile
---

In this course, you will learn how to build cross-L1 Solidity dApps with Interchain Messaging and Avalanche Warp Messaging.

## Why Take This Course?

A significant innovation in blockchain is the development of multi-chain systems, like Avalanche, which provide a significant improvement in scalability, interoperability, and flexibility. At the core of these multi-chain systems is the ability to run multiple blockchains that communicate. Each chain's VM is optimized for specialized use cases, thereby boosting the network's overall performance.

Cross-chain communication is a crucial building block of multi-chain systems. Utilizing Interchain Messaging and Avalanche Warp Messaging is an incredible easy way to build cross-L1 dApps, since developers can build on top an extensive and audited development framework. 

## Course Content

Below you can find a 30 minute recording of a presentation about Avalanche Warp Messaging and Teleporter. This summarizes the content of the first chapters:

<YouTube id="N6F7D4Hb87c"/>

### Interoperability 

In the first section, we cover some basic concepts of interoperability in multi-chain systems. You will learn about examples of interoperability between blockchains and the terms "source," "destination," and "message."

### Avalanche Interchain Messaging

In this section, we learn what Avalanche Interchain Messaging is and what is abstracted away from the general dApp developer. You will also build your first cross-L1 dApps.

### Securing Cross-Chain Communication

In this section, we look at techniques to secure cross-chain communication. We dive into signature schemes, multi-signature schemes, and the BLS multi-signature scheme.

### Avalanche Interchain Messaging Protocol

Avalanche blockchains can natively interoperate between one another using AWM. You will learn about the AWM message format and how the message flow works.

## Prerequisites

### Avalanche

This course is meant for people with a solid understanding of the basic concepts of Avalanche. You should be familiar with these concepts:

- **Virtual Machines:** What they are and what VM customization means
- **Avalanche L1s & Blockchains:** What the difference between a VM, Blockchain, and an Avalanche L1 is

If any of this is unclear, we strongly recommend taking the Avalanche Fundamentals and Multi-Chain Architecture courses first.

### Software Development

You will need a general understanding of Software Development. You won't have to write a lot of code, but you will have to understand some. Therefore, we recommend:

- **Solidity:** Familiarity with most concepts of the language. All exercises will mainly consist of writing cross-subnet dApps in Solidity.
- **Docker:** The advanced exercises in the latter part of the course will occur in contained environments for easy setup. It will help if you're generally familiar with the concept of containerization, docker, and docker compose.
- **Testing:** Having some experience or familiarity with unit testing is ideal.

## Learning Outcomes

By the end of this course, students will:

- Understand the challenges of cross-chain communication
- Know what separates Avalanche Warp Messaging from other cross-chain communication protocols
- Understand the differences between Avalanche Warp Messaging and Teleporter
- Apply their knowledge by building cross-Avalanche L1 dApps, such as asset bridges

Overall, this course aims to provide an advanced understanding of Teleporter. By completing this course, students will be better prepared to build advanced cross-Avalanche L1 blockchain applications.

# Dapp's and L1's (/academy/l1-native-tokenomics/dappVsL1)

---
title: Dapp's and L1's
description: Listing tokenomics and infrastructure requirements to understand whether creating an L1 is neccessary for your business-case
updated: 2025-08-21
authors: [nicolasarnedo]
icon: Microscope
---

So far you have learnt a lot of the basics around blockchains, how they work, architecture, consensus mechanism's, smart contract's, and also Avalanche-specific concepts. Before reading through this course however, now is a good moment to reflect on whether your use-case requires it's own L1 and native tokenomics.

In order to do this, there are several economic factors which will dictate if we should deploy an application on a public blockchain (Avalanche C-chain, Ethereum) or create our own custom Layer 1 (L1) blockchain. Let's look into them...

### Transaction Volume and Value
If your application processes a high volume of low-value transactions, a custom L1 may be more cost-effective in the long run. Conversely, if your application handles only a few high-value transactions, the cost savings may not justify the complexity of running a separate L1.

### Fee Stability
On a public blockchain, you are at the mercy of network-wide fee fluctuations. With a custom L1, you can ensure fee stability, which is crucial for budgeting and long-term planning.

### Data Control and Customization
You can control who interacts with your application equally when deploying an app to a public chain vs on your own L1, but if you want to have more control on the data; who can deploy smart contracts, isolating your data for compliance/KYC reasons, or who can validate transactions, then you will absolutely need an L1.

If you do have to create an L1 - the primary cost of running it is the infrastructure required to support the validator set. Once you establish an appropriate number of validators based on your security requirements, the operational costs become mostly fixed. These costs are independent of the number and complexity of the transactions processed on your chain, providing predictable financial outlays as your application scales.

### Token Location
Choose based on where your security and token economics must live. If your token must be native to the protocol (gas token, staking/slashing, fee burn/distribution, protocol‑level issuance or supply rules) and you need validator/permissioning guarantees, a custom L1 is appropriate. If your token’s utility is application‑level (access, rewards, governance without base‑fee mechanics) and you benefit from public‑chain security and liquidity, a dApp with an ERC‑20 on a public chain is the simpler path. Decide whether the required guarantees are protocol‑layer (L1) or app‑layer (public chain).

Launching a blockchain application on a public permissionless blockchain or spinning up your own L1 on Avalanche is a decision that depends heavily on your application's transaction profile and economic model. Ultimately, the decision should be driven by a careful analysis of your transaction patterns, user experience goals, what will be the token utilty and the potential for fee volatility in public networks. By weighing these factors, you can make an informed decision that aligns with your application's long-term success.

#### *Use-case Example*

*Gaming application where users frequently make micro-transactions, high transaction fees on a public blockchain could be a significant barrier to user retention. By deploying your own L1, you can minimize or even eliminate these fees, thereby enhancing the user experience and driving higher engagement. This is particularly relevant for applications that target mainstream audiences, where a seamless and cost-effective user experience is paramount.*

**Live Proof**: [Off The Grid](https://gunzillagames.com/en/) uses a dedicated Avalanche L1 to power a player‑driven economy with on‑chain item ownership (NFTs) and currency ($GUNZ).

# Welcome to the Course (/academy/l1-native-tokenomics)

---
title: Welcome to the Course
description: Learn about the L1 Native Tokenomics
updated: 2025-08-21
authors: [nicolasarnedo]
icon: Smile
---

Welcome to the **L1 Native Tokenomics** course! This course is designed to give you a deep understanding of how to create and manage native tokens on your own Avalanche L1 blockchain. 

By the end of this course, you will have practical skills in designing tokenomics, configuring native token allocation, and leveraging precompiles to create powerful token economies.

## Prerequisites

Before starting this course, you should have completed the [Blockchain Fundamentals](/academy/blockchain-fundamentals) and [Avalanche Fundamentals](/academy/avalanche-fundamentals) courses of the [Avalanche Developers Academy](https://build.avax.network/academy#:~:text=Choose%20Your%20Learning%20Path) learning tree.

## Learning Outcomes

By the end of this course, you will:

- **Understand Token Fundamentals**: Gain deep insights into what tokens are, their differences, and the implications of creating native tokens versus ERC20 tokens.
- **Master Native Token Creation**: Learn how to create custom native tokens and understand when you need them versus when ERC20 tokens are sufficient.
- **Leverage Precompiles**: Understand how to use the Native Minter and Fee Config Precompiles to create powerful tokenomics.
- **Design Token Distribution**: Create effective vesting schedules, bonding curves, and airdrop strategies for your native tokens.
- **Implement Governance**: Develop governance structures including DAOs and quadratic voting models for decentralized decision-making.

But before diving into the technical implementation, we've included two essential think pieces to help you make informed decisions:

**Essential Reading**: [Dapp vs L1](/academy/l1-native-tokenomics/dapp-vs-l1) - A critical analysis to determine whether your use case actually requires its own L1 with native tokenomics, or if deploying on an existing chain would be more appropriate.

**Highly Recommended**: [Token Ownership](/academy/l1-native-tokenomics/token-ownership) - Not strictly necessary for implementation, this deep dive into the philosophical and practical aspects of token ownership will give you a much richer understanding of the underlying concepts at play in tokenomics design.


# Token Ownership (/academy/l1-native-tokenomics/token-ownership)

---
title: Token Ownership
description: Everything you need to know about token ownership on blockchains
updated: 2025-08-21
authors: [nicolasarnedo]
icon: Key
---

## A Short History and Why It Matters

Token ownership means recording who controls a digital asset on a public ledger, enforced by cryptography and consensus rather than by legal registries alone. It unlocks portable, programmable, and verifiable property rights for anything that can be represented in bits.

### From Scarcity to Programmability

- Bitcoin (2009) solved digital scarcity and established provable, bearer‑style ownership “by code.”
- Ethereum (2015) generalized ownership with smart contracts, enabling tokens: programmable representations of value, access, or rights. The 2014–2018 wave of token sales showed how ownership could be distributed globally without intermediaries—sometimes as utility access, sometimes (mistakenly) as implied equity. The lesson: tokens coordinate, but value capture must be designed, not assumed.

### What “Ownership” Means On‑Chain

On blockchains, ownership is:
- Verifiable: anyone can audit balances and provenance.
- Portable: assets move across apps and wallets with private keys.
- Programmable: rights can encode governance, access, royalties, staking, or fee distribution.
- Composable: tokens integrate with DeFi, marketplaces, and tooling by common standards.

### Token Classes at a Glance

<img src="/common-images/l1-native-tokenomics/L1NT-TokenClassification.png" alt="Classification of crypto assets" style={{ maxWidth: '100%', borderRadius: '8px' }} />

At a high level:
- Fungible tokens (e.g., ERC‑20) track interchangeable units (balances, payments, governance power).
- Non‑fungible tokens (e.g., ERC‑721) track unique items and their provenance (collectibles, credentials, rights).
- Hybrids and multi‑tokens (e.g., ERC‑1155) combine both models for efficient gaming/commerce flows.

### Why Tokenized Ownership Works

Tokens drastically reduce friction to distribute and align ownership. Like equity, they can motivate long‑term contribution; unlike equity, they are programmable (e.g., automatic reward streams, on‑chain voting) and readily tradable. But not every token confers the same rights: designs differ in value capture (fee burns, staking rewards, access discounts), transferability, and governance—and must consider regulation.

### Looking Ahead

As you move into native tokens and ERC‑20s next, keep this lens: token ownership is a coordination primitive. Good designs clearly define what is owned (rights), how value accrues (mechanics), and how ownership changes hands (standards and controls). With those pillars, tokens become reliable building blocks for open, interoperable economies.

# Course Completion Certificate (/academy/interchain-token-transfer/certificate)

---
title: Course Completion Certificate
updated: 2024-10-11
authors: [owenwahlgren]
icon: BadgeCheck
---

import CertificatePage from '@/components/quizzes/certificates';

You've made it to the end of the course. Let's check your progress and get your certificate.

<CertificatePage courseId="interchain-token-transfer"/>

Thank you for participating in this course. We hope you found it informative and enjoyable!

# Welcome to the Course (/academy/interchain-token-transfer)

---
title: Welcome to the Course
description: Learn about sending assets to another L1s with Avalanche Interchain Token Transfer.
updated: 2024-05-31
authors: [ashucoder9]
icon: Smile
---

In this course, you will learn how to transfer assets across multiple Avalanche blockchains with Avalanche Interchain Token Transfer ICTT.

## Why Take This Course?

A significant innovation in blockchain is the development of multi-chain systems, like Avalanche, which provide a significant improvement in scalability, interoperability, and flexibility. At the core of these multi-chain systems is the ability to run multiple blockchains that communicate. Each chain's VM is optimized for specialized use cases, thereby boosting the network's overall performance.

Cross-chain communication is a crucial building block of multi-chain systems. Utilizing Avalanche Interchain Messaging and Interchain Token Transfer is an incredibly easy way to build cross-Avalanche L1 dApps, since developers can build on top of an extensive, audited development framework. 

Transfering tokens between multiple chains is a common use case in multi-chain systems. This course will help you understand how to transfer assets between multiple Avalanche blockchains using the Avalanche Interchain Token Transfer protocol.

<Callout>
This course focuses on using the existing testnet chains (Fuji C-Chain, Echo, and Dispatch). If you want to create your own L1 blockchain, please refer to the [Creating an L1](/academy/avalanche-fundamentals/04-creating-an-l1/01-creating-an-l1) course.
</Callout>

<Callout>
Since Interchain Token Transfer relies on Interchain Messaging (ICM), you must run your own relayer to enable cross-chain communication. Follow the [Running a Relayer](/academy/interchain-messaging/09-running-a-relayer/01-relayer-introduction) course to set up your relayer.
</Callout>

## Course Content

### Getting Started with Interchain Token Transfer

In this section, you will learn how to use our Interchain Token Transfer toolbox to perform cross-chain operations. We'll guide you through the process of using our user-friendly interface to deploy contracts, create bridges, and transfer assets across the testnet chains (Fuji C-Chain, Echo, and Dispatch).

### Tokens and Token Types

In this section, you will learn about the different types of tokens that can be transferred between Avalanche blockchains. We will cover ERC-20 and native tokens and how to deploy and transfer them using our toolbox. Furthermore, you will learn what wrapped native tokens are and how they can be used to transfer assets between chains.

### Token Bridging

Next we will talk about the high level concepts of token bridging and demonstrate how to use our toolbox to create and manage bridge contracts for cross-chain transfers between the testnet chains.

### Interchain Token Transfer Architecture

In this chapter we will look at the design of Avalanche Interchain Token Transfer. You will learn about the file structure of the contracts and the concepts of the token home and token remote.

### ERC-20 to ERC-20 Bridge Implementation

You will learn how to use our toolbox to deploy ERC-20 tokens and create bridges to transfer them between the testnet chains.

### Multi-Chain Token Operations

Here you will learn about the concept of multi-hops and how to use our toolbox to bridge tokens between multiple testnet chains.

### Native to ERC-20 Bridge Implementation

In this chapter you will learn how to use our toolbox to bridge a native token as an ERC-20 token to another testnet chain.

### Send and Call Operations

In this chapter you will learn how to use our toolbox to call smart contracts with the tokens after sending them to another testnet chain.

### Cross-Chain Token Swaps

In this chapter you will learn how to perform cross-chain token swaps between the testnet chains using our toolbox.

## Prerequisites

### Avalanche Knowledge

This course is intended for people with knowledge about Cross-Chain communication protocols, and a solid understanding of the basic concepts of Avalanche. You should be familiar with these concepts:

1. Avalanche Architecture: Be familiar with Avalanche blockchains.
2. Interchain Messaging: Know how to communicate between two Avalanche blockchains with ICM. 

If some of this is not clear, we strongly recommend taking the Avalanche Fundamentals, Multi-Chain Architecture, and Interchain Messaging courses first.

### Software Development

You will need a general understanding of how to use Web3 applications. We recommend:

1. Basic understanding of how to use Core Wallet
   - Download from [core.app](https://core.app)

2. Test tokens for development
   - **Recommended:** Create a [Builder Hub account](https://build.avax.network/login) and connect your wallet to receive testnet tokens automatically
   - **Alternative:** Use external faucets like [core.app/tools/testnet-faucet](https://core.app/tools/testnet-faucet/?subnet=c&token=c) with code `avalanche-academy`

3. Understanding of token standards (ERC-20, etc.)

## Learning Outcomes

By the end of this course, you will:

- Understand what Avalanche Interchain Token Transfer is and when to use it.
- Understand the different options for transferring assets between multiple chains.
- Be able to deploy tokens and create bridges using our toolbox.
- Be able to perform cross-chain token transfers between testnet chains using our toolbox.
- Apply the knowledge gained in the course by enabling assets to be transferred between multiple Avalanche blockchains.

# Course Completion Certificate (/academy/multi-chain-architecture/certificate)

---
title: Course Completion Certificate
updated: 2024-10-11
authors: [owenwahlgren]
icon: BadgeCheck
---

import CertificatePage from '@/components/quizzes/certificates';

You've made it to the end of the course. Let's check your progress and get your certificate.

<CertificatePage courseId="multichain-architecture"/>

Thank you for participating in this course. We hope you found it informative and enjoyable!

# Welcome to the Course (/academy/multi-chain-architecture)

---
title: Welcome to the Course
description: Learn about the Multi-Chain Architecture.
updated: 2024-06-28
authors: [usmaneth]
icon: Smile
---

Are you ready to dive deeper into the fascinating world of Avalanche? This course will equip you with a comprehensive understanding of Avalanche's Multi Blockchain architecture, along with the practical skills required to create and manage custom blockchains.

Ideal for people familiar with the basics of Avalanche, this course will unlock the potential of creating custom blockchains. We will explore the various components and key concepts of the Custom Blockchain architecture, empowering you to fully leverage its benefits.

Throughout this course, you will gain hands-on experience by utilizing the Avalanche Command Line Interface (Avalanche CLI) to create your own custom blockchains and run them locally. You will explore different variations and configurations to learn the versatility and advantages of custom blockchains. Additionally, you will interact with the local instances using the Core Wallet, further enhancing your practical skills.

Let's get started exploring the power of Avalanche Custom Blockchains.

## Presentation

Below you can find a recording of a presentation about the Multi-Chain Architecture of Avalanche.

<YouTube id="Yy7_ZiBWXWQ"/>

## Prerequisites

This course is for people who understand the Avalanche basics. If you are not familiar with Avalanche Consensus, Virtual Machines, blockchains in Avalanche, or Avalanche Custom Blockchains, we strongly recommend taking our [Avalanche Fundamentals](/academy/avalanche-fundamentals) course first.

## Learning Outcomes

In this course you will learn:

- The benefits of Avalanche Custom Blockchains
- How to use Avalanche CLI to create and run custom blockchains locally
- How to interact with Avalanche L1s using Core Wallet



# Course Completion Certificate (/academy/permissioned-l1s/certificate)

---
title: Course Completion Certificate
description: Get your completion certificate for the Permissioned L1s course
updated: 2025-03-19
authors: [nicolasarnedo]
icon: BadgeCheck
---

import CertificatePage from '@/components/quizzes/certificates';

You've made it to the end of the course! Let's check your progress and get your certificate.

<CertificatePage courseId="permissioned-l1s"/>

Thank you for participating in this course. We hope you found it informative and enjoyable!

# Welcome to the Course (/academy/permissioned-l1s)

---
title: Welcome to the Course
description: Learn about L1 Validator Management for Permissioned Blockchains
updated: 2025-07-15
authors: [nicolasrnedo]
icon: Smile
---

## Permissioned L1s 

Welcome to the **Permissioned L1s** course! This course is designed to give you a deep
understanding of configuring, launching and maintaining permissioned L1s on Avalanche. By the end of this course, you will have
practical skills in deploying an L1 and managing the validator set in a Proof of Authority (PoA)
network.

## Video

<YouTube id="xgx6VzdR974" params="start=365"/>

### What You'll Learn

This comprehensive course will walk you through:

- **Introduction** - P-Chain review, how Validator Manager Contracts use ICM & commonlys used Proxy Patterns
- **Proof of Authority** - Understanding permissioning types for blockchains, what Proof of Authority is and the Validator Manager contract structure
- **Create an L1** - Creating a Subnet, diving deep into the Transparent Proxy pattern, understanding genesis pre-deployed contracts and creating your L1 (recommended to first have created an L1 in the [Avalanche Fundamentals course](/academy/avalanche-fundamentals))
- **Validator Manager Deployment** - Deploying and configuring the Validator Manager Contract (VMC) on your new L1
- **Validator Manager Operations** - Adding, changing weights and removing validators
- **Coming Soon... Multi-Sig Setup for PoA** - Implementing secure multi-signature governance with Safe/Ash wallets
- **Coming Soon... Private L1s** - Configuring validator-only access and RPC node restrictions

### Let's Get Started!

Each section builds upon previous knowledge, so we recommend completing the course in order.

Happy learning and building!

# Course Completion Certificate (/academy/permissionless-l1s/certificate)

---
title: Course Completion Certificate
description: Get your completion certificate for the Permissioned L1s course
updated: 2025-03-19
authors: [nicolasarnedo]
icon: BadgeCheck
---

import CertificatePage from '@/components/quizzes/certificates';

You've made it to the end of the course! Let's check your progress and get your certificate.

<CertificatePage courseId="permissioned-l1s"/>

Thank you for participating in this course. We hope you found it informative and enjoyable!

# Welcome to the Course (/academy/permissionless-l1s)

---
title: Welcome to the Course
description: Learn about L1 Validator Management for Permissionless Blockchains
updated: 2025-01-15
authors: [nicolasarnedo]
icon: Smile
---

## Permissionless L1s 

Welcome to the **Permissionless L1s** course! This course is designed to give you a deep understanding of configuring, launching and maintaining permissionless L1s on Avalanche. 

By the end of this course, you will have practical skills in deploying an L1 with Proof of Stake (PoS) consensus and managing the validator set in a permissionless
network.


### Prerequisites

Before starting this course, we recommend completing:
- [L1 Native Tokenomics](/academy/l1-native-tokenomics) - Understanding tokenomics fundamentals
- [Permissioned L1s](/academy/permissioned-l1s) - Foundation in L1 validator management

If you just completed these recently, you can go ahead and skip the [Review chapter](). If not, we recommend giving it a read, it will cover:

- P-Chain fundamentals
- Multi-Chain Architecture
- Permissioned L1s  
- Native Tokenomics

### What You'll Learn

This comprehensive course will walk you through:

- **Proof of Stake** - Understanding PoS consensus, staking token selection, and liquid staking considerations
- **Necessary Precompiles** - Native Minter and Reward Manager precompiles for tokenomics
- **Basic Setup** - Deploying Validator Manager Contract, upgrading proxy, and initializing validator configuration
- **Staking Manager Setup** - Deploying and configuring staking managers for native token staking
- **Staking Manager Operations** - Adding, changing weights, removing validators, and handling delegation
- **Node Licenses** - Understanding validator licensing and real-world examples

### Let's Get Started!

Each section builds upon previous knowledge, so we recommend completing the course in order.

Happy learning and building!

# Welcome to the course (/academy/solidity-foundry)

---
title: Welcome to the course
description: Learn the basics about programming Smart Contracts in Solidity for an EVM Blockchain
updated: 2024-05-31
authors: [Andrea Vargas]
icon: Smile
---

In this course, you will learn how to build Solidity dApps on Avalanche.

## Why Take This Course?

A significant innovation in blockchain is the development of multi-chain systems, like Avalanche, which provide a significant improvement in scalability, interoperability, and flexibility. While a blockchain on Avalanche can be run with any VM, the most prominent choice currently is the Ethereum Virtual Machine (EVM). Users can deploy their own logic in the form of smart contracts to the EVM. 

These smart contracts can be written in Solidity. Learning Solidity can enable you to leverage the features of blockchain for your dApp.

## Course Content

### Smart Contracts 
In the first section, we will look at what smart contracts are, their basic structure and how they work. 

### Hello World Part I
In this section we will look at the primitive types (strings, integers, bool, ...) and function as well as the Solidity file structure. 

### Hello World Part II
We will look at control flows (if & else), data structures and constructors. Furthermore, we learn about inheritance from other contracts and modifiers and events.

### Contract Standardization
You will learn how contracts can be standardized and how inheritance and interfaces can help us to do so.

## Prerequisites

### Blockchain / Web3
This course is meant for people with a some experience when it comes to web3. You should be familiar with these concepts:
- Wallet: What they are and how to create one
- dApp: What a decentralized application is and how to interact with one

If any of this is unclear, we strongly recommend taking the Avalanche Fundamentals and Subnet Architecture courses first, that give a soft introduction into these topics from a user stand point.

### Software Development
You will need a general understanding of Software Development. Therefore, we recommend:
- Programming: Familiarity with most basic concepts of programming, such as variables, control flows (if, else) and loops. All exercises will consist of writing small contracts in Solidity.
- IDE: It will help if you're generally familiar with the concept of an integrated developer environment. We will be leveraging Remix.

## Learning Outcomes

By the end of this course, students will:

- Interact and Deploy contracts using Foundry
- Get familiar with ERC20 and ERC721 token standards
- Understand important concepts such as inheritance, modifiers, and events.
- Apply their knowledge by building their own smart contracts.


# Features (/academy/avacloudapis/02-overview/01-about)

---
title: Features
description: Learn about the features of the AvaCloud API.
updated: 2024-09-03
authors: [owenwahlgren]
icon: Book
---

## What is the Data API?

The Data API provides web3 application developers with multi-chain data related to Avalanche’s primary network, Avalanche L1s, and Ethereum. With the Data API, you can easily build products that leverage real-time and historical transaction and transfer history, native and token balances, and various types of token metadata.

### Data API Features
- **Extensive L1 Support**: Gain access to data from over 100+ L1s across both mainnet and testnet. If an L1 is listed on the [Avalanche Explorer](https://subnets.avax.network/stats/), you can query its data using the Data API.
- **Transactions and UTXOs**: Easily retrieve details related to transactions, UTXOs, and token transfers from Avalanche EVMs, Ethereum, and Avalanche’s Primary Network (P-Chain, X-Chain and C-Chain).
- **Blocks**: Retrieve latest blocks and block details
- **Balances**: Fetch balances of native, ERC-20, ERC-721, and ERC-1155 tokens along with relevant metadata.
- **Tokens**: Augment your user experience with asset details.
- **Staking**: Get staking related data for active and historical validations.

## What is the Metrics API?
The Metrics API equips web3 developers with a robust suite of tools to access and analyze on-chain activity across Avalanche’s primary network, Avalanche L1s, and other supported EVM chains. This API delivers comprehensive metrics and analytics, enabling you to seamlessly integrate historical data on transactions, gas consumption, throughput, staking, and more into your applications.

The Metrics API, along with the Data API are the driving force behind every graph you see on the [Avalanche Explorer](https://subnets.avax.network/stats/). From transaction trends to staking insights, the visualizations and data presented are all powered by these APIs, offering real-time and historical insights that are essential for building sophisticated, data-driven blockchain products.

### Metrics API Features
- **Chain Throughput**: Retrieve detailed metrics on gas consumption, Transactions Per Second (TPS), and gas prices, including rolling windows of data for granular analysis.
- **Cumulative Metrics**: Access cumulative data on addresses, contracts, deployers, and transaction counts, providing insights into network growth over time.
- **Staking Information**: Obtain staking-related data, including the number of validators and delegators, along with their respective weights, across different L1s.
- **Blockchains and L1s**: Get information about supported blockchains, including EVM Chain IDs, blockchain IDs, and L1s associations, facilitating multi-chain analytics.
- **Composite Queries**: Perform advanced queries by combining different metric types and conditions, enabling detailed and customizable data retrieval.

## What is the AvaCloudSDK?

The [AvaCloud SDK](https://developers.avacloud.io/avacloud-sdk/getting-started) provides web3 application developers with multi-chain data related to Avalanche’s primary network, Avalanche L1s, and Ethereum. With the Data API, you can easily build products that leverage real-time and historical transaction and transfer history, native and token balances, and various types of token metadata.

The SDK is currently available in TypeScript, with more languages coming soon. If you are interested in a language that is not listed, please reach out to us in the [`#dev-tools`](https://discord.com/login?redirect_to=%2Flogin%3Fredirect_to%3D%252Fchannels%252F578992315641626624%252F1280920394236297257) channel in the [Avalanche Discord](https://discord.com/invite/avax).


# APIs vs RPCs (/academy/avacloudapis/02-overview/02-apis-vs-rpc)

---
title: APIs vs RPCs
description: Learn how the AvaCloud Data API differs from RPC calls
updated: 2024-09-03
authors: [owenwahlgren]
icon: Book
---

Blockchain RPCs and APIs both facilitate interactions with a network, but they differ significantly in how they operate.

### RPCs
**Blockchain RPCs** allow you to communicate directly with a blockchain node, performing tasks like querying data or submitting transactions. These are low-level, synchronous calls, requiring a deep understanding of the blockchain's structure and specific commands.

To get a more comprehensive understanding of Ethereum's JSON-RPC API, you can refer to the [official Ethereum documentation](https://ethereum.org/en/developers/docs/apis/json-rpc/).

### APIs
**Blockchain APIs**, like the AvaCloud Data API, abstract away much of the complexity. They offer higher-level, user-friendly endpoints that streamline interactions, making it easier to build and manage blockchain applications without needing in-depth knowledge of the underlying blockchain protocols.

To get a more comprehensive understanding of the AvaCloud Data API, you can refer to the [official AvaCloud Data API documentation](https://developers.avacloud.io/data-api/overview).

### Example Use Case
For example, querying a user's ERC-20 portfolio using an RPC involves a series of complex calls to retrieve and parse raw blockchain data. 
Using just RPCs, you would need to:

1. Query every block on the network for transaction logs.
2. Parse each transaction log to identify ERC-20 token transfers.
3. Extract the ERC-20 token contract address.
4. For each ERC-20 token contract, query the user's address to get the balance.
5. Parse and aggregate the data to present the user's portfolio.

While it may seem simple in theory, this process can be time-consuming and error-prone, especially when dealing with multiple blockchains.

With the AvaCloud Data API, you could simply use a dedicated endpoint such as: 
```bash
curl --request GET \
  --url https://glacier-api.avax.network/v1/chains/{chainId}/addresses/{address}/balances:listErc20 \
  --header 'x-glacier-api-key: <api-key>'
```

to get a neatly formatted response with the user's ERC-20 portfolio, significantly reducing development time and complexity.

```json
{
  "nextPageToken": "<string>",
  "erc20TokenBalances": [
    {
      "address": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
      "name": "Wrapped AVAX",
      "symbol": "WAVAX",
      "decimals": 18,
      "logoUri": "https://images.ctfassets.net/gcj8jwzm6086/5VHupNKwnDYJvqMENeV7iJ/fdd6326b7a82c8388e4ee9d4be7062d4/avalanche-avax-logo.svg",
      "ercType": "ERC-20",
      "price": {
        "currencyCode": "usd",
        "value": "42.42"
      },
      "chainId": "43114",
      "balance": "2000000000000000000",
      "balanceValue": {
        "currencyCode": "usd",
        "value": "42.42"
      }
    }
  ]
}
```

# Data API (/academy/avacloudapis/02-overview/03-dataapi-endpoints)

---
title: Data API
description: Learn about AvaCloud Data API.
updated: 2024-09-03
authors: [owenwahlgren]
icon: Book
---
![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/avacloudsdk/glacier-data-api-7knGxPQ6gpsJcZehfeZVYcRUAr6u1l.png)

The AvaCloud Data API provides a comprehensive set of endpoints to interact with Avalanche networks. These endpoints allow you to query information about blocks, transactions, assets, and more.

Below are some of the key endpoints available in the Data API.
A more comprehensive list of Data API endpoints can be found [here](https://developers.avacloud.io/data-api/overview).

## Data API Reference
### EVM Endpoints

<Accordions>
<Accordion title="Chains">
- [List All Chains](https://developers.avacloud.io/data-api/evm-chains/list-chains)
```bash
curl --request GET \
     --url https://glacier-api.avax.network/v1/chains \
     --header 'accept: application/json'
```
- [Get Chain Information](https://developers.avacloud.io/data-api/evm-chains/get-chain-information)
```bash
curl --request GET \
     --url https://glacier-api.avax.network/v1/chains/{chainId} \
     --header 'accept: application/json'
```
</Accordion>

<Accordion title="Blocks">
- [List Latest Blocks](https://developers.avacloud.io/data-api/evm-chains/list-latest-blocks)
```bash
curl --request GET \
     --url https://glacier-api.avax.network/v1/chains/{chainId}/blocks \
     --header 'accept: application/json'
```
- [Get Block Information](https://developers.avacloud.io/data-api/evm-chains/getblock)
```bash
curl --request GET \
     --url https://glacier-api.avax.network/v1/chains/{chainId}/blocks/{blockId} \
     --header 'accept: application/json'
``` 

</Accordion>

<Accordion title="Transactions">
- [Get Deployment Transaction](https://developers.avacloud.io/data-api/evm-transactions/get-deployment-transaction)
```bash
curl --request GET \
     --url https://glacier-api.avax.network/v1/chains/{chainId}/contracts/{address}/transactions:getDeployment \
     --header 'accept: application/json'
```
- [List Deployed Contracts](https://developers.avacloud.io/data-api/evm-transactions/list-deployed-contracts)
```bash
curl --request GET \
     --url https://glacier-api.avax.network/v1/chains/{chainId}/contracts/{address}/deployments \
     --header 'accept: application/json'
```
- [List ERC Transfers](https://developers.avacloud.io/data-api/evm-transactions/list-erc-transfers)
```bash
curl --request GET \
     --url https://glacier-api.avax.network/v1/chains/{chainId}/tokens/{address}/transfers \
     --header 'accept: application/json'
```

- [List Transactions](https://developers.avacloud.io/data-api/evm-transactions/list-transactions)
```bash
curl --request GET \
     --url https://glacier-api.avax.network/v1/chains/{chainId}/addresses/{address}/transactions \
     --header 'accept: application/json'
```

- [List Native Transactions](https://developers.avacloud.io/data-api/evm-transactions/list-native-transactions)
```bash
curl --request GET \
     --url https://glacier-api.avax.network/v1/chains/{chainId}/addresses/{address}/transactions:listNative \
     --header 'accept: application/json'
```

- [List ERC-20 Transfers](https://developers.avacloud.io/data-api/evm-transactions/list-erc-20-transfers)
```bash
curl --request GET \
     --url https://glacier-api.avax.network/v1/chains/{chainId}/addresses/{address}/transactions:listErc20 \
     --header 'accept: application/json'
```

- [List ERC-721 Transfers](https://developers.avacloud.io/data-api/evm-transactions/list-erc-721-transfers)
```bash
curl --request GET \
     --url https://glacier-api.avax.network/v1/chains/{chainId}/addresses/{address}/transactions:listErc721 \
     --header 'accept: application/json'
```

- [List ERC-1155 Transfers](https://developers.avacloud.io/data-api/evm-transactions/list-erc-1155-transfers)
```bash
curl --request GET \
     --url https://glacier-api.avax.network/v1/chains/{chainId}/addresses/{address}/transactions:listErc1155 \
     --header 'accept: application/json'
```
- [List Internal Transactions](https://developers.avacloud.io/data-api/evm-transactions/list-internal-transactions)
```bash
curl --request GET \
     --url https://glacier-api.avax.network/v1/chains/{chainId}/addresses/{address}/transactions:listInternals \
     --header 'accept: application/json'
```

- [Get Transaction](https://developers.avacloud.io/data-api/evm-transactions/get-transaction)
```bash
curl --request GET \
     --url https://glacier-api.avax.network/v1/chains/{chainId}/transactions/{txHash} \
     --header 'accept: application/json'
```

- [List Transactions For a Block](https://developers.avacloud.io/data-api/evm-transactions/list-transactions-for-a-block)
```bash
curl --request GET \
     --url https://glacier-api.avax.network/v1/chains/{chainId}/blocks/{blockId}/transactions \
     --header 'accept: application/json'
```

- [List Latest Transactions](https://developers.avacloud.io/data-api/evm-transactions/list-latest-transactions)
```bash
curl --request GET \
     --url https://glacier-api.avax.network/v1/chains/{chainId}/transactions \
     --header 'accept: application/json'
```
</Accordion>

<Accordion title="Balances">
- [Get Native Token Balance](https://developers.avacloud.io/data-api/evm-balances/get-native-token-balance)
```bash
curl --request GET \
     --url https://glacier-api.avax.network/v1/chains/{chainId}/addresses/{address}/balances:getNative \
     --header 'accept: application/json'
```
- [List ERC-20 Balances](https://developers.avacloud.io/data-api/evm-balances/list-erc-20-balances)
```bash
curl --request GET \
     --url https://glacier-api.avax.network/v1/chains/{chainId}/addresses/{address}/balances:listErc20 \
     --header 'accept: application/json'
```
- [List ERC-721 Balances](https://developers.avacloud.io/data-api/evm-balances/list-erc-721-balances)
```bash
curl --request GET \
     --url https://glacier-api.avax.network/v1/chains/{chainId}/addresses/{address}/balances:listErc721 \
     --header 'accept: application/json'
```
- [List ERC-1155 Balances](https://developers.avacloud.io/data-api/evm-balances/list-erc-1155-balances)
```bash
curl --request GET \
     --url https://glacier-api.avax.network/v1/chains/{chainId}/addresses/{address}/balances:listErc1155 \
     --header 'accept: application/json'
```
- [List Collectible (ERC-721 and ERC-1155) Balances](https://developers.avacloud.io/data-api/evm-balances/list-collectible-erc-721erc-1155-balances)
```bash
curl --request GET \
     --url https://glacier-api.avax.network/v1/chains/{chainId}/addresses/{address}/balances:listCollectibles \
     --header 'accept: application/json'
```
</Accordion>

<Accordion title="Contracts">
- [Get Contract Metadata](https://developers.avacloud.io/data-api/evm-contracts/get-contract-metadata)
```bash
curl --request GET \
     --url https://glacier-api.avax.network/v1/chains/{chainId}/addresses/{address} \
     --header 'accept: application/json'
```
</Accordion>

<Accordion title="NFTs">
- [Reindex NFT Metadata](https://developers.avacloud.io/data-api/nfts/reindex-nft-metadata)
```bash
curl --request POST \
     --url https://glacier-api.avax.network/v1/chains/{chainId}/nfts/collections/{address}/tokens/tokenId:reindex \
     --header 'accept: application/json'
```
- [List Tokens](https://developers.avacloud.io/data-api/nfts/list-tokens)
```bash
curl --request GET \
     --url https://glacier-api.avax.network/v1/chains/{chainId}/nfts/collections/{address}/tokens \
     --header 'accept: application/json'
```
- [Get Token Details](https://developers.avacloud.io/data-api/nfts/get-token-details)
```bash
curl --request GET \
     --url https://glacier-api.avax.network/v1/chains/{chainId}/nfts/collections/{address}/tokens/tokenId \
     --header 'accept: application/json'
```

</Accordion>

</Accordions>



### Avalanche Primary Network Endpoints

<Accordions>
<Accordion title="Network, Chains, and L1s">
- [Get Chain Interactions for Addresses](https://developers.avacloud.io/data-api/primary-network/get-chain-interactions-for-addresses)
```bash
curl --request GET \
     --url https://glacier-api.avax.network/v1/networks/{network}/addresses:listChainIds \
     --header 'accept: application/json'
```

- [Get Network Details](https://developers.avacloud.io/data-api/primary-network/get-network-details)
```bash
curl --request GET \
     --url https://glacier-api.avax.network/v1/networks/{network} \
     --header 'accept: application/json'
```
- [List Blockchains](https://developers.avacloud.io/data-api/primary-network/list-blockchains)
```bash
curl --request GET \
     --url https://glacier-api.avax.network/v1/networks/{network}/blockchains \
     --header 'accept: application/json'
```

- [List Subnets](https://developers.avacloud.io/data-api/primary-network/list-subnets)
```bash
curl --request GET \
     --url https://glacier-api.avax.network/v1/networks/mainnet/subnets \
     --header 'accept: application/json'
```
- [Get Subnet Details by ID](https://developers.avacloud.io/data-api/primary-network/get-subnet-details-by-id)
```bash
curl --request GET \
     --url https://glacier-api.avax.network/v1/networks/mainnet/subnets/{subnetId} \
     --header 'accept: application/json'
```
</Accordion>

<Accordion title="Validators and Delegators">
- [List Validators](https://developers.avacloud.io/data-api/primary-network/list-validators)
```bash
curl --request GET \
     --url https://glacier-api.avax.network/v1/networks/mainnet/validators \
     --header 'accept: application/json'
```
- [Get Single Validator Details](https://developers.avacloud.io/data-api/primary-network/get-single-validator-details)
```bash
curl --request GET \
     --url https://glacier-api.avax.network/v1/networks/mainnet/validators/{nodeId} \
     --header 'accept: application/json'
```
- [List Delegators](https://developers.avacloud.io/data-api/primary-network/list-delegators)
```bash
curl --request GET \
     --url https://glacier-api.avax.network/v1/networks/mainnet/delegators \
     --header 'accept: application/json'
```
</Accordion>

<Accordion title="Blocks">
- [Get Block](https://developers.avacloud.io/data-api/primary-network-blocks/get-block)
```bash
curl --request GET \
     --url https://glacier-api.avax.network/v1/networks/mainnet/blockchains/11111111111111111111111111111111LpoYY/blocks/{blockId} \
     --header 'accept: application/json'
```
- [List Blocks Proposed by Node](https://developers.avacloud.io/data-api/primary-network-blocks/list-blocks-proposed-by-node)
```bash
curl --request GET \
     --url https://glacier-api.avax.network/v1/networks/mainnet/blockchains/11111111111111111111111111111111LpoYY/nodes/{nodeId}/blocks \
     --header 'accept: application/json'
```

- [List Latest Blocks](https://developers.avacloud.io/data-api/primary-network-blocks/list-latest-blocks)
```bash
curl --request GET \
     --url https://glacier-api.avax.network/v1/networks/mainnet/blockchains/11111111111111111111111111111111LpoYY/blocks \
     --header 'accept: application/json'
```
</Accordion>

<Accordion title="Vertices">
- [List Vertices](https://developers.avacloud.io/data-api/primary-network-vertices/list-vertices)
```bash
curl --request GET \
     --url https://glacier-api.avax.network/v1/networks/mainnet/blockchains/2oYMBNV4eNHyqk2fjjV5nVQLDbtmNJzq5s3qs3Lo6ftnC6FByM/vertices \
     --header 'accept: application/json'
```
- [Get Vertex](https://developers.avacloud.io/data-api/primary-network-vertices/get-vertex)
```bash
curl --request GET \
     --url https://glacier-api.avax.network/v1/networks/mainnet/blockchains/2oYMBNV4eNHyqk2fjjV5nVQLDbtmNJzq5s3qs3Lo6ftnC6FByM/vertices/vertexHash \
     --header 'accept: application/json'
```
- [List Vertices by Height](https://developers.avacloud.io/data-api/primary-network-vertices/list-vertices-by-height)
```bash
curl --request GET \
     --url https://glacier-api.avax.network/v1/networks/mainnet/blockchains/2oYMBNV4eNHyqk2fjjV5nVQLDbtmNJzq5s3qs3Lo6ftnC6FByM/vertices:listByHeight \
     --header 'accept: application/json'
```
</Accordion>

<Accordion title="Transactions">
- [Get Transaction](https://developers.avacloud.io/data-api/primary-network-transactions/get-transaction)
```bash
curl --request GET \
     --url https://glacier-api.avax.network/v1/networks/{network}/blockchains/{blockchainId}/transactions/{txHash} \
     --header 'accept: application/json'
```
- [List Latest Transactions](https://developers.avacloud.io/data-api/primary-network-transactions/list-latest-transactions)
```bash
curl --request GET \
     --url https://glacier-api.avax.network/v1/networks/{network}/blockchains/{blockchainId}/transactions \
     --header 'accept: application/json'
```
- [List Staking Transactions](https://developers.avacloud.io/data-api/primary-network-transactions/list-staking-transactions)
```bash
curl --request GET \
     --url https://glacier-api.avax.network/v1/networks/mainnet/blockchains/11111111111111111111111111111111LpoYY/transactions:listStaking \
     --header 'accept: application/json'
```

- [List Asset Transactions](https://developers.avacloud.io/data-api/primary-network-transactions/list-asset-transactions)
```bash
curl --request GET \
     --url https://glacier-api.avax.network/v1/networks/mainnet/blockchains/2oYMBNV4eNHyqk2fjjV5nVQLDbtmNJzq5s3qs3Lo6ftnC6FByM/assets/{assetId}/transactions \
     --header 'accept: application/json'
```

</Accordion>

<Accordion title="Balances and UTXOs">
- [List UTXOs](https://developers.avacloud.io/data-api/primary-network-utxos/list-utxos)
```bash
curl --request GET \
     --url https://glacier-api.avax.network/v1/networks/mainnet/blockchains/11111111111111111111111111111111LpoYY/utxos \
     --header 'accept: application/json'
```
- [Get Balances](https://developers.avacloud.io/data-api/primary-network-balances/get-balances)
```bash
curl --request GET \
     --url https://glacier-api.avax.network/v1/networks/mainnet/blockchains/11111111111111111111111111111111LpoYY/balances \
     --header 'accept: application/json'
```
</Accordion>

<Accordion title="Rewards">
- [List Pending Rewards](https://developers.avacloud.io/data-api/primary-network-rewards/list-pending-rewards)
```bash
curl --request GET \
     --url https://glacier-api.avax.network/v1/networks/mainnet/rewards:listPending \
     --header 'accept: application/json'
```
- [List Historical Rewards](https://developers.avacloud.io/data-api/primary-network-rewards/list-historical-rewards)
```bash
curl --request GET \
     --url https://glacier-api.avax.network/v1/networks/mainnet/rewards \
     --header 'accept: application/json'
```
</Accordion>

<Accordion title="Assets">
- [Get Asset Details](https://developers.avacloud.io/data-api/primary-network/get-asset-details)
```bash
curl --request GET \
     --url https://glacier-api.avax.network/v1/networks/mainnet/blockchains/2oYMBNV4eNHyqk2fjjV5nVQLDbtmNJzq5s3qs3Lo6ftnC6FByM/assets/{assetId} \
     --header 'accept: application/json'
```
</Accordion>
</Accordions>


# Webhooks API (/academy/avacloudapis/02-overview/04-webhooks)

---
title: Webhooks API
description: Learn about AvaCloud Webhooks API.
updated: 2024-09-03
authors: [owenwahlgren]
icon: Book
---
## What is a Webhook?

A webhook is a communication mechanism to provide applications with real-time information. It delivers data to other applications as it happens, meaning you get data immediately, unlike typical APIs where you would need to poll for data to get it in "real-time". This makes webhooks much more efficient for both providers and consumers. Webhooks work by registering a URL to send notifications once certain events occur.
You can create receiver endpoints in your server in any programming language and those will have an associated URL. This object contains all the relevant information about what just happened, including the type of event and the data associated with that event.

## What are AvaCloud Webhooks?

With the Webhooks API, you can monitor real-time events on the Avalanche C-Chain and L1s. For example, you can monitor smart contract events, track NFT transfers, and observe wallet-to-wallet transactions.

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/avacloudsdk/glacier-webhooks-xpLeH8o7slcnvOdWsIorDJSUeNlz04.png)

### Key Features:
- **Real-time notifications:** Receive immediate updates on specified on-chain activities without polling.
- **Customizable:** Specify the desired event type to listen for, customizing notifications according to individual requirements.
- **Secure:** Employ shared secrets and signature-based verification to guarantee that notifications originate from a trusted source.
- **Broad Coverage:** Support for C-chain mainnet, testnet, and L1s within the Avalanche ecosystem, ensuring wide-ranging monitoring capabilities.

### Use Cases:
- **NFT Marketplace Transactions:** Get alerts for NFT minting, transfers, auctions, bids, sales, and other interactions within NFT marketplaces.
- **Wallet Notifications:** Receive alerts when an address performs actions such as sending, receiving, swapping, or burning assets.
- **DeFi Activities:** Receive notifications for various DeFi activities such as liquidity provisioning, yield farming, borrowing, lending, and liquidations.

## Webhooks API Reference

<Accordions>

<Accordion title="Create a webhook">
[Create a new webhook](https://developers.avacloud.io/webhooks-api/webhooks/create-a-webhook)
```bash
curl --request POST \
     --url https://glacier-api.avax.network/v1/webhooks \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "eventType": "address_activity"
}
```
</Accordion>

<Accordion title="List webhooks">
[Lists webhooks for the user.](https://developers.avacloud.io/webhooks-api/webhooks/list-webhooks)
```bash
curl --request GET \
     --url https://glacier-api.avax.network/v1/webhooks \
     --header 'accept: application/json'
```

</Accordion>

<Accordion title="Get a webhook by ID">
[Retrieves a webhook by ID.](https://developers.avacloud.io/webhooks-api/webhooks/get-a-webhook-by-id)
```bash
curl --request GET \
     --url https://glacier-api.avax.network/v1/webhooks/id \
     --header 'accept: application/json'
```

</Accordion>

<Accordion title="Deactivate a webhook">
[Deactivates a webhook by ID.](https://developers.avacloud.io/webhooks-api/webhooks/deactivate-a-webhook)
```bash
curl --request DELETE \
     --url https://glacier-api.avax.network/v1/webhooks/id \
     --header 'accept: application/json'
```

</Accordion>

<Accordion title="Update a webhook">
[Updates an existing webhook.](https://developers.avacloud.io/webhooks-api/webhooks/update-a-webhook)
```bash
curl --request PATCH \
     --url https://glacier-api.avax.network/v1/webhooks/id \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
```
</Accordion>

<Accordion title="Generate a shared secret">
[Generates a new shared secret.](https://developers.avacloud.io/webhooks-api/webhooks/generate-a-shared-secret)
```bash
curl --request POST \
     --url https://glacier-api.avax.network/v1/webhooks:generateOrRotateSharedSecret \
     --header 'accept: application/json'
```

</Accordion>

<Accordion title="Get a shared secret">
[Get a previously generated shared secret.](https://developers.avacloud.io/webhooks-api/webhooks/get-a-shared-secret)
```bash
curl --request GET \
     --url https://glacier-api.avax.network/v1/webhooks:getSharedSecret \
     --header 'accept: application/json'
```

</Accordion>

<Accordion title="Add addresses to webhook">
[Add addresses to webhook.](https://developers.avacloud.io/webhooks-api/webhooks/add-addresses-to-webhook)
```bash
curl --request PATCH \
     --url https://glacier-api.avax.network/v1/webhooks/id/addresses \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
```
</Accordion>

<Accordion title="Remove addresses to webhook">
[Remove addresses from webhook.](https://developers.avacloud.io/webhooks-api/webhooks/remove-addresses-from-webhook)
```bash
curl --request DELETE \
     --url https://glacier-api.avax.network/v1/webhooks/id/addresses \
     --header 'accept: application/json' \
     --header 'content-type: application/json'
```

</Accordion>

<Accordion title="List addresses by webhook">
[List adresses by webhook.](https://developers.avacloud.io/webhooks-api/webhooks/list-adresses-by-webhook)
```bash
curl --request GET \
     --url https://glacier-api.avax.network/v1/webhooks/id/addresses \
     --header 'accept: application/json'
```

</Accordion>


</Accordions>

# Create API Key (/academy/avacloudapis/03-environment-setup/01-avacloud-account)

---
title: Create API Key
description: Get an API key for AvaCloud
updated: 2024-09-03
authors: [owenwahlgren]
icon: Book
---
import { Step, Steps } from 'fumadocs-ui/components/steps';


## Get an AvaCloud API Key

In order to utilize your accounts rate limits, you will need to make API requests with an API key. You can generate API Keys from the [AvaCloud portal](https://app.avacloud.io/glacier-api/).

<Steps>

<Step>
Create an account on [AvaCloud](https://avacloud.io).
</Step>

<Step>
Click on the `Web3 Data API` [tab](https://app.avacloud.io/glacier-api/).
![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/avacloudsdk/create-api-key-gfBR9O5rSJilgNzws8JWyHXctbsXox.png)
</Step>

<Step>
Click `+ Add API Key` and create a new name for your API key.
![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/avacloudsdk/name-api-key-NuNRHpnSFC3dLvLYdbztDTlAf8Ax6k.png)
</Step>

<Step>
**Save your API key** in a secure location. We will need it in the next step.
![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/avacloudsdk/grab-api-key-KN2CdMQVWrHPKjPY4vxS4H6pIZVJmW.png)
</Step>

</Steps>

After generating the API keys the AvaCloud page should look like this:
![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/avacloudsdk/final-api-key-5ydE6hNLZajRH3hNEAYE5IFFmNBdPX.png)

Once you've created and retrieved the key, you will be able to make authenticated queries by passing in your API key in the `x-glacier-api-key` header of your HTTP request.

An example curl request to the Data API:

```bash
curl -H "Content-Type: Application/json" -H "x-glacier-api-key: <your_api_key>" \
  "https://glacier-api.avax.network/v1/chains"
```

# Setup AvaCloudSDK Starter Kit (/academy/avacloudapis/03-environment-setup/02-setup-starter-kit)

---
title: Setup AvaCloudSDK Starter Kit
description: Set up the AvaCloudSDK Starter Kit in a GitHub Codespace
updated: 2024-09-03
authors: [owenwahlgren]
icon: Book
---
import Link from 'next/link';
import { cn } from '@/utils/cn';
import { buttonVariants } from '@/components/ui/button.tsx'
import { Step, Steps } from 'fumadocs-ui/components/steps';

In this course we will run the AvaCloudSDK Starter Kit in a Github Codepsace. This is the quickest way to get started.

The `AvaCloudSDK Starter Kit` contains everything we need to get started quickly with the AvaCloud API. 

<Steps>
<Step>

### Open the AvaCloudSDK Starter Kit Github Repository:
**Make sure you are on the `follow-along` branch!**

<Link
    href="https://github.com/ava-labs/glacier-starter-kit/tree/follow-along"
    className={cn(
    buttonVariants({ variant: 'default', className: 'mt-4' }),
    )}
    target='_blank'
>Open AvaCloudSDK Starter Kit</Link>

</Step>
<Step>

### Create a Codespace
[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://github.com/codespaces/new?hide_repo_select=true&ref=follow-along&repo=851861669&machine=standardLinux32gb)
The Codespace will open in a new tab. Wait a few minutes until it's fully built.

</Step>
<Step>

### Verify everything is working correctly

Open the terminal with `` Ctrl + ` `` or by opening it through the menu:

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/avacloudsdk/terminal-08TThSFqM438J1Jd5E1bh1OyMYAXWg.png)

</Step>
<Step>

### Set the `AVACLOUD_API_KEY` environment variable
Create a `.env` file in the root of the project and add your API key from [the previous step](/academy/avacloudapis/03-environment-setup/01-avacloud-account):

```bash
AVACLOUD_API_KEY=ac_rGIKESl9_9DWuLfJJQLSV5nlzbKR7eHxym6XW3XEQJeNBDRxI...
```

</Step>
<Step>
### Start the NextJS app
Now we can run the NextJS app in hot reload mode:
    
```bash
yarn dev
```

It should preview within the Codespace:
![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/avacloudsdk/site-running-neUxhhADHqXs34Jrgw1uSJhqokItAC.png)

</Step>
<Step>



### Optional: Open Codespace locally in Visual Studio Code

You can switch any time from the browser IDE to Visual Studio Code:

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/avacloudsdk/vs-code-DNVuxWt4Z4ffoDsszoGDyUuhXvhC8m.png)

The first time you switch, you will be asked to install the [Codespaces extension](https://marketplace.visualstudio.com/items?itemName=GitHub.codespaces) and connect VS Code to you GitHub account, if it is not already connceted.

</Step>
</Steps>

# Time to Build! (/academy/avacloudapis/03-environment-setup/03-what-we-build)

---
title: Time to Build!
description: Learn about what we will build in this course
updated: 2024-09-03
authors: [owenwahlgren]
icon: Book
---

### Finished Setup
Once your environment is set up, we can start building some applications using the AvaCloud API and the AvaCloudSDK. The home page should look like this:
![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/avacloudsdk/preview-L1zktfNDP4fWzdESdhIQ7KxsfnQJj0.png)

### What We Will Build
Here is a brief overview of what we will be building in this course:

- ERC-20 Balance App
- Wallet Portfolio App
- Block Explorer App

Each of these applications will utilize the Data API to get data from the Avalanche network. We will fetch data such as ERC-20 token balances, NFT balances, recent transactions from an address, block information and much more.

# Overview (/academy/avacloudapis/04-erc20-token-balance-app/01-overview)

---
title: Overview
description: Use the AvaCloud Data API to create a simple web app that displays a user's ERC-20 token balances.
updated: 2024-09-13
authors: [owenwahlgren]
icon: Book
---

In this section we will use the Data API to create a simple web app that displays a user's ERC-20 token portfolio. This app will allow users to input their Avalanche C-Chain address and view a list of their ERC-20 token balances.

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/avacloudsdk/balance-app-9ggCriiHBsggku1bFGF8tL1lyThSx4.png)
We will use two endpoints from the Data API to accomplish this:

- [`data.evm.blocks.getLatestBlocks`](https://developers.avacloud.io/data-api/evm-blocks/list-latest-blocks)
- [`data.evm.balances.listErc20Balances`](https://developers.avacloud.io/data-api/evm-balances/list-erc-20-balances)


# Understanding the Code (/academy/avacloudapis/04-erc20-token-balance-app/02-understanding-code)

---
title: Understanding the Code
description: Before we start coding, let's take a look at the code we will be working with.
updated: 2024-09-13
authors: [owenwahlgren]
icon: Book
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

There will be two main files that we will be working with in this section.

<Steps>
<Step>

### `Page.tsx`
This is the code that will be rendered on the client side, as distinguished by `"use client";` at the top of the file. It contains the React components that will be displayed to the user and is responsible for making the API calls to our backend, which in turn calls the Data API.

It is important to understand that when you `"use client"` in a NextJS project, it will be rendered on the client side. This means that the code will be executed in the user's browser and not on the server. This is important to keep in mind when working with sensitive data or when you want to keep your API keys secure.

Besides this, we have two main functions that we will be working with in this file:

<Steps>
<Step>

```tsx title="src/app/balance-app/page.tsx"
const handleSetAddress = async () => {
  //
  // TODO: Implement handleSetAddress
  //
};
```
`handleSetAddress` is a simple function that will be called when the user clicks the "Set Address" button. It will ensure the address is valid then set the inputted address to the React State. Next, we call our next function `fetchERC20Balances` to get the user's balance.

</Step>
<Step>

```tsx title="src/app/balance-app/page.tsx"
const fetchERC20Balances = async (address: string) => {
  //
  // TODO: Implement fetchERC20Balances
  //
};
```

`fetchERC20Balances` is a function that will make a call to our backend to get the user's ERC-20 token balances. It will first get the current block height, then call the `listErc20Balances` method on our backend with the user's address and the block height. It will then return the balances as an array of `Erc20TokenBalance` objects.

</Step>
</Steps>

</Step>
<Step>

### `Route.ts`
This code will be executed on the server side, as distinguished by `"use server";` at the top of the file. It contains the code that will be executed on the server side and is responsible for making the API calls to the Data API.

There are a few key components to understand in this file:

<Steps>
<Step>
```tsx title="src/app/api/balance/route.ts"
import { AvaCloudSDK } from "@avalabs/avacloud-sdk";
const avaCloudSDK = new AvaCloudSDK({
  apiKey: process.env.AVACLOUD_API_KEY,
  chainId: "43114", // Avalanche Mainnet
  network: "mainnet",
});
```
Here we initialize the `AvaCloudSDK` with our AvaCloud API key and the chainId of `43114` for the Avalanche Mainnet. This will allow us to make calls to the Data API.
</Step>
<Step>

```tsx title="src/app/api/balance/route.ts"
export async function GET(request: Request) {
  const { searchParams } = new URL(request.url)
  const method = searchParams.get('method')
  try {
    let result
    switch (method) {
      case 'getBlockHeight':
        result = await getBlockHeight()
        break
      case 'listErc20Balances':
        const address: string = searchParams.get('address')!
        const blockNumber: string = searchParams.get('blockNumber')!
        result = await listErc20Balances(address, blockNumber);
        break
      default:
        return NextResponse.json({ error: 'Invalid method' }, { status: 400 })
    }
    return NextResponse.json(result)
  } catch (error) {
    return NextResponse.json({ error: 'Internal Server Error' }, { status: 500 })
  }
}
```
Here we define the internal API methods for our backend. We have two methods that we will be working with in this section: `getBlockHeight` and `listErc20Balances`. We create both of these methods internally, then forward the request to the Data API. We then return the result to the client.
</Step>
<Step>
```tsx title="src/app/api/balance/route.ts"
async function getBlockHeight() {
   //
   // TODO: Implement getBlockHeight
   //
}
async function listErc20Balances(address: string, blockNumber: string) {
   //
   // TODO: Implement listErc20Balances
   //
}
```
In the next section, we will implement the `listErc20Balances` and `getBlockHeight` function to call the Data API through the AvaCloudSDK.
</Step>
</Steps>
</Step> 
</Steps> 

# Modifying the Code (/academy/avacloudapis/04-erc20-token-balance-app/03-modifying-code)

---
title: Modifying the Code
description: Lets modify the code to implement the Data API.
updated: 2024-09-13
authors: [owenwahlgren]
icon: Book
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

In this section we will modify the code to implement the Data API.

### Modify Backend `src/app/api/balance/route.ts`

<Steps>
<Step>
First we will implement the `getBlockHeight` function. The goal of this function is to fetch recent blocks from the Data API then to return the highest block in the first position.

<Accordions>
<Accordion title="Hint">
Reference the [AvaCloud SDK documentation](https://developers.avacloud.io/data-api/evm-blocks/list-latest-blocks) to see how to fetch the latest blocks.
</Accordion>
<Accordion title="Solution">
```tsx title="src/app/api/balance/route.ts"
async function getBlockHeight() {
    const result = await avaCloudSDK.data.evm.blocks.getLatestBlocks({
        pageSize: 1,
      });
    return result.result.blocks[0].blockNumber
}
```
</Accordion>
</Accordions>
</Step>
<Step>
Next we will implement the `listErc20Balances` function. The goal of this function is to fetch the ERC-20 token balances for a given address at a specific block height.
<Accordions>
<Accordion title="Hint">
Reference the [AvaCloud SDK documentation](https://developers.avacloud.io/data-api/evm-balances/list-erc-20-balances) to see how to fetch ERC-20 token balances.
Note the `Erc20TokenBalance` type that is imported, we should use this to combine paged results.
</Accordion>
<Accordion title="Solution">
```tsx title="src/app/api/balance/route.ts"
async function listErc20Balances(address: string, blockNumber: string) {
    const result = await avaCloudSDK.data.evm.balances.listErc20Balances({
        blockNumber: blockNumber,
        pageSize: 10,
        address: address,
      });
    const balances: Erc20TokenBalance[] = [];
    for await (const page of result) {
        balances.push(...page.result.erc20TokenBalances);
    }
    return balances
}
```
</Accordion>
</Accordions>
</Step>
</Steps>
### Modify Frontend `src/app/balance-app/page.tsx`

<Steps>
<Step>
</Step>
<Step>
First we will implement the `fetchERC20Balances` function. The goal of this function is to make a call to our backend to get the user's ERC-20 token balances.
<Accordions>
<Accordion title="Hint">
Make a call to our backend first for the most recent block height, then our `listErc20Balances` API. Finally return the results.
</Accordion>
<Accordion title="Solution">
```tsx title="src/app/balance-app/page.tsx"
const fetchERC20Balances = async (address: string) => {
    const blockResult = await fetch("api/balance?method=getBlockHeight");
    const blockNumber = await blockResult.json();
    const balanceResult = await fetch("api/balance?method=listErc20Balances&address=" + address + "&blockNumber=" + blockNumber);
    const balances = await balanceResult.json();
    return balances as Erc20TokenBalance[];
};
```
</Accordion>
</Accordions>
</Step>
<Step>
Next we will implement the `handleSetAddress` function. The goal of this function is to set the address in the state and fetch the ERC-20 token balances for that address using our `fetchERC20Balances` function.
<Accordions>
<Accordion title="Hint">
First make sure the address is valid, then update the state for `Address` and `Balances`
</Accordion>
<Accordion title="Solution">
```tsx title="src/app/balance-app/page.tsx"
const handleSetAddress = async () => {
    const addressInput = document.getElementById("address") as HTMLInputElement;
    const address = addressInput.value;
    const addressPattern = /^0x[a-fA-F0-9]{40}$/;  

    if (addressInput && addressPattern.test(address)) {
      setAddress(address);
      setBalances(await fetchERC20Balances(address));
    }
};
```
</Accordion>
</Accordions>
</Step>


</Steps>


# Final Result (/academy/avacloudapis/04-erc20-token-balance-app/04-final)

---
title: Final Result
description: The final result of the ERC-20 token balance app.
updated: 2024-09-03
authors: [owenwahlgren]
icon: Book
---

If we implemented the code correctly, we should have a working ERC-20 token balance app that displays the user's token balances. The app will look like the following:
![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/avacloudsdk/balance-app-init-bIVbTrMxCmFteBLTTcDRHGuVU75Kcd.png)

After setting the address field, the app will display the user's ERC-20 token balances:

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/avacloudsdk/balance-app-9ggCriiHBsggku1bFGF8tL1lyThSx4.png)

Notice how the app also displays images for each token. This is done by fetching the token metadata from `listErc20Balances` and displaying the token's logo.

# Overview (/academy/avacloudapis/05-wallet-portfolio-app/01-overview)

---
title: Overview
description: Use the Data API to create a simple web app that displays data and metrics on a connected wallet.
updated: 2024-09-13
authors: [owenwahlgren]
icon: Book
---

In this section we will expand on the ERC-20 Balance App with NFTs (ERC-721) and ERC-1155 tokens. We will also add a connect wallet button to allow users to connect their own wallet and view their own token balances.

Here is a preview of what we will build:
![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/avacloudsdk/nfts-v4LwE4Ij450GkYThM5JQG7ghKtT1LQ.png)
![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/avacloudsdk/tokens-ILhHQF5XpddcXcg3pbyG6aQ8hbd9XJ.png)

We will use a few additional endpoints from the Data API to accomplish this:

- [`data.evm.balances.listErc721Balances`](https://developers.avacloud.io/data-api/evm-balances/list-erc-721-balances)
- [`data.evm.balances.listErc1155Balances`](https://developers.avacloud.io/data-api/evm-balances/list-erc-1155-balances)
- [`data.evm.transactions.listTransactions`](https://developers.avacloud.io/data-api/evm-transactions/list-transactions)

# Understanding the Code (/academy/avacloudapis/05-wallet-portfolio-app/02-understanding-code)

---
title: Understanding the Code
description: Before we start coding, let's take a look at the code we will be working with.
updated: 2024-09-13
authors: [owenwahlgren]
icon: Book
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

There will be two main files that we will be working with in this section.

<Steps>
<Step>

### `Page.tsx`
This is the code that will be rendered on the client side, as distinguished by `"use client";` at the top of the file. It contains the React components that will be displayed to the user and is responsible for making the API calls to our backend, which in turn calls the Data API.

It is important to understand that when you `"use client"` in a NextJS project, it will be rendered on the client side. This means that the code will be executed in the user's browser and not on the server. This is important to keep in mind when working with sensitive data or when you want to keep your API keys secure.

Besides this, we have three main functions that we will be working with in this file:

<Steps>
<Step>
```tsx title="src/app/basic-wallet/page.tsx"
const fetchERC721Balances = async (address: string) => {
    //
    // TODO: Implement this!
    //
    return [] as Erc721TokenBalance[];
  }
```
`fetchERC721Balances` is a function that will make a call to our backend to get the user's ERC-721 token balances. It will call the `listErc721Balances` method on our backend with the user's address. It will then return the balances as an array of `Erc721TokenBalance` objects.

</Step>
<Step>
```tsx title="src/app/basic-wallet/page.tsx"
const fetchERC1155Balances = async (address: string) => {
     //
    // TODO: Implement this!
    //
    return [] as Erc1155TokenBalance[];
  }
```

`fetchERC1155Balances` is a function that will make a call to our backend to get the user's ERC-1155 token balances. It will call the `listErc1155Balances` method on our backend with the user's address. It will then return the balances as an array of `Erc1155TokenBalance` objects.

</Step>
<Step>
```tsx title="src/app/basic-wallet/page.tsx"
  const fetchRecentTransactions = async (address: string) => {
    //
    // TODO: Implement this!
    //
    return {} as TransactionDetails;
  }
```
`fetchRecentTransactions` is a function that will make a call to our backend to get the user's recent transactions for all tokens. It will call the `listRecentTransactions` method on our backend with the user's address. It will then return the balances as an object of type `TransactionDetails`.

</Step>
</Steps>

</Step>
<Step>

### `Route.ts`
This code will be executed on the server side, as distinguished by `"use server";` at the top of the file. It contains the code that will be executed on the server side and is responsible for making the API calls to the Data API.

There are a few key components to understand in this file:

<Steps>
<Step>
```tsx title="src/app/api/wallet/route.ts"
import { AvaCloudSDK } from "@avalabs/avacloud-sdk";
const avaCloudSDK = new AvaCloudSDK({
  apiKey: process.env.AVACLOUD_API_KEY,
  chainId: "43114", // Avalanche Mainnet
  network: "mainnet",
});
```
Here we initialize the `AvaCloudSDK` with our AvaCloud API key and the chainId of `43114` for the Avalanche Mainnet. This will allow us to make calls to the Data API.
</Step>
<Step>

```tsx title="src/app/api/wallet/route.ts"
export async function GET(request: Request) {
  const { searchParams } = new URL(request.url)
  const method = searchParams.get('method')
  let address
  try {
    let result
    switch (method) {
      case 'listERC721Balances':
        address = searchParams.get('address')!
        result = await listERC721Balances(address)
        break
      case 'listERC1155Balances':
        address = searchParams.get('address')!
        result = await listErc1155Balances(address)
        break
      case 'listRecentTransactions':
        address = searchParams.get('address')!
        result = await listRecentTransactions(address)
        break
      default:
        return NextResponse.json({ error: 'Invalid method' }, { status: 400 })
    }
    return NextResponse.json(result)
  } catch (error) {
    return NextResponse.json({ error: 'Internal Server Error' }, { status: 500 })
  }
}
```
Here we define the internal API methods for our backend. We have two methods that we will be working with in this section: `getBlockHeight`, `listERC721Balances`, `listErc1155Balances` and `listRecentTransactions`. We create all of these methods internally, then forward the request to the Data API. We then return the result to the client.
</Step>
<Step>
```tsx title="src/app/api/wallet/route.ts"
async function getBlockHeight() {
    //
    // TODO: Implement this!
    //
    return
}

const listERC721Balances = async (address: string) => {
    //
    // TODO: Implement this!
    //
    return
}

const listErc1155Balances = async (address: string) => {
    //
    // TODO: Implement this!
    //
    return
}

const listRecentTransactions = async (address: string) => {
    //
    // TODO: Implement this!
    //
    return
}
```
In the next section, we will implement these functions to call the Data API through the AvaCloudSDK.
</Step>
</Steps>
</Step> 
</Steps> 

# Modifying the Code (/academy/avacloudapis/05-wallet-portfolio-app/03-modifying-code)

---
title: Modifying the Code
description: Lets modify the code to implement the Data API.
updated: 2024-09-13
authors: [owenwahlgren]
icon: Book
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

In this section, we will modify the code to implement the Data API. 

### Modify Backend `src/app/api/wallet/route.ts`
<Steps>
<Step>
First we will implement the `getBlockHeight` function. This function is the same as the one in ERC20 Balance App, but we will repeat it for the sake of the tutorial. The goal of this function is to fetch recent blocks from the Data API then to return the highest block in the first position.

<Accordions>
<Accordion title="Hint">
Reference the [AvaCloud SDK documentation](https://developers.avacloud.io/data-api/evm-blocks/list-latest-blocks) to see how to fetch the latest blocks.
</Accordion>
<Accordion title="Solution">
```tsx title="src/app/api/wallet/route.ts"
async function getBlockHeight() {
    const result = await avaCloudSDK.data.evm.blocks.getLatestBlocks({
        pageSize: 1,
      });
    return result.result.blocks[0].blockNumber
}
```
</Accordion>
</Accordions>
</Step>
<Step>
Next we will implement the `listERC721Balances` function. The goal of this function is to fetch the ERC-721 token balances for a given address.
<Accordions>
<Accordion title="Hint">
Reference the [AvaCloud SDK documentation](https://developers.avacloud.io/data-api/evm-balances/list-erc-721-balances) to see how to fetch ERC-721 token balances.
Note the `Erc721TokenBalance` type that is imported, we should use this to combine paged results.
</Accordion>
<Accordion title="Solution">
```tsx title="src/app/api/wallet/route.ts"
const listERC721Balances = async (address: string) => {
    const result = await avaCloudSDK.data.evm.balances.listErc721Balances({
        pageSize: 10,
        address: address,
      });
    const balances: Erc721TokenBalance[] = [];
    for await (const page of result) {
        balances.push(...page.result.erc721TokenBalances);
    }
    return balances
}
```
</Accordion>
</Accordions>
</Step>
<Step>
Now we will implement the `listErc1155Balances` function. The goal of this function is to fetch the ERC-1155 token balances for a given address.
<Accordions>
<Accordion title="Hint">
Reference the [AvaCloud SDK documentation](https://developers.avacloud.io/data-api/evm-balances/list-erc-1155-balances) to see how to fetch ERC-1155 token balances.
Note the `Erc1155TokenBalance` type that is imported, we should use this to combine paged results.
</Accordion>
<Accordion title="Solution">
```tsx title="src/app/api/wallet/route.ts"
const listErc1155Balances = async (address: string) => {
    const result = await avaCloudSDK.data.evm.balances.listErc1155Balances({
        pageSize: 10,
        address: address,
      });
    const balances: Erc1155TokenBalance[] = [];
    for await (const page of result) {
        balances.push(...page.result.erc1155TokenBalances);
    }
    return balances
}
```
</Accordion>
</Accordions>
</Step>

<Step>
Finally we will implement the `listRecentTransactions` function. The goal of this function is to fetch recent transactions for a given address given a block start and end.
<Accordions>
<Accordion title="Hint">
Reference the [AvaCloud SDK documentation](https://developers.avacloud.io/data-api/evm-transactions/list-transactions) to see how to fetch recent transactions.
Note the `TransactionDetails` type that is imported, we should use this to combine and sort paged results.
</Accordion>
<Accordion title="Solution">
```tsx title="src/app/api/wallet/route.ts"
const listRecentTransactions = async (address: string) => {
    const blockHeight = await getBlockHeight()
    const result = await avaCloudSDK.data.evm.transactions.listTransactions({
        pageSize: 10,
        startBlock: blockHeight - 100000,
        endBlock: blockHeight,
        address: address,
        sortOrder: "desc",
      });
    const transactions: TransactionDetails = {
        erc20Transfers: [],
        erc721Transfers: [],
        erc1155Transfers: [],
        nativeTransaction: {
            blockNumber: '',
            blockTimestamp: 0,
            blockHash: '',
            blockIndex: 0,
            txHash: '',
            txStatus: '',
            txType: 0,
            gasLimit: '',
            gasUsed: '',
            gasPrice: '',
            nonce: '',
            from: {
                name: undefined,
                symbol: undefined,
                decimals: undefined,
                logoUri: undefined,
                address: ''
            },
            to: {
                name: undefined,
                symbol: undefined,
                decimals: undefined,
                logoUri: undefined,
                address: ''
            },
            value: ''
        },
    }
    for await (const page of result) {
        for (const transaction of page.result.transactions) {
            if (transaction.erc20Transfers) {
                if (transactions.erc20Transfers) {
                    transactions.erc20Transfers.push(...transaction.erc20Transfers);
                }
            } 
            else if (transaction.erc721Transfers) {
                if (transactions.erc721Transfers) {
                    transactions.erc721Transfers.push(...transaction.erc721Transfers);
                }
            }
            else if (transaction.erc1155Transfers) {
                if (transactions.erc1155Transfers) {
                    transactions.erc1155Transfers.push(...transaction.erc1155Transfers);
                }
            }
        }
    }
    return transactions
}
```
</Accordion>
</Accordions>
</Step>


</Steps>
### Modify Frontend `src/app/basic-wallet/page.tsx`
Now we will modify the frontend to make calls to our backend.
<Steps>
<Step>
</Step>
<Step>
First we will implement the `fetchERC20Balances` function. The goal of this function is to make a call to our backend to get the user's ERC-20 token balances.
<Accordions>
<Accordion title="Hint">
Make a call to our backend first for the most recent block height, then our `listErc20Balances` API. Finally return the results.
</Accordion>
<Accordion title="Solution">
```tsx title="src/app/basic-wallet/page.tsx"
const fetchERC20Balances = async (address: string) => {
    const blockResult = await fetch("api/balance?method=getBlockHeight");
    const blockNumber = await blockResult.json();
    const balanceResult = await fetch("api/balance?method=listErc20Balances&address=" + address + "&blockNumber=" + blockNumber);
    const balances = await balanceResult.json();
    return balances as Erc20TokenBalance[];
};
```
</Accordion>
</Accordions>
</Step>
<Step>
Next we will implement the `fetchERC721Balances` function. The goal of this function is to call our `listErc721Balances` function on the backend and return it as a `Erc721TokenBalance` array.
<Accordions>
<Accordion title="Hint">
Make a call to our backend then parse the result as json. Return it as `Erc721TokenBalance[]`.
</Accordion>
<Accordion title="Solution">
```tsx title="src/app/basic-wallet/page.tsx"
const fetchERC721Balances = async (address: string) => {
    const result = await fetch(`api/wallet?method=listERC721Balances&address=${address}`);
    const balances = await result.json();
    return balances as Erc721TokenBalance[];
  }
```
</Accordion>
</Accordions>
</Step>

<Step>
Now we will implement the `fetchERC1155Balances` function. The goal of this function is to call our `listERC1155Balances` function on the backend and return it as a `Erc1155TokenBalance` array.
<Accordions>
<Accordion title="Hint">
Make a call to our backend then parse the result as json. Return it as `Erc1155TokenBalance[]`.
</Accordion>
<Accordion title="Solution">
```tsx title="src/app/basic-wallet/page.tsx"
const fetchERC1155Balances = async (address: string) => {
    const result = await fetch(`api/wallet?method=listERC1155Balances&address=${address}`);
    const balances = await result.json();
    return balances as Erc1155TokenBalance[];
  }
```
</Accordion>
</Accordions>
</Step>

<Step>
Finally we will implement the `fetchRecentTransactions` function. The goal of this function is to call our `listRecentTransactions` function on the backend and return it as an object of type `TransactionDetails`.
<Accordions>
<Accordion title="Hint">
Make a call to our backend then parse the result as json. Return it as type of `TransactionDetails`.
</Accordion>
<Accordion title="Solution">
```tsx title="src/app/basic-wallet/page.tsx"
const fetchRecentTransactions = async (address: string) => {
    const result = await fetch(`api/wallet?method=listRecentTransactions&address=${address}`);
    const transactions = await result.json();
    return transactions as TransactionDetails;
  }
```
</Accordion>
</Accordions>
</Step>
</Steps>

# Overview (/academy/avacloudapis/06-block-explorer-app/01-overview)

---
title: Overview
description: Use the Data API to create a simple block explorer.
updated: 2024-09-13
authors: [owenwahlgren]
icon: Book
---
In this section we will build a basic block explorer using the Data API.

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/avacloudsdk/explorer-Uahzju9LouXAGd61AQvm38Vxtq4cG5.png)

We will use a couple additional endpoints from the Data API to accomplish this:

- [`data.evm.blocks.getBlockHeight`](https://developers.avacloud.io/data-api/evm-blocks/list-latest-blocks)
- [`data.evm.transactions.listLatestTransactions`](https://developers.avacloud.io/data-api/evm-transactions/list-latest-transactions)

# Understanding the Code (/academy/avacloudapis/06-block-explorer-app/02-understanding-code)

---
title: Understanding the Code
description: Before we start coding, let's take a look at the code we will be working with.
updated: 2024-10-09
authors: [owenwahlgren]
icon: Book
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

There will be two main files that we will be working with in this section.

<Steps>
<Step>

### `Page.tsx`
This is the code that will be rendered on the client side, as distinguished by `"use client";` at the top of the file. It contains the React components that will be displayed to the user and is responsible for making the API calls to our backend, which in turn calls the Data API.

It is important to understand that when you `"use client"` in a NextJS project, it will be rendered on the client side. This means that the code will be executed in the user's browser and not on the server. This is important to keep in mind when working with sensitive data or when you want to keep your API keys secure.

Besides this, we have three main functions that we will be working with in this file:

<Steps>
<Step>
```tsx title="src/app/basic-explorer/page.tsx"
const fetchRecentTransactions = async () => {
    //
    // TODO: Implement this!
    //
    return data as NativeTransaction[]
  }
```
`fetchRecentTransactions` is a function that will make a call to our backend to get the most recent transactions from the chain. It will call the `getRecentTransactions` method on our backend. It will then return the transactions as an array of `NativeTransaction` objects.

</Step>
<Step>
```tsx title="src/app/basic-explorer/page.tsx"
const fetchRecentBlocks = async () => {
    //
    // TODO: Implement this!
    //
    return data as EvmBlock[]
  }
```

`fetchRecentBlocks` is a function that will make a call to our backend to get the most recent blocks from the chain. It will call the `getRecentBlocks` method on our backend. It will then return the blocks as an array of `EvmBlock` objects.

</Step>
</Steps>

</Step>
<Step>

### `Route.ts`
This code will be executed on the server side, as distinguished by `"use server";` at the top of the file. It contains the code that will be executed on the server side and is responsible for making the API calls to the Data API.

There are a few key components to understand in this file:

<Steps>
<Step>
```tsx title="src/app/api/explorer/route.ts"
import { AvaCloudSDK } from "@avalabs/avacloud-sdk";
const avaCloudSDK = new AvaCloudSDK({
  apiKey: process.env.AVACLOUD_API_KEY,
  chainId: "43114", // Avalanche Mainnet
  network: "mainnet",
});
```
Here we initialize the `AvaCloudSDK` with our AvaCloud API key and the chainId of `43114` for the Avalanche Mainnet. This will allow us to make calls to the Data API.
</Step>
<Step>

```tsx title="src/app/api/explorer/route.ts"
export async function GET(request: Request) {
  const { searchParams } = new URL(request.url)
  const method = searchParams.get('method')
  try {
    let result
    switch (method) {
      case 'getRecentTransactions':
        result = await getRecentTransactions()
        break
      case 'getRecentBlocks':
        result = await getRecentBlocks()
        break
      default:
        return NextResponse.json({ error: 'Invalid method' }, { status: 400 })
    }
    return NextResponse.json(result)
  } catch (error) {
    return NextResponse.json({ error: 'Internal Server Error' }, { status: 500 })
  }
}
```
Here we define the internal API methods for our backend. We have two methods that we will be working with in this section: `getRecentBlocks` and `getRecentTransactions`. We create all of these methods internally, then forward the request to the Data API. We then return the result to the client.
</Step>
<Step>
```tsx title="src/app/api/explorer/route.ts"
const getRecentBlocks = async () => {
   //
    // TODO: Implement this!
    //
}

const getRecentTransactions = async () => {
    //
    // TODO: Implement this!
    //
}
```
In the next section, we will implement these functions to call the Data API through the AvaCloudSDK.
</Step>
</Steps>
</Step> 
</Steps> 

# Modifying the Code (/academy/avacloudapis/06-block-explorer-app/03-modifying-code)

---
title: Modifying the Code
description: Lets modify the code to implement the Data API.
updated: 2024-10-09
authors: [owenwahlgren]
icon: Book
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

In this section we will modify the code to implement the Data API.

### Modify Backend `src/app/api/explorer/route.ts`

<Steps>
<Step>
First we will implement the `getRecentBlocks` function. The goal of this function is to fetch recent blocks from the Data API with all its information.

<Accordions>
<Accordion title="Hint">
Reference the [AvaCloud SDK documentation](https://developers.avacloud.io/data-api/evm-blocks/list-latest-blocks) to see how to fetch the latest blocks.
</Accordion>
<Accordion title="Solution">
```tsx title="src/app/api/explorer/route.ts"
const getRecentBlocks = async () => {
    const result = await avaCloudSDK.data.evm.blocks.getLatestBlocks({
        pageSize: 1,
      });

    let count = 0;
    const blocks: EvmBlock[] = [];
    for await (const page of result) {
        if (count === 20) {
            break;
        }
        blocks.push(...page.result.blocks);
        count++;
    }
    return blocks
}
```
</Accordion>
</Accordions>
</Step>
<Step>
Next we will implement the `getRecentTransactions` function. The goal of this function is to fetch all native token transfers from the Data API.
<Accordions>
<Accordion title="Hint">
Reference the [AvaCloud SDK documentation](https://developers.avacloud.io/data-api/evm-transactions/list-latest-transactions) to see how to fetch latest transactions.
Note the `NativeTransaction` type that is imported, we should use this to combine paged results.
</Accordion>
<Accordion title="Solution">
```tsx title="src/app/api/explorer/route.ts"
const getRecentTransactions = async () => {
    const result = await avaCloudSDK.data.evm.transactions.listLatestTransactions({
        pageSize: 3,
    });

    let count = 0;
    const transactions: NativeTransaction[] = [];
    for await (const page of result) {
        if (count === 20) {
            break;
        }
        transactions.push(...page.result.transactions);
        count++;
    }
    return transactions;
}
```
</Accordion>
</Accordions>
</Step>
</Steps>
### Modify Frontend `src/app/basic-explorer/page.tsx`

<Steps>
<Step>
</Step>
<Step>
First we will implement the `fetchRecentTransactions` function. The goal of this function is to make a call to our backend to get recent transactions.
<Accordions>
<Accordion title="Hint">
Make a call to our backend first for our `getRecentTransactions` method. Finally return the results.
</Accordion>
<Accordion title="Solution">
```tsx title="src/app/basic-explorer/page.tsx"
  const fetchRecentTransactions = async () => {
    const response = await fetch(`/api/explorer?method=getRecentTransactions`)
    const data = await response.json()
    return data as NativeTransaction[]
  }
```
</Accordion>
</Accordions>
</Step>
<Step>
Next we will implement the `fetchRecentBlocks` function. The goal of this function is to make a call to our backend to get recent block information.
<Accordions>
<Accordion title="Hint">
Make a call to our backend first for our `getRecentBlocks` method. Finally return the results.
</Accordion>
<Accordion title="Solution">
```tsx title="src/app/basic-explorer/page.tsx"
const fetchRecentBlocks = async () => {
    const response = await fetch(`/api/explorer?method=getRecentBlocks`)
    const data = await response.json()
    return data as EvmBlock[]
  }
```
</Accordion>
</Accordions>
</Step>


</Steps>


# Overview (/academy/avacloudapis/07-using-webhooks/01-overview)

---
title: Overview
description: Coming soon!
updated: 2024-09-13
authors: [owenwahlgren]
icon: Book
---


# Avalanche Consensus (/academy/avalanche-fundamentals/02-avalanche-consensus-intro/01-avalanche-consensus-intro)

---
title: Avalanche Consensus
description: Learn how blockchains arrive at consensus using different mechanisms.
updated: 2024-05-31
authors: [martineckardt]
icon: Book
---

<YouTube id="3cAFxV2AIU8" />

Avalanche Consensus is a novel consensus protocol that is used in the Avalanche network. It is a leaderless, decentralized, and scalable consensus protocol that is used to achieve consensus on the state of the network.

<Quiz quizId="101"/>

## What You Will Learn

In this section, you will go through the following topics:

- **Consensus Mechanisms:** Understand what consensus mechanisms are and how they work
- **Snowman Consensus:** Learn about the Snowman consensus protocol
- **TPS vs TTF:** Understand the difference between transactions per second (TPS) and time to finality (TTF)


# Consensus Mechanisms (/academy/avalanche-fundamentals/02-avalanche-consensus-intro/02-consensus-mechanisms)

---
title: Consensus Mechanisms
description: Learn how blockchains arrive at consensus using different mechanisms.
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

Consensus plays a crucial role in [blockchain networks](/guides/what-is-a-blockchain) by resolving conflicts and ensuring that all validators agree on the current state of the distributed ledger. The main objective of a consensus mechanism is to create a single version of truth that is universally accepted by network participants.

Validators can reach a consensus by following a set of steps called a consensus protocol. This way, they collectively decide on the state of the system and all state changes. Different consensus mechanisms have different approaches. All aim to ensure that validators reach a majority agreement on network state. 

## Ordering through Consensus

Consensus is needed to agree on the order of state changes in a blockchain. This allows the validators to decide between two conflicting states.

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/avalanche-fundamentals/1-aWL9i9BFicUEF7ntMjBFuUejfadAUS.png)

<Quiz quizId="102"/>

## Double Spending Attack

A Double Spending Attack is when a user attempts to spend more crypto than they own by creating multiple transactions that reference the same funds.

Let's look at an Example: Alice owns 5 AVAX

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/avalanche-fundamentals/2-2fU6eqsUiCq76Sy04VEfvD5rLo3eVc.png)

Now Alice issues two transactions at the same time to different validators:

1. Send 5 AVAX to Bob
2. Send 5 AVAX to Charly

It is important that there is only a limited notion of time in blockchain systems. Even if Alice does not issue these transactions at the exact same time, validators cannot identify which was issued first.

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/avalanche-fundamentals/3-8GHqtWHuf44Nilsugj6yC9sC0BFsZh.png)

Each of the transaction in itself is valid. Alice owns 5 AVAX and should be able to send them to whomever she wants. However, she should only be able to send the amount she actually owns.

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/avalanche-fundamentals/4-GeSctGjJKsmXFWvwMpZmYpDcGquZcg.png)

Therefore, validators have to collectively come to consensus on which of the two conflicting transactions will be included in the blockchain first, and therefore be accepted by all validators as the next state. To illustrate, we will color the validators preferring Charlie yellow and the validators preferring Bob blue.

<Quiz quizId="103"/>


# Snowman Consensus (/academy/avalanche-fundamentals/02-avalanche-consensus-intro/03-snowman-consensus)

---
title: Snowman Consensus
description: Learn about the Avalanche Snowman consensus protocol.
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

Protocols in the Avalanche family operate through repeated sub-sampled voting. When a validator is determining whether a block should be accepted, it asks a small, random subset of validators on their preferences. Based on the responses the validator gets, it might change its own preference.

Let's visualize this with an example. You are a validator in a set of validators that is performing the Avalanche Consensus protocol to agree on whether to send the funds to Charlie (yellow) or to Bob (blue). It is important to understand that none of the validators really cares whether it is going to be yellow or blue, as long as all correctly operating validators decide for the same outcome at the end of the process. The starting preference is chosen randomly by each validator.

## Changing Preference

You start by sampling the current preference of five other nodes and they reply: 2 prefer yellow (Charlie) and 3 prefer blue (Bob). 

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/avalanche-fundamentals/5-f6WnJHv0VAKRNOSd8gFHbO2Mar4mWl.png)

Avalanche consensus dictates that a validator changes its preference if an α-majority of the sampled validators agree on another option, and it goes along with this popular choice. 

Let's set the alpha value to 3 in our example, meaning that we change our preference when 3 out of 5 sampled nodes have another preference. Since 3 out of 5 have replied with blue (Bob) we are changing our own preference to Bob. 

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/avalanche-fundamentals/6-TscORkJchAtrT2rG8rG5CPFPilUR1b.png)

From now on you will respond with blue, when another validators queries you for your current preference. 

<Quiz quizId="104"/>

## Consecutive Successes

Avalanche Consensus does not run for a fixed number of rounds, but until a decision threshold is hit. This means the validator keeps sampling until their preference is confirmed for beta (β) consecutive rounds.

Now you query another five validators for their preference. Again, three of the five reply with the preference blue (Bob). Since your current preference is confirmed, you increment a counter for consecutive successes by one. You repeat this sampling process until their preference is confirmed for 8 consecutive rounds. 

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/avalanche-fundamentals/7-KYmL0QWax9tmW7uT8bdqu9R5sNwgSs.png)

## Parameters of Avalanche Consensus

In our example we used fixed values for how many nodes are sampled, how many are needed to change our preference and how many consecutive rounds of successes we require to finalize our decision. These consensus parameters are formalized in the table below and can be chosen by every node individually to meet their needs.

|Symbol|Name|Range|Explanation|
|---|---|---|---|
|n  |Number of Participants|1 to ∞|How many participants take part in the system?|
|k  |Sample Size|1 to n|How many of these participants get asked every round of sub-sampling?|
|α  |Quorum Size|1 to k|How many of the asked participants have to have the same preference for me to change my preference?|
|β  |Decision Threshold|>= 1|How many times does the quorum have to confirm my preference until I finalize my decision?|

With these parameters we can illustrate the consensus algorithm as pseudo code:

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/avalanche-fundamentals/8-XzHBlGu1fdnPniQecAkpFfC5JTegVD.png)


## Finalization

In the common case when a transaction has no conflicts, finalization happens very quickly. When conflicts exist, honest validators quickly cluster around conflicting transactions, entering a positive feedback loop until all correct validators prefer that transaction. This leads to the acceptance of non-conflicting transactions and the rejection of conflicting transactions.

Avalanche Consensus guarantees (with high probability based on system parameters) that if any honest validator accepts a transaction, all honest validators will come to the same conclusion.

<Quiz quizId="105"/>


# Throughput vs. Time to Finality (/academy/avalanche-fundamentals/02-avalanche-consensus-intro/04-tps-vs-ttf)

---
title: Throughput vs. Time to Finality
description: Learn how metrics like throughput and time to finality are different.
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

To measure blockchain performance we can use two metrics:

- Throughput: How many transaction are finalized per second measured in transactions per second (TPS)
- Time to Finality: How long does it take a transaction to go from being submitted to validators to being unchangeable. 

These metrics are very different. Blockchain builders aspire to high throughput and very short time to finality.

## Highway Analogy

Let's take an analogy of a highway. Each car represents a transaction and they all travel the same speed. When you click *send* in your wallet, you're like a car entering the highway. When the transaction is *finalized* and unchangeable, it's like the car reaching its destination.

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/avalanche-fundamentals/9-JT3ORUzCZAILlQJjQaY2nJvFZHEVRL.png)

Throughput could be likened to the number of lanes, determining how many cars can pass on the highway in a given amount of time. The more lanes you have, the more cars can pass through, thus increasing the throughput. In a blockchain network, increasing the block size (analogous to adding more lanes) can increase throughput.

Now, imagine you're driving to a specific destination (finality). The time it takes you to get from your starting point (initiation of the transaction) to your destination (confirmation of the transaction) is analogous to the "time to finality." As soon as a car reaches finality, it cannot return or abort the travel.

Our goal is to build highways with many lanes (high throughput) but that bring us to our destination as fast as possible (short time to finality).

### Throughput and Finality of Popular Blockchain Networks

|Network|Throughput|Time to Finality|
|---|---|---|
|Bitcoin|7 TPS|60 min|
|Ethereum|30 TPS|6.4 min|
|Avalanche / Avalanche L1|2500 TPS|~0.8 seconds|

**TPS** &rarr; **Transactions per Second**

Returning to the highway analogy, these networks would look like this:

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/avalanche-fundamentals/10-M9xrguxF39gS0MkB03LHE1DcNDGsIV.png)

<Quiz quizId="1201"/>


# Multi-Chain Architecture (/academy/avalanche-fundamentals/03-multi-chain-architecture-intro/01-multi-chain-architecture)

---
title: Multi-Chain Architecture
description: Learn about the Multi-Chain Architecture.
updated: 2024-05-31
authors: [ashucoder9]
icon: Book
---

Multi-chain systems are a significant innovation, which provide greater scalability, customizability, and independence. At the core of multi-chain systems is the ability to run multiple blockchains simultaneously. Each blockchain is optimized for specialized use cases, thereby boosting the network's overall performance.

## What You Will Learn

In this section, you will go through the following topics:

- **Avalanche L1s:** Understand what Avalanche L1s are and how they work
- **Setup Core Wallet:** Learn how to setup the Core wallet browser extension
- **Use Dexalot:** Use your first Avalanche L1


# Avalanche L1s (/academy/avalanche-fundamentals/03-multi-chain-architecture-intro/02-L1)

---
title: Avalanche L1s
description: Learn about the Multi-Chain Architecture.
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

> An Avalanche L1 is an independent blockchain with its own set of rules regarding validator membership, tokenomics,
and the execution layer. It has it's own validator set that comes to consensus and validates the blockchain. 

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/l1s.png)

These specialized L1 blockchains can be tailored to meet specific needs for a variety of applications,
including DeFi, NFTs, gaming, and enterprise solutions.

- They specify their own execution logic.
- They determine their own fee structures.
- They maintain their own state.
- They facilitate their own networking.
- They provide their own security.

This independence ensures that L1s don't have to share execution threads, storage, or networking with other L1s networks or the Primary Network. 

## Avalanche Network

The Avalanche network is a network of independent interoperable L1s. They can communicate with
each other and assets can be transferred between them, while they maintain interoperability. As a result, the Avalanche network can:

- Scale up easily
- Achieve higher overall transactions per second (TPS)
- Offer lower transaction costs

By leveraging L1s, Avalanche creates a flexible and scalable ecosystem that can adapt to a wide range of use cases and requirements.

<Quiz quizId="106"/>

# Features & Benefits of Avalanche L1s (/academy/avalanche-fundamentals/03-multi-chain-architecture-intro/03-benefits)

---
title: Features & Benefits of Avalanche L1s
description: Learn about various benefits of using Avalanche L1s, such as Scalability, Independence, Customizability, Privacy, and Interoperability.
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

## Scalability of the Avalanche Network

Every blockchain has a limited capacity for computation and data storage. Therefore, the
transactions it can process in a given time frame and the state it can store are limited. In order
to scale horizontally and to offer more blockspace, we can just add more blockchains to the
Avalanche Network.

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/avalanche-fundamentals/11-KyUqqw9iwrH60hF4wnYPOWRTBOGRhT.png)

We can use the analogy of a highway to visualize this concept. A highway can only handle a certain
number of cars at a time. If too many cars try to enter the highway at once, traffic congestion will
occur and they have to wait to enter the highway. The idea is similiar to building many highways in
parallel and create additional space for cars to drive on. This allows for more transactions to be
processed in parallel, and therefore increases the overall throughput of the network.

The beauty of this approach is its simplicity. It doesn't require any new untested innovations. The challenge, rather, is optimizing how Avalanche L1s interoperate and making switching from one Avalanche L1 to the other easy.

## Independence From Other Avalanche L1s

Separating the ecosystem into different chains creates independence from another. If congestion
builds on one chain due to high network activity (e.g. an NFT drop, high volatility in token prices,
new game launched), other chains are unaffected. One chain's congestion or increasing fees won't
impact other chains. Going back to our highway analogy, we can think of the scaling through multiple
chains as building many short highways in parallel.

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/avalanche-fundamentals/12-B730ft1bJPU6lxd3G4B7rpdExaNuC6.png)

Coming back to our highway analogy, we can imagine a scenario where congestion builds up on one highway. The other highways are not directly affected. Some cars may choose to take a different highway and the traffic bottleneck may decrease.

In single-chain systems, like Ethereum, congestion and rising fees affect everyone, including parties
that have nothing to do with the cause of the activity increase. While the unified, or monolithic,
blockchain design does offer certain advantages (like unified liquidity, fewer bridges, and
potential for enhanced user experience via co-location of dApps), it also introduces notable
drawbacks. 

Validators must have powerful, costly machines to support a diverse array of applications, increasing centralization due to high operational costs of running a node. Lack of modularity can halt all on-chain activities during network disruptions, potentially causing significant financial losses. Additionally, each new dApp competes for the same block space as all others, leading to overcrowding.

<Quiz quizId="107"/>

## Customizability

The creator of an Avalanche L1 can customize it to meet their needs. This can happen in numerous
ways, including introducing a custom own gas token, using a different Virtual Machine (e.g. a WASM
or Move VM), or limiting access to the Avalanche L1. This is very hard to do in a single-chain
system because it would require a majority of users to agree.

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/avalanche-fundamentals/13-VegJrRJXmD83CRfgpx2wTbzLkszjBB.png)

In our highway analogy, let's think of some travelers having a very unique requirement: They would
like to travel by boat instead of a car. While technically possible to build a water lane on a
single highway system, this would be challenging. However, when these custom requirements are met in
a Avalanche L1, it's easy to do.

The ability to choose or create custom Virtual Machines (VMs) offers unprecedented flexibility.
Avalanche L1s allow for developers to have: 

- Multiple VM Support: Unlike single-VM networks like Bitcoin or Ethereum, Avalanche L1s can host
  multiple blockchain instances with different VMs.
- Ease of Use: Leverage existing VMs like the Subnet-EVM or create entirely new custom VMs using our
  SDKs to suit your specific needs.
- Network Effects: This flexible architecture creates network effects both within individual
  blockchains and across different Avalanche L1s and blockchains.

<Quiz quizId="401"/>

## Enhanced Privacy, Compliance and Access Control

While public blockchains offer transparency, many business scenarios require controlled visibility
of transaction data. Developers building an Avalanche L1 can optionally enable: 

- Selective Transparency: Private blockchains allow you to limit transaction visibility to
  authorized participants.
- Data Protection: Implement transaction encryption to safeguard sensitive information.
- Granular Access: Control which data is visible to which participants, supporting "need-to-know"
  access models.

## Interoperability

Avalanche L1s come with native interoperability and can leverage:

- Cross-Chain Communication: Facilitate seamless interaction between different custom blockchains in
  the Avalanche network leverage Avalanche Interchain Messaging.
- Asset Bridges: Create efficient bridges for asset transfers between your custom blockchain and
  other networks such as the Avalanche Interchain Token Transfer.

# Avalanche9000 Upgrade (/academy/avalanche-fundamentals/03-multi-chain-architecture-intro/03a-etna-upgrade)

---
title: Avalanche9000 Upgrade
description: Learn about how the Avalanche9000 upgrade changes the network architecture.
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

import EtnaUpgradeMotivation from '@/content/common/multi-chain-architecture/etna-upgrade-motivation.mdx';

<EtnaUpgradeMotivation />

<Quiz quizId="1202"/>

# Avalanche L1s vs Layer 2 (/academy/avalanche-fundamentals/03-multi-chain-architecture-intro/04-custom-blockchains-vs-layer-2)

---
title: Avalanche L1s vs Layer 2
description: Comparing different blockchain scaling approaches.
updated: 2024-06-28
authors: [usmaneth]
icon: BookOpen
---

Layer 2 blockchain solutions, such as rollups, are another innovation in the blockchain landscape. Layer 2s aim to enhance the scalability and performance of the Ethereum network. Rollups essentially perform computations off-chain and submit the resultant state changes to the base layer, thereby reducing the computational load on the main Ethereum chain.

While both Avalanche Custom Blockchains and Layer 2 rollups strive to improve blockchain scalability and performance, they use different methods and each have their unique advantages and trade-offs. 

## Decentralization and Security

Avalanche Custom Blockchains are part of the base layer itself. Each blockchain in Avalanche maintains its security, hence a compromise in one blockchain doesn't necessarily impact the others. On the other hand, rollups delegate security to the Ethereum mainnet. As long as the mainnet remains secure, so does the Layer 2 solution, given the rollup performs properly. However, a security breach on the mainnet can potentially affect all Layer 2 solutions.

## Interoperability and Flexibility

Avalanche's multi-chain structure offers great interoperability and flexibility, as each custom blockchain network can define its own rules and validate multiple blockchains of different virtual machines. This means Avalanche can cater to a vast array of use cases. Conversely, Layer 2 solutions are primarily designed to augment the Ethereum mainnet and might not offer the same flexibility.

## Performance and Cost

Both approaches aim to offer higher transaction throughput and lower fees compared to traditional single-chain systems. Avalanche achieves this through parallel processing across its Avalanche L1s, while rollups offload computation off-chain. However, users of Layer 2 solutions might experience delays when transferring assets back to Layer 1. Furthermore, since Layer 2 systems need to checkpoint their activity to the L1, which effectively sets a price floor and couples the prices of the L1 gas token to the L2 gas token. In Avalanche, the gas tokens of an Avalanche L1 are completely independent from AVAX.

<Quiz quizId="402"/>

<Quiz quizId="108"/>



# Set Up Core Wallet (/academy/avalanche-fundamentals/03-multi-chain-architecture-intro/05-setup-core)

---
title: Set Up Core Wallet
description: Learn about how to setup your own Core Wallet.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

import { Step, Steps } from 'fumadocs-ui/components/steps';
import InstallCoreExtension from "@/content/common/core-wallet/install.mdx"
import CreateWallet from "@/content/common/core-wallet/create-wallet.mdx"
import TestnetMode from "@/content/common/core-wallet/testnet-mode.mdx"
import Faucet from "@/content/common/core-wallet/faucet.mdx"

To grasp the concept of the Avalanche L1s better we will interact with a chain. To do that, we will use Core. Core is an all-in-one command center built for multi-chain systems. It supports Avalanche, Bitcoin, Ethereum, and all EVM-compatible blockchains. Core has a browser extension, a web wallet, and a mobile app. It is optimized for multiple chains and makes navigating between them easy.

<Steps>
<Step>

### Install Core Extension

<InstallCoreExtension />

</Step>
<Step>

### Create a Wallet

<CreateWallet />

</Step>
<Step>

### Switch to Testnet

<TestnetMode />

</Step>
<Step>

### Get Testnet Tokens

<Faucet />

</Step>
</Steps>

## Managing MetaMask & Core Extensions

If had Metamask already installed, you could face some problems. We recommend temporarily disabling
Metamask for the time being.

Open the extensions page in browser. You can also type `chrome://extensions` in your address bar to open it.
Scroll through your list of installed extensions, or use the search bar at the top of the page, to
find the Metamask extension.

Once you find Metamask, you will see a toggle switch next to it. Click on this switch to disable the
extension. You can reenable it any time. When the switch is in the off position, Metamask is disabled, and you should be all set.

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/avalanche-fundamentals/14-7yGvfoSga3HSD9JF2bokKPBFd3OvdV.png)


# Use Dexalot L1 (/academy/avalanche-fundamentals/03-multi-chain-architecture-intro/06-use-dexalot)

---
title: Use Dexalot L1
description: Get first hand experience with an Avalanche L1.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

In this activity, we'll interact with our first Avalanche L1. The Dexalot Avalanche L1 aims to replicate the user experience of a centralized exchange (CEX) with greater decentralization and transparency. By using a Avalanche L1, Dexalot can offer cheaper transaction fees than other traditional decentralized exchanges while keeping the transparency that centralized exchanges lack.

<Steps>
<Step>

### Display the Dexalot Avalanche L1 in Core

Make sure your Core Wallet is set to Testnet mode, so we do not use real funds. Open your Core Wallet Browser Extension and click "Show all Networks." To display Dexalot to our home screen, click the star icon next to its name.

</Step>
<Step>

### Bridge Tokens to Dexalot

Head over to the [Dexalot Testnet](https://app.dexalot-test.com/trade), connect your wallet (top right), and click on the `Deposit` button next to the pink icon with your connexted wallet. You will have to authenticate your wallet for the first time you interact with Dexalot.

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/avalanche-fundamentals/Dexalot1.png)

Once you clicked the `Deposit` button, select to deposit into the Dexalot L1. Enter 1 AVAX and click Deposit. Confirm the transaction in your wallet.

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/avalanche-fundamentals/Dexalot2.png)

A few moments later, your balances should be updated and you should be able to see that on the `Dashboard` tab:

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/avalanche-fundamentals/Dexalot3.png)

</Step>
<Step>

### Swap Tokens on Dexalot L1

Now head to the `Trade` tab and sell 0.5 AVAX for USDC. You can select the trading pair AVAX/USDC on the top right. The website will prompt your wallet to switch networks to the Dexalot L1. Confirm the switch and then sign the transaction.

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/avalanche-fundamentals/Dexalot3.png)

Now, head back to the `Dashboard` tab and check how the balances updated.
![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/avalanche-fundamentals/Dexalot4.png)


</Step>
<Step>

### Withdraw to Fuji C-Chain

From the `Dashboard` tab, withdraw your AVAX and USDC back to the Fuji C-Chain by clicking on the "Withdraw" gray button on the left:

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/avalanche-fundamentals/Dexalot5.png)

Make sure the network is set to Fuji C-Chain and enter the amount you want to withdraw. Click on the Withdraw button and confirm the transaction in your wallet.
![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/avalanche-fundamentals/Dexalot6.png)

</Step>
</Steps>

## What just happened?

On the surface, it might feel like a regular decentralized swap. However, there is a substantial difference. We performed our operation not on the C-Chain, but bridged our tokens to a Avalanche L1, performed the operations there, and bridged our tokens back to the C-Chain.

The Avalanche L1 (Dexalot) we used was highly specialized for our use case and very cheap. We actually got all the gas token ALOT we needed airdropped, just for bridging assets over. The only fees we had to pay were for bridging. Usually, we would not have done this for a single operation, so these costs do not occur for a single trade, but only for depositing and withdrawing from the portfolio.


# Creating an L1 (/academy/avalanche-fundamentals/04-creating-an-l1/01-creating-an-l1)

---
title: Creating an L1
description: Learn how to create an L1 blockchain in the Avalanche network using the Builder Tooling.
updated: 2024-05-31
authors: [martineckardt]
icon: Book
---

Now that we've gone over what Avalanche L1s are and how Interoperability works, you are probably eager to test out the
functionality of Avalanche L1s by creating one yourself! In this section, you will learn how to
create an L1  blockchain using the the Avalanche Builder Tooling. 

For production deployments you can leverage a [Blockchain-as-a-Service
Provider](/integrations#Blockchain%20as%20a%20Service) to oursurce the setup and maintenance of the
L1 infrastructure.

## Video 

You can watch a video how an L1 is created:

<YouTube id="RyfmQyDN33M" />

## What You Will Learn

In this section, you will go through the following steps:

<Steps>
<Step>

### Claim Testnet AVAX Tokens 

In the first step we will show you how to set up the Core wallet chrome extension. After, we will
show how to claim some testnet AVAX tokens from the faucet. Finally, you will learn how to bridge
the tokens from the C-Chain to the P-Chain.

</Step>
<Step>

### Create the P-Chain records for the a Subnet and blockchain

Here we will show you how to create the P-Chain records for the Subnet and the blockchain. You will
issue a `CreateSubnetTx` transaction on the P-Chain to create a Subnet record. Then you will add a belockchain to
the Subnet by issuing a `CreateChainTx` transaction on the P-Chain.

</Step>
<Step>

### Set up a node to track the Subnet

In this step you will learn how to set up a node to track the Subnet. We will leverage Docker to set
up a node on a cloud server. When the node is up and running, you will connect your wallet to it.

</Step>
<Step>

### Convert to an L1

To finish the process, you will convert the Subnet to an L1. This is done by issuing a
`ConvertSubnetToL1Tx` transaction on the P-Chain. This will turn your node into an actual validator
for the L1. 

</Step>
<Step>

### Test the L1

In the final step, you will deploy a ERC-20 token on the L1 you had launched. 

</Step>
</Steps>

# Create Builder Account (/academy/avalanche-fundamentals/04-creating-an-l1/01a-create-builder-account)

---
title: Create Builder Account
description: Create a Builder Account for easier access.
updated: 2025-03-13
authors: [martineckardt]
icon: CircleUserRound
---

Before you start creating your first L1, we recommend you to create an Avalanche Builder Account. This will
allow you to easily access many features of Builder Hub. You can complete the course without a Builder Account, but it will be much more convenient to have one.

<Button asChild>
  <a target="_blank" href="/login">
    Create Avalanche Builder Account
  </a>
</Button>

### Benefits of a Builder Account

- **Faucet**: With a Builder Account, you can claim testnet AVAX on the C-Chain and P-Chain right
  from the Builder Console without the need of a coupon code or holding a mainnet balance.
- **Free Managed Testnet Infrastructure**: With a Builder Account, we will provide free managed
    testnet nodes and ICM relayers for your L1. This infrastructure is not suitable for production use, but it is great for testing and development.

# Install Core Wallet (/academy/avalanche-fundamentals/04-creating-an-l1/02-connect-core)

---
title: Install Core Wallet
description: Learn how to install the Core wallet browser extension and create a wallet.
updated: 2025-03-13
authors: [owenwahlgren]
icon: Wallet
---

In this section you will learn how to set up Core wallet and get some testnet AVAX on the P-Chain so
you can launch your first L1.

<Steps>
<Step>

### Download Core Wallet

If you don't have Core Wallet installed already, download the Core Extension for Chrome:

[Core Wallet Extension](https://chromewebstore.google.com/detail/core-crypto-wallet-nft-ex/agoakfejjabomempkjlepdflaleeobhb)

Core is the only wallet that supports issuing P-Chain transactions, so it is not possible to use
other wallets such as MetaMask or Rabby.

</Step>
<Step>

### Create a Wallet in Core

Create a new wallet in Core by clicking the `Continue with Google` or by manually creating a new Wallet.

</Step>
</Steps>

Congratulations! You have successfully set up your Core wallet.









# Claim Testnet Tokens (/academy/avalanche-fundamentals/04-creating-an-l1/02a-claim-testnet-tokens)

---
title: Claim Testnet Tokens
description: Learn how to connect Core wallet and claim testnet AVAX.
updated: 2025-03-13
authors: [owenwahlgren]
icon: Coins
---

Connect your Core wallet below to claim testnet AVAX on the C-Chain and P-Chain. With a Builder Hub account, **tokens are automatically sent to your wallet** - no manual claims or coupon codes needed!

<ToolboxMdxWrapper walletMode="c-chain">
    <Faucet />
</ToolboxMdxWrapper>

<Callout type="info">
**Automated Faucet:** Once you connect your wallet with a Builder Hub account, testnet tokens are automatically sent to your wallet when needed. You can also manually request tokens using the buttons above.
</Callout>

## Alternative Faucet

If you don't want to create a [Builder Hub Account](https://build.avax.network/login), you can use the external [Avalanche Faucet](https://core.app/tools/testnet-faucet/?subnet=c&token=c) with coupon code `avalanche-academy` or `avalanche-academy25` to get 2 AVAX on the C-Chain.

After you have claimed some AVAX on the C-Chain, you can bridge it to the P-Chain using this tool:

<ToolboxMdxWrapper walletMode="c-chain">
    <CrossChainTransfer />
</ToolboxMdxWrapper>

# Network Architecture (/academy/avalanche-fundamentals/04-creating-an-l1/03-network-architecture)

---
title: Network Architecture
description: Learn about the network architecture of Avalanche and the role of the P-Chain.
updated: 2025-03-13
authors: [owenwahlgren]
icon: BookOpen
---

To create an L1 you need to follow these steps:

1. Create a Subnet record on the P-Chain with the `CreateSubnet` transaction
2. Add one or more chains to the Subnet with the `CreateChain` transaction
3. Convert the Subnet to an L1 and add the initial validators with the `ConvertSubnetToL1` transaction

Let's dive into what that means:

## Validators in a Multi-Chain Network

Validators are nodes of a blockchain that secure the network by validating the transactions.
Each L1 in the Avalanche network has it's own set of validators that is running the `AvalancheGo` client.

<img src="https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/l1-validator-management/l1s-4usH2C4o3WLEqAkK9JLoDgGHezOWqn.png" alt="L1 Creation" />

## Platform Chain

The Platform Chain is the backbone for the native interoperability of the Avalanche network. It is a
registry of all validators in the Avalanche network. This includes the validators of the Primary
Network (including the C- and P-Chain), as well as all L1s and legacy Subnet validators. For each
validator the P-Chain stores the following information:

- A unique node ID identifying the validator
- A BLS Public Key
- The Stake Weight
- The Balance of the Validator for the continous interoperability fee

following graphic shows a simplified data model of the P-Chain:

<img src="/common-images/p-chain/data-model.png" alt="P-Chain Architecture" />

Builders can create new L1 blockchains in the Avalanche Network by issuing transactions on the
P-Chain. The P-Chain runs a special-purpose virtual machine called the
[platformvm](https://github.com/ava-labs/avalanchego/tree/master/vms/platformvm). It is not
EVM-based and therefore to interact with it you need a compatible wallet like Core wallet. Creating
new records for L1 blockchains on the P-Chain is done by issuing transactions like the `CreateSubnetTx`.

The P-Chain is secured by the Primary Network validators. L1 validators are syncing the P-Chain,
meaning they always have the latest view of the validator set of all blockchains in the Avalanche
network, but are not participating in the consensus of the P-Chain.

## Subnets

When the Avalanche network was created the architecture included the concepts of Subnets. Subnets
are blockchains that were validated by a *subset of the Primary Network validators*. Each Primary
Network validator can be a member of multiple subnets, and each Subnet can have multiple validators.
Since Primary network validators have to fullfil the Primary Network staking requirements of
`2,000 AVAX`, this was also necessary for every validator that was validating a Subnet. There was no
option to opt-out of validating the Primary Network.

<img src="https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/l1-validator-management/primary-network-3Xv3evd1fOAVXXEZ69mmrBI5AFt7AX.png" alt="Primary Network
Architecture" />

While the concept of Subnets is still supported in the Avalanche network, it is recommended to launch
new blockchains as L1s to take advantage of the benefits outlined earlier. Since the naming of Subnets
is deep enshrined in the Avalanche network, you will still see it sometimes in the code or the
transaction names.

<Quiz quizId="1204"/>

# Create a Blockchain (/academy/avalanche-fundamentals/04-creating-an-l1/05-create-blockchain)

---
title: Create a Blockchain
description: Learn how to configure a blockchain and create a record for it on the P-Chain by issuing a CreateChainTx transaction using the Builder Tooling.
updated: 2025-03-13
authors: [owenwahlgren]
icon: SquareMousePointer
---

Now that you have Core wallet set up and some AVAX on the P-Chain you can create a Subnet. You will
do this by issuing a `CreateSubnetTx` transaction. This will create a Subnet that is uniquely
identified by the transaction hash of the `CreateSubnetTx` transaction.

The `CreateSubnetTx` transaction only has a single parameter: The owner of the Subnet. The owner can
add blockchains to the Subnet and convert it to an L1. With the conversion to an L1 the owner will loose it's
privileges. Therefore, the owner is only relevant during the creation time and does not have to be
secured by a mulit-sig if a immediate conversion to an L1 is planned. We will just use your P-Chain
address as the owner.

Then you will issue the `CreateChainTx` on the P-Chain to create the blockchain record. The
`CreateChainTx` transaction as the following parameters:

- `name`: The name of the chain
- `subnetID`: The ID of the Subnet you want to add the chain to
- `vmID`: The ID of the Virtual Machine that will be used to run the chain.
- `genesisData`: The genesis configuration of the chain

The Genesis Builder tool allows us to configure many aspects of the blockchain like permissioning,
it's tokenonomics and the transaction fee mechanism. 

Feel free to browse through the different configuration options, but for now don't change any of the
defaults and just click the `View Genesis JSON` button.

Then click `Create Chain` This will create the P-Chain record for your blockchain and associate it
with the Subnet created in the previous step. 

The blockchain will be uniquely identified by the transaction hash of the `CreateChainTx` transaction.

<ToolboxMdxWrapper walletMode="c-chain">
    <CreateChain embedded={true} />
</ToolboxMdxWrapper>

Congratulations! You have successfully created a blockchain record on the P-Chain. The blockchain does not
have any validator nodes yet, so we can't connect our wallet to it or issue any transactions just
yet. You will learn how to do that in the next section.


# Set up Validator Nodes (/academy/avalanche-fundamentals/04-creating-an-l1/06-run-a-node)

---
title: Set up Validator Nodes
description: Learn how to deploy validator nodes for your L1 using managed infrastructure or self-hosted Docker deployments.
updated: 2025-03-19
authors: [owenwahlgren]
icon: Terminal
---

import AvalancheGoDocker from "@/components/toolbox/console/layer-1/AvalancheGoDockerL1";
import ToolboxMdxWrapper from "@/components/toolbox/academy/wrapper/ToolboxMdxWrapper.tsx";

Now that the P-Chain records are set up, you can start syncing the node with your Subnet.

## Run Your L1 Node

Use our free managed testnet infrastructure to instantly deploy a node for your L1, no need for Docker or Cloud Provider account set up with credits. Enjoy the benefits of:

- Instant deployment with one click
- Automatic configuration for your Subnet
- Free for testnet development
- Monitor and manage through the [Builder Console](/console/testnet-infra/nodes)

<ToolboxMdxWrapper walletMode="testnet-mainnet">
    <CreateManagedTestnetNode />
</ToolboxMdxWrapper>

<Callout type="warning">
Managed nodes automatically shut down after 3 days. For production or extended testing, see the self-hosted option below.
</Callout>

## Optional Alternative: Self-Hosted Infrastructure

The free managed testnet nodes are a great option for playing around with Avalanche L1s, but are not
intended for running on production environments. They are shut down automatically after 3 days. If you want to test out your production environment, running beyond 3 days, or anything more complex you should run nodes on your own infrastructure
using Docker:

<ToolboxMdxWrapper walletMode="testnet-mainnet">
    <AvalancheGoDocker />
</ToolboxMdxWrapper>



# Convert a Subnet to an L1 (/academy/avalanche-fundamentals/04-creating-an-l1/07-convert-subnet-l1)

---
title: Convert a Subnet to an L1
description: Learn how to convert a Subnet to an L1 on the P-Chain by issuing a ConvertSubnetToL1Tx transaction using the Builder Tooling.
updated: 2025-03-13
authors: [owenwahlgren]
icon: SquareMousePointer
---

The node you have just launched is tracking the Subnet but is not yet a validator. In fact, since the Subnet
does not have any validators yet it cannot process any transactions. In this step we will do two
things at once:

1. Convert the Subnet to an L1
2. Add your node as a validator

Converting a Subnet to an L1 requires the Subnet owner issuing a `ConvertSubnetToL1Tx` transaction
on the P-Chain. This transaction establishes a new validator set for your blockchain and transforms
it from a Subnet into a sovereign L1 chain. The `ConvertSubnetToL1Tx` transaction is a one-time
transaction that can only be executed once by the Subnet owner(s). 

After the conversion the subnet owner looses all privileges and the L1 is controlled by a validator
manager contract, that manages the validator set. You will learn more about this in the next
chapter. 

The `ConvertSubnetToL1Tx` has the following parameters:

- **Subnet ID** - The unique identifier of your Subnet
- **Validator Manager Blockchain ID** - The ID of the blockchain where the Validator Manager
  contract will be deployed. This blockchain can belong to the L1, be the C-Chain or belong to any
  other L1 in the Avalanche network
- **Validator Manager Address** - The address of the contract on that blockchain
- **Validators** - The initial set of validators for the L1

<Callout type="info">
The **Validator Manager Address** is initially set to an OpenZeppelin [TransparentUpgradeableProxy](https://docs.openzeppelin.com/contracts/4.x/api/proxy) contract pre-deployed in the `genesis.json`. After conversion, you'll deploy the actual `ValidatorManager` implementation contract and update the proxy to point to it.
</Callout>

## Conversion Tool

Use the following tool to convert your Subnet to an L1:

<ToolboxMdxWrapper walletMode="c-chain">
  <ConvertToL1 />
</ToolboxMdxWrapper>


# Test your L1 (/academy/avalanche-fundamentals/04-creating-an-l1/08-test-l1)

---
title: Test your L1
description: Test your freshly created L1 by deploying an ERC-20 using the Builder Tooling.
updated: 2025-03-13
authors: [martineckardt]
icon: SquareMousePointer
---

Congratulations! You have successfully created your own L1. Now, let's deploy an ERC-20 token on
your L1 and test it.

<ToolboxMdxWrapper walletMode="l1">
    <DeployExampleERC20 />
</ToolboxMdxWrapper>

You have just launched your own blockchain on Avalanche and already deployed your first token on it.

In this following chapters you will learn more on how you can tailor your L1 to your applications needs.


# Remove Node (/academy/avalanche-fundamentals/04-creating-an-l1/09-remove-node)

---
title: Remove Node
description: Learn how to stop and remove a node running on Docker.
updated: 2025-03-19
authors: [martineckardt]
icon: Terminal
---

Now that you have tested your L1, you can stop and remove the node. This is useful if you want to free up resources or if you want to start a new node with different parameters.

<Steps>
<Step>

### Stop Node

To stop the node, you can use the following command:

```bash
docker stop avago
```

The node credentials and the blockchain state is persisted in the `~/.avalanchego` directory. When
you restart the node with `docker start avago` it will pick up where it left off.

</Step>
<Step>

### Remove Node

```bash
docker rm avago
```

This will not remove the state and credentials of the node. To remove these you need to delete the `~/.avalanchego` directory.

</Step>
</Steps>

# Introduction (/academy/avalanche-fundamentals/05-interoperability/01-introduction)

---
title: Introduction
description: Learn about interoperability in the Avalanche ecosystem and its importance in multichain systems
updated: 2024-08-26
authors: [martineckardt, nicolasarnedo]
icon: Book
---

<YouTube id="eLHOElbSw1k" />

Now that we know about [Avalanche's Multichain Architecture](/academy/avalanche-fundamentals/03-multi-chain-architecture-intro/01-multi-chain-architecture) it is important we understand how we achieve **native interoperability** between all of these chains.

## What is Interoperability

Interoperability refers to the ability of different blockchain networks to communicate, share data, and interact with each other seamlessly. This capability allows assets, information, and functionalities to move between separate blockchain ecosystems without the need for intermediaries.

These interactions can take many forms, including:
- Asset Bridging (Tokens, NFTs, etc.)
- DAO Voting across Chains
- Cross-Chain Liquidity Pools
- Decentralized Data Feeds
- Cross-Chain Smart Contract Calls

## Why Interoperability Matters

Without interoperability, blockchains face significant challenges:

- **Lack of Liquidity**: New blockchains struggle to attract sufficient liquidity for tokens and financial instruments, limiting their viability and user adoption.

- **Limited Developer Adoption**: Developers are hesitant to build on new blockchains without access to existing tools, communities, and infrastructure from established networks.

- **Restricted User Access**: Users face barriers entering new blockchains due to lack of direct on-ramp services and limited asset availability.

## How Avalanche Achieves Interoperability

Avalanche enables native cross-chain communication through a layered approach:

### Avalanche Warp Messaging (AWM)
The foundational protocol that enables L1s to exchange authenticated messages. AWM leverages BLS multi-signatures where validators sign outgoing messages, and these signatures are aggregated for efficient verification on the destination chain.

### Interchain Messaging Contracts (ICM)
Smart contracts that provide a developer-friendly interface on top of AWM. They handle message encoding/decoding, relayer incentives, and cross-chain dApp communication patterns.

### Interchain Token Transfer (ICTT)
Built on Interchain Messaging contracts, ICTT enables asset transfers between L1s by locking tokens on the source chain and minting representations on the destination chain.

## What You'll Learn

In this section, we'll explore:

1. **Interoperability Fundamentals** - Understanding the core concepts and use cases
2. **Securing Cross-Chain Communication** - Cryptographic foundations including BLS signatures
3. **Avalanche's Interoperability Solutions** - Deep dive into AWM and ICTT protocols
4. **Practical Implementation** - How these technologies work together in real applications

Let's begin by understanding the fundamental concepts that make secure cross-chain communication possible. 

# Source, Message and Destination (/academy/avalanche-fundamentals/05-interoperability/02-source-message-destination)

---
title: Source, Message and Destination
description:  Learn about interoperability and it's importance in multichain systems.
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

Interoperability is achieved by enabling blockchains to pass messages to one another. Each message originates from a source chain and is sent to one or more destination chains. These messages encode arbitrary data that can attest some event on the source chains, such as the deposit of an asset or the result of a vote.

<div class="flex space-x-8">
    <div class="flex-1">
        ![](/common-images/teleporter/source.png)
        # Source
        - Origin of communication
        - Sender calls contract
    </div>
    <div class="flex-1">
        ![](/common-images/teleporter/message.png)
        # Message
        - Contains source, destination, and encoded data
        - Signature guarantees  authenticity
    </div>
    <div class="flex-1">
        ![](/common-images/teleporter/destination.png)
        # Destination
        - Submission of message as transaction
        - Verifies signatures
    </div>
</div>

## Source Chain

The source chain in a cross-blockchain communication system refers to the original blockchain where data, assets, or information originate before being communicated to another blockchain. It acts as the starting point for initiating cross-chain interactions. When a user intends to communicate with another blockchain, they utilize protocols or smart contracts to initiate the communication process from the source chain.

## Message

The message is the data structure that will be sent to to the destination chain. It contains some metadata, the encoded message, and a signature. The signature attests the authenticity of the message, meaning that whatever the message claims has actually happened on the source chain. 

## Destination Chain

Conversely, the destination chain is the recipient blockchain where the communicated data, assets, or instructions will be received and processed. Validators, nodes, or protocols associated with the cross-blockchain communication system on the destination chain receive and authenticate the information relayed from the source chain. Once validated, the destination chain processes the data or executes the specified instructions.

<Quiz quizId="301"/>


# ICM, ICM Contracts & ICTT (/academy/avalanche-fundamentals/05-interoperability/03-icm-icmContracts-and-ictt)

---
title: ICM, ICM Contracts & ICTT
description: Learn how Avalanche implements secure interoperability with ICM, ICM Contracts (Teleporter), and ICTT
updated: 2025-07-21
authors: [nicolasarnedo]
icon: BookOpen
---

We can look at Avalanche's Native Interoperability with a layered approach, each step guaranteeing that our message is securely sent across systems. 

In order to understand the fundamentals of cross-chain messaging, here are 5 concepts that we will be covering in this chapter that make it possible:

1. **Secure Signatures** - The foundation that ensures messages can be trusted
2. **ICM (Interchain Messaging)** - Native blockchain feature that enables cross-chain communication
3. **ICM Contracts** - Developer-friendly tools that make building cross-chain apps easier
4. **ICTT (Interchain Token Transfer)** - Ready-to-use solution for moving tokens between chains *(not always used)*
5. **Relayers** - service that helps deliver messages between chains by collecting signatures and submitting transactions

![Interchain Messaging Layers](/common-images/avalanche-fundamentals/InterchainMessagingLayers+Relayer.png)

Knowing the components is the first piece of the puzzle, grasping how they interact with each other is the next step. In the next image we can see 



## Interchain Messaging (ICM)

ICM is the foundation of cross-chain communication on Avalanche. It's built directly into every Avalanche blockchain, making it a native feature rather than an add-on.

### What ICM Does

Think of ICM as a built-in postal system for blockchains:
- **Creates Messages**: Smart contracts can create messages to send to other blockchains
- **Signs Messages**: Validators sign these messages to prove they're authentic
- **Verifies Messages**: Destination blockchains can verify that messages are genuine

### The Warp Precompile

At the heart of ICM is the "warp precompile" - a special smart contract that comes pre-installed on every Avalanche blockchain. Unlike regular smart contracts that developers deploy, this one is built into the blockchain software itself (and is written in go unlike most smart contracts that are in solidity).

### Simple Message Flow

![Interchain Messaging Flow](/common-images/avalanche-fundamentals/InterchainMessagingExampleFlow.png)

1. A smart contract creates a message using the warp precompile
2. The blockchain emits an event saying "I have a message to send"
3. Validators sign this message to prove it's legitimate
4. A relayer picks up the message and signatures
5. The relayer delivers everything to the destination blockchain
6. The destination blockchain verifies the signatures and accepts the message



## ICM Contracts (Teleporter)

While ICM provides the basic messaging capability, developers need an easier way to use it. That's where ICM Contracts come in - specifically a contract called "Teleporter".

### What Teleporter Does

Teleporter is like a user-friendly interface for ICM:
- **Simple Functions**: Instead of complex operations, developers just call `sendCrossChainMessage()`
- **Message Management**: Automatically handles encoding, tracking, and delivering messages
- **Fee Handling**: Manages payments to relayers for delivering messages
- **Security**: Prevents messages from being delivered twice or replayed

### Why Developers Use Teleporter

- It's deployed at the same address on every blockchain
- It handles all the complex parts of cross-chain messaging
- It provides a standard way for contracts to communicate across chains
- It makes building cross-chain applications much simpler

## Relayers

Relayers are the delivery service of the cross-chain messaging system. They're responsible for physically moving messages from one blockchain to another.

### What Relayers Do

1. **Monitor Blockchains**: Watch for new cross-chain messages
2. **Collect Signatures**: Gather validator signatures that prove a message is valid
3. **Submit Transactions**: Create and submit the transaction on the destination blockchain
4. **Pay Gas Fees**: Cover the transaction costs on the destination chain (and get reimbursed)

### Key Points About Relayers

- Anyone can run a relayer - it's permissionless
- Relayers need wallets with tokens on destination chains to pay for gas
- They can be configured to handle specific routes or all messages
- They're incentivized through fee mechanisms built into Teleporter

## ICTT: An Example Cross-Chain Application

ICTT (Interchain Token Transfer) is not a core component of cross-chain messaging - it's an application built on top of ICM, Teleporter, and relayers. Think of it as one of many possible cross-chain applications.

### What ICTT Does

ICTT is a pre-built solution specifically for moving tokens between blockchains:
- **Token Home**: Manages the original tokens on their native blockchain
- **Token Remote**: Creates wrapped versions of tokens on other blockchains
- **Transfer Logic**: Handles locking, minting, burning, and releasing tokens

### Why ICTT is Special

While anyone could build their own token bridge using ICM and Teleporter, ICTT provides:
- A tested, secure implementation
- Standard contracts that work the same way everywhere
- Support for both native tokens and ERC-20 tokens
- Advanced features like "send and call" for composability

Think of ICTT like a pre-built e-commerce platform - you could build your own, but using the existing solution saves time and reduces risk.

## Summary

Avalanche's cross-chain messaging system works like a well-coordinated postal service:

**The Core Components:**
- **ICM**: The built-in messaging system in every blockchain
- **ICM Contracts (Teleporter)**: The easy-to-use interface for developers
- **Relayers**: The delivery service that moves messages between chains

**Why It Works So Well:**
- **Trust**: Messages are secured by the same validators that run the blockchains
- **Simplicity**: Developers can send messages with just a function call
- **Flexibility**: Anyone can build cross-chain applications (like ICTT for tokens)
- **Speed**: Messages are delivered in seconds, not minutes or hours

This design means developers can focus on building their applications instead of worrying about the complex infrastructure of cross-chain communication.

## What Powers This System?

Now that we understand how messages travel from one blockchain to another, you might wonder: what makes this system secure? How do we know a message really came from the source blockchain and hasn't been tampered with?

The answer lies in cryptographic signatures - the digital equivalent of a tamper-proof seal. In the next sections, we'll explore:
- How validators create these digital signatures
- Why multiple signatures make the system secure
- How signatures can be efficiently combined and verified

Understanding these concepts will complete your knowledge of how Avalanche achieves secure, native interoperability.

For hands-on practice with cross-chain messaging, check out the [Academy Interchain Messaging](/academy/interchain-messaging) course.

<Quiz quizId="405"/> 

# Signature Schemes (/academy/avalanche-fundamentals/05-interoperability/04-signature-schemes)

---
title: Signature Schemes
description: Learn how Signature Schemes work and enable secure cross-chain communication
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

import SignatureSchemes from "@/content/common/cryptography/signature-schemes.mdx"
import defaultMdxComponents from "fumadocs-ui/mdx";

<SignatureSchemes components={defaultMdxComponents}/>

<Quiz quizId="309"/> 

# Use a Signature Scheme (/academy/avalanche-fundamentals/05-interoperability/05-signature-demo)

---
title: Use a Signature Scheme
description: Hands-on demonstration of BLS signature schemes
updated: 2024-05-31
authors: [martineckardt]
icon: Terminal
---

import SignatureSchemesDemo from "@/content/common/cryptography/signature-schemes-demo.mdx"

<SignatureSchemesDemo /> 

# Multi-Signature Schemes (/academy/avalanche-fundamentals/05-interoperability/06-multi-signatures)

---
title: Multi-Signature Schemes
description: Learn how multiple signatures provide Byzantine fault tolerance
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

import MultiSignatureSchemes from "@/content/common/cryptography/multi-signature-schemes.mdx"

<MultiSignatureSchemes />

<Quiz quizId="310"/> 

# Use Multi-Signature Schemes (/academy/avalanche-fundamentals/05-interoperability/07-multi-signature-demo)

---
title: Use Multi-Signature Schemes
description: Hands-on demonstration of multi-signature schemes with BLS
updated: 2024-05-31
authors: [martineckardt]
icon: Terminal
---

import SignatureSchemesDemo from "@/content/common/cryptography/multi-signature-schemes-demo.mdx"

<SignatureSchemesDemo /> 

# BLS Signature Aggregation (/academy/avalanche-fundamentals/05-interoperability/08-signature-aggregation)

---
title: BLS Signature Aggregation
description: Learn how signature aggregation enables efficient multi-party verification
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

import SignatureKeyAggregation from "@/content/common/cryptography/signature-key-aggregation.mdx"
import defaultMdxComponents from "fumadocs-ui/mdx";

<SignatureKeyAggregation components={defaultMdxComponents}/> 

<Quiz quizId="1203"/>

# Use Cases (/academy/avalanche-fundamentals/05-interoperability/09-use-cases)

---
title: Use Cases
description: Learn about the practical applications of interoperability on Avalanche
updated: 2024-08-26
authors: [owenwahlgren]
icon: BookOpen
---

Interoperability enables various use cases that enhance user experience and expand the Avalanche ecosystem's capabilities. Let's explore the key applications:

## 1. Cross-Chain Token Transfers

Tokens can be seamlessly transferred across different L1 blockchains without centralized exchanges:

- **Seamless Transfers**: Move tokens (like USDC) between chains with minimal fees and fast transaction times
- **Liquidity Access**: Leverage liquidity from various networks for DeFi activities, trading, or payments
- **Decentralization**: Maintain control over assets during transfers without third-party intermediaries

## 2. Decentralized Data Feeds

Smart contracts can access reliable price feeds and other data from specialized oracle chains:

- **Chainlink Integration**: Utilize real-time price data to power DeFi applications
- **Trustless Access**: Obtain data directly from decentralized oracles
- **Cross-Chain Applications**: Build financial applications that rely on consistent data across networks

## 3. Cross-Chain Token Swaps

Direct token swaps between different blockchain networks without centralized exchanges:

- **Decentralized Exchange**: Swap assets in a trustless environment
- **Multi-Chain Access**: Access tokens from various ecosystems 
- **Lower Costs**: Avoid high fees of centralized platforms

## 4. Cross-Chain NFTs

NFTs can be transferred and utilized across different blockchain networks:

- **Broad Exposure**: NFTs can be showcased and traded across multiple chains
- **Enhanced Utility**: Use NFTs in gaming, art, and virtual worlds across platforms
- **Ownership Preservation**: Maintain authenticity and provenance across chains

## 5. Interoperable DeFi Protocols

DeFi protocols can interact across chains for enhanced functionality:

- **Cross-Chain Yield Farming**: Maximize returns across multiple chains
- **Cross-Chain Collateralization**: Use assets from any chain as collateral
- **Composability**: Build innovative financial products leveraging multiple networks

## 6. Cross-Chain Governance

Decentralized governance that spans multiple blockchains:

- **Unified Governance**: Govern multi-chain protocols from a single platform
- **Decentralized Voting**: Enable participation from token holders on different chains
- **Enhanced Participation**: More diverse and representative decision-making

## Real-World Example: Gaming

<YouTube id="Ef90eCRY5z0" />

Consider a gaming ecosystem where:
- Game assets (NFTs) are minted on one L1 optimized for low fees
- The game logic runs on another L1 optimized for high throughput
- Rewards are distributed on a third L1 with established DeFi infrastructure

Interoperability makes this seamless for users who can play, trade, and earn across all chains without friction.

<Quiz quizId="404"/> 

# Independent Tokenomics (/academy/avalanche-fundamentals/07-independent-tokenomics/01-independent-tokenomics)

---
title: Independent Tokenomics
description: Quickly recap our past learnings about Avalanche Custom Blockchains.
updated: 2024-06-28
authors: [usmaneth]
icon: Book
---

Avalanche Custom Blockchains offer multiple ways to implement independent tokenomics. This gives developers more control and can enable new business models that would not be economically feasible on single-chain systems.

The customizations include:

- **Native Token:** Every Avalanche L1 has its own native token used for paying transaction fees. 
- **Transaction Fees:** We can configure how the transaction fees should be calculated.   
- **Initial Native Token Allocation:** We can specify how the inital token supply is distributed.
- **Native Token Minting Rights:** We can specify if and who can mint more native tokens.
- **Staking Token:** If our Avalanche L1 allows public and permissionless validation, we can define our logic how a node can become a validator.

You will learn about all these topics and get hands-on experience how you can configure the tokenomics of your own custom blockchain.


# Staking Token (/academy/avalanche-fundamentals/07-independent-tokenomics/11-staking-token)

---
title: Staking Token
description: Learn about staking tokens in blockchain networks.
updated: 2024-06-28
authors: [usmaneth]
icon: BookOpen
---

In many networks, such as Ethereum, the same token is used for staking and paying for gas. In the Avalanche network staking tokens and gas tokens can be separated, since they fullfil different purposes within the blockchain ecosystem.

Staking tokens are used for securing public permissionless Avalanche L1s through a proof-of-stake (PoS) consensus mechanism. Holders of staking tokens can run validators and participate in the consensus process by staking a certain amount of tokens as collateral.

Validators propose and validate new blocks of your L1 blockchain. Staking tokens play a crucial role in maintaining network security and incentivizing their participation.

Not all Avalanche L1s are public and permissionless. Many enterprises choose a Proof-of-Authority
setup, where the validators are selected by the enterprise. These blockchains do not have a staking
token.

You will learn about setting up Proof-of-Stake in the L1 Validator Management course.

# Introduction to VM Customization (/academy/avalanche-fundamentals/07b-vm-customization/00-vm-customization)

---
title: Introduction to VM Customization
description: Learn about customizing Virtual Machines.
updated: 2024-05-31
authors: [ashucoder9]
icon: Book
---

<YouTube id="gilx8K32_eI" />

For some use cases, it may be necessary to use a customized VM too. This is the case if an application cannot be built on a regular EVM on the C-Chain, or if it would result in gas costs too high to be economical for its users or creators.

Depending on a builder's needs, Avalanche allows for different VM customizations:

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/avalanche-fundamentals/32-BJ1Orj9c9p0VxpSTUJlWH1jPvo8nlD.png)

Customizing the EVM on the Ethereum network is difficult, requiring a wide consensus that the proposed change is mutually beneficial for all network participants. This can make customizations for unique use cases challenging, if not impossible. Additionally, Ethereum doesn't give users the option to add different chains. 

In Avalanche, every Avalanche L1 has autonomy over their Virtual Machines. Their creators can customize VMs to fit their unique requirements. This is one of the biggest advantages of multi-chain systems. 

In this section, we will see the three way to customize Virtual Machines at a high level. In later courses, we will dive deeper and learn how to actually customize each. 

<Quiz quizId="115"/>

# VM Configuration (/academy/avalanche-fundamentals/07b-vm-customization/01-configuration)

---
title: VM Configuration
description: Learn about customizing Virtual Machines.
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

When building a VM, it is possible to define certain parameters that can change the behavior of the VM. In our soda dispenser analogy these may be the products and prices offered by the dispenser. We might want to have two dispenser blockchains that offer different products and prices. If the VM is built in a way that it has parameters for the products and prices, it can be easily reused for different use items.

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/avalanche-fundamentals/33-AibP9P6YHVSun8IyXBAkKAJMeXVLqp.png)

This is a massive advantage over one-chain-fits-all systems, where the parameters have to be a compromise between all network participants. In Avalanche it is possible to have different blockchain with the same VM, but different parameters. 

Using VM Configuration we can easily create EVM-chains for different use cases such as trading a cheap gaming NFT or valuable Real estate on chain. These blockchains may differ in fees (low fees for cheap NFTs, high fees for valuable goods) and security levels (low security for cheap NFTs, high security for valuable goods). 

<Quiz quizId="116"/>

Examples of the configurable parameters of the subnetEVM include:

**trxAllowList:** Define a whitelist of accounts that restrict which account's transactions are accepted by the VM.

**contractDeployerAllowlist:** Defined a whitelist of accounts that restricts which account can deploy contracts on the blockchain

Using these parameters we can adapt the VM to our requirements without writing a single line of code. This is by far the easiest, but also least flexible way to customize a VM to one's requirements.

```json
{
  "config": {
    "chainId": 99999,
    "homesteadBlock": 0,
    "eip150Block": 0,
    "eip150Hash": "0x2086799aeebeae135c246c65021c82b4e15a2c451340993aacfd2751886514f0",
    "eip155Block": 0,
    "eip158Block": 0,
    "byzantiumBlock": 0,
    "constantinopleBlock": 0,
    "petersburgBlock": 0,
    "istanbulBlock": 0,
    "muirGlacierBlock": 0,
    "subnetEVMTimestamp": 0,
    "feeConfig": {
      "gasLimit": 20000000,
      "minBaseFee": 1000000000,
      "targetGas": 100000000,
      "baseFeeChangeDenominator": 48,
      "minBlockGasCost": 0,
      "maxBlockGasCost": 10000000,
      "targetBlockRate": 2,
      "blockGasCostStep": 500000
    },
    "contractDeployerAllowListConfig": {
      "blockTimestamp": 0,
      "adminAddresses": [
        "0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC"
      ]
    }
  },
  "alloc": {
    "8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC": {
      "balance": "0x52B7D2DCC80CD2E4000000"
    },
    "0x0Fa8EA536Be85F32724D57A37758761B86416123": {
      "balance": "0x52B7D2DCC80CD2E4000000"
    }
  },
  "nonce": "0x0",
  "timestamp": "0x0",
  "extraData": "0x00",
  "gasLimit": "0x1312D00",
  "difficulty": "0x0",
  "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
  "coinbase": "0x0000000000000000000000000000000000000000",
  "number": "0x0",
  "gasUsed": "0x0",
  "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000"
}
```

You can find more examples of Genesis files [here](https://github.com/ava-labs/subnet-evm/tree/master/tests/precompile/genesis).


# VM Modification (/academy/avalanche-fundamentals/07b-vm-customization/02-modification)

---
title: VM Modification
description: Learn about modifying Virtual Machines.
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

The next more powerful way to customize a VM is VM Modification. To meet our requirements, we can modify and extend our existing VM. In our soda dispenser analogy, we might want to customize our soda dispenser to accept card payments. Our current soda dispenser machine simply does not have this feature. Instead of reinventing the wheel and building a new dispenser with the new feature from the ground up, we simply extend the existing VM using a plugin.

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/avalanche-fundamentals/34-C4A2siQ7sVC3E0NAYfJ60Kr6AJDVQA.png)

In Avalanche, creating modified VMs is straightforward. The subnetEVM for instance can be customized through the development of plugins as well as precompiles.

<Quiz quizId="117"/>

# VM Creation (/academy/avalanche-fundamentals/07b-vm-customization/03-creation)

---
title: VM Creation
description: Learn about creating Virtual Machines.
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

For some use cases it might be necessary to create entirely new VMs. 

In our analogy this would be the case if we require completely different features, let's say we want to build a car VM. There is simply no way we can configure or extend a soda dispenser to turn it into a car. Instead we have to build a new VM from ground up. These newly created VMs can cater to much more specialized use cases and therefore this enables completely new blockchain applications not possible before. 

VM Creation is by far the most complex way, but also the most powerful way to customize a VM. It requires a deep understanding of the blockchain space and software development skill. There might be certain basic elements in most VMs, such as the notion of transaction, accounts and authentication. Therefore, Avalanche provides some SDKs, such as the HyperSDK, to make the creation of VMs in languages like Go and Rust easier. 

When creating a VM, there are two very distinct design patterns, that greatly vary in their intended use case.

## Special Purpose VMs

Special Purpose VMs are highly optimized for a specific use case. They only allow a very limited set of operations closely knit to its use case. A popular example for this would be the VM of the Bitcoin blockchain. The operations are much more limited than the ones of the Ethereum Virtual Machines, hence it only allows transactions related to the transfer of BTC.

## General Purpose

General Purpose VMs introduce another layer - commonly know as Smart Contracts or Programs - that can be submitted to the VM and enable user of the chain to interact with these. This way it allows its users to introduce their own logic to the VM. The most common General Purpose VM is the Ethereum Virtual Machine (EVM). However, some Avalanche L1s creators might want to create a VM that utilizes another language, such as Move, instead of Solidity as its smart contract language.

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/avalanche-fundamentals/35-ZGXXBzP8NzWvLQm5y1giGjRTfATKwO.png)

One of the EVM's key features is its capability to execution of smart contracts in a deterministic and trustless manner, ensuring that the outcome of their execution is predictable and verifiable by all network participants. Developers can create decentralized applications and deploy them on the Ethereum blockchain. 

This enables a wide range of use cases including decentralized finance (DeFi), tokenization, supply chain management, and more. The EVM's flexibility, security, and compatibility have made it a fundamental component of the Ethereum ecosystem, powering a vibrant and rapidly evolving ecosystem of decentralized applications and services.


# Permissioning (/academy/avalanche-fundamentals/08-permissioning-users/01-permissioning)

---
title: Permissioning
description: Learn about different ways of permissioning your Avalanche L1 blockchain.
updated: 2024-06-28
authors: [usmaneth]
icon: Book
---

Permissioning your Avalanche L1 is an optional feature of having your own L1 blockchain. There may be many reasons why a blockchain creator may want to permission their network including these:

- **Privacy and Confidentiality:** In industries where data privacy is crucial, such as finance or healthcare, permissioned blockchains allow only authorized parties to access sensitive information. This ensures that confidential data remains protected from unauthorized access.
- **Regulatory Compliance:** Many industries are subject to strict regulatory requirements regarding data handling and security. Permissioned blockchains enable organizations to implement necessary controls to ensure compliance with regulatory standards without compromising the integrity of the blockchain.
- **Cost-efficiency:** Restricting the usage of a blockchain to certain use cases may make it more cost efficient. Blockchain operators may be able to avoid transaction fee spikes caused events such as NFT drops by imposing restrictions.

These permissions don't necessarily have to be administered by a centralized entity. There could also be a DAO in charge of determining who should be allowed to use the blockchain. 

In the upcoming lessons, you will learn about the different levels of Permissions and how they can be configured for your Avalanche L1.

<Quiz quizId="406"/>

# Compliance (/academy/avalanche-fundamentals/08-permissioning-users/02-compliance)

---
title: Compliance
description: Learn how you can configure compliance for your Avalanche L1.
updated: 2024-06-28
authors: [usmaneth]
icon: BookOpen
---

For institutions, reputational damage and legal complications could arise if their blockchain systems were inadvertently used for criminal activities.

Regulatory bodies might impose penalties on such institutions if they were to fail to create sufficient controls to prevent these activities.

Most institutions have nuanced compliance requirements. Therefore, many institutions need flexible blockchains that can meet these needs. 

## Interacting with Criminal Actors

In permissionless systems, the counterparty on a trade is unknown. If a user performs a swap on a decentralized exchange on a permissionless blockchain, such as Ethereum or the Avalanche C-Chain, the origin of funds that are received are mostly unknown. 

To solve this problem, each Avalanche L1 can restrict who can interact with the blockchain. Only a whitelist of accounts can issue transactions. One could build a blockchain where only accounts that went through a KYC process are permitted.

## Interacting with Illegal Services

An additional risk to consider is that businesses may operate within an environment prone to illicit activities, or they may inadvertently become involved in such actions. In a permissionless system, any individual has the capability to deploy any contract, regardless of its compliance with the legal framework.

Avalanche L1s can limit who deploys smart contracts on the blockchain. Consequently, those involved in the creation of contracts can be held accountable. This level of control reassures institutions, ensuring that all protocols they engage with are fully compliant with existing laws. 

Beyond compliance advantages, this approach helps to maintain a blockchain free from an excess of smart contracts that could otherwise congest the system.

<Quiz quizId="407"/>

# Transaction Allowlist (/academy/avalanche-fundamentals/08-permissioning-users/04-tx-allowlist)

---
title: Transaction Allowlist
description: Learn how to restrict transactions to a specific set of addresses.
updated: 2024-06-28
authors: [usmaneth]
icon: BookOpen
---

import TxAllowList from "@/content/common/evm-precompiles/transaction-allowlist.mdx";

<TxAllowList />

# Activate Transaction Allowlist (/academy/avalanche-fundamentals/08-permissioning-users/05-activate-tx-allowlist)

---
title: Activate Transaction Allowlist
description: Learn how to activate the the transaction allowlist precompile in the genesis.
updated: 2024-06-28
authors: [martineckardt]
icon: Terminal
---

Avalanche L1s do not implement permissioning by default. To enable permissioning, you need to
activate the transaction allowlist precompile in the genesis. This allows only approved addresses to
issue transactions on your blockchain. 

<GenesisBuilder embedded={true} initiallyExpandedSections={['permissions']} />

# Contract Deployer Allowlist (/academy/avalanche-fundamentals/08-permissioning-users/06-contract-deployer-allowlist)

---
title: Contract Deployer Allowlist
description: Learn how to restrict contract deployment to a specific set of addresses.
updated: 2024-06-28
authors: [martineckardt]
icon: BookOpen
---

import ContractDeployerAllowlist from "@/content/common/evm-precompiles/contract-deployer-allowlist.mdx";

<ContractDeployerAllowlist />

# Activate Contract Deployer Allowlist (/academy/avalanche-fundamentals/08-permissioning-users/07-activate-contract-deployer-allowlist)

---
title: Activate Contract Deployer Allowlist
description: Learn how to activate the contract deployer allowlist precompile in the genesis.
updated: 2024-06-28
authors: [martineckardt]
icon: Terminal
---

Analogous to the transaction allowlist, Avalanche L1s do not implement contract deployer allowlist by default. To enable permissioning, you need to activate the contract deployer allowlist precompile in the genesis. This allows only approved addresses to deploy contracts on your blockchain.

<GenesisBuilder embedded={true} initiallyExpandedSections={['permissions']} />

# Permissioning Validators (/academy/avalanche-fundamentals/09-permissioning-validators/01-permissioning-validators)

---
title: Permissioning Validators
description: Learn about different ways of permissioning your Avalanche L1 blockchain.
updated: 2024-06-28
authors: [usmaneth]
icon: Book
---

The ability to control a blockchain's validator set has many benefits that can significantly enhance the efficiency, security, and governance of the network. It allows blockchain participants to have greater influence over the consensus process and decision-making, leading to a more robust and adaptable ecosystem. There are two ways to structure the validator set:

- **Permissionless Validation:** Anyone can participate in the validation process and be rewarded in tokens to cover their costs for the hardware and running the validator. In Avalanche, we call Avalanche L1s that take this approach Elastic Avalanche L1s.
- **Permissioned Validation:** Only whitelisted validators can validate the Avalanche L1. A permissioned Avalanche L1 can be turned into a Elastic Avalanche L1 at any time, but not the other way round.

There are many reasons why the creators might want a permissioned validator set for their Avalanche
L1. You will learn in detail about the technical options in the L1 Validator Management course.

## Enterprises and Corporations: 

Large enterprises and corporations often require blockchain solutions for their internal operations or specific industry use cases. A permissioned validator set allows them to control who can participate in the network and validate transactions. This is particularly relevant in industries with strict regulatory requirements, where entities need to ensure compliance and data privacy.

## Consortiums and Industry Associations: 

Consortiums or industry associations comprising multiple organizations with shared interests can benefit from a permissioned validator set. These entities often collaborate on initiatives requiring a distributed ledger, such as supply chain management, healthcare data sharing, or financial transactions. By establishing a permissioned validator set, the consortium can ensure that trusted participants from within the consortium validate the transactions.

## Government Agencies: 

Government entities may find value in launching a blockchain with a permissioned validator set to manage critical infrastructure, public services, or regulatory processes. They can select validators from trusted institutions or stakeholders to maintain control over the network while ensuring compliance with legal and governance requirements. Examples include land registry systems, voting platforms, or identity management solutions.

## Financial Institutions: 

Banks, payment processors, and other financial institutions could be interested in a permissioned validator set for blockchain solutions related to payments, remittances, or settlement systems. These institutions often require a level of control over the network to maintain regulatory compliance, prevent money laundering, and ensure adherence to Anti-Money Laundering (AML) regulations.

<Quiz quizId="408"/>

# Private Blockchains (/academy/avalanche-fundamentals/09-permissioning-validators/02-private-blockchains)

---
title: Private Blockchains
description: Learn about different ways of permissioning your Avalanche L1 blockchain.
updated: 2024-06-28
authors: [usmaneth]
icon: BookOpen
---

On a public blockchain, every transaction and change to the blockchain's state is visible to all. Anyone with internet access can see the transaction data. Block Explorers are one way to conveniently access the data on a chain. Although the identities of participants are often pseudonymous, the transaction data itself is open for anyone to see.

However, there are many instances, especially in business or enterprise settings, where such transparency isn't desirable. A company might be conducting a high-value transaction that it doesn't want competitors or others in the market to see. There might also be legal or regulatory reasons for needing to keep transaction data private.

In a private, permissioned blockchain, the visibility of transactions is limited to a select group of individuals or entities. This way, sensitive data isn't exposed. Only those who have been granted the necessary permissions can view the transaction data, and these permissions can be tightly controlled and monitored by network administrators.

Further, transactions in a private blockchain can be encrypted, adding an extra layer of security. Even within the network, details about specific transactions can be hidden from certain participants, based on their level of permission. This allows for a much higher degree of confidentiality, as specific data can be revealed only on a need-to-know basis.

In summary, privacy in the context of private, permissioned blockchains isn't just about restricting who can join. It's about having granular control over who can see what data, and when. It's about providing a secure, confidential environment where sensitive transactions can occur without the risk of exposure to unintended parties.

This has made private, permissioned blockchains an attractive option for businesses and organizations dealing with sensitive data, high-value transactions, or strict confidentiality requirements.

## Private Blockchains

The data of Avalanche L1s, by default, are publicly available. This means that every node can sync and listen to ongoing transactions/blocks in these blockchains, even if they're not validating the network. Nodes may do this for indexing purposes or just having access to the current state of the blockchain without relying on third-parties.

Avalanche L1 validators can choose not to publish data from their blockchains. If a node sets `validatorOnly` to true, the node exchanges messages only with the blockchain's validators. Other peers won't be able to learn contents of this blockchain from their nodes.

<Quiz quizId="409"/>

# Intain Markets Case Study (/academy/avalanche-fundamentals/09-permissioning-validators/03-case-study-intain-markets)

---
title: Intain Markets Case Study 
description: Learn about Intain's permissioned Avalanche L1.
updated: 2024-06-28
authors: [usmaneth]
icon: Microscope
---

Intain operates a structured finance platform. It has **IntainMARKETS**, a marketplace for tokenized asset-backed securities built as an Avalanche L1.

The digital marketplace automates and integrates functions of key stakeholders in structured finance, including issuer, verification agent, underwriter, rating agency, servicer, trustee, and investor.

Rather than replacing trust intermediaries, it integrates them onto a single platform  to enable digital issuance and investment with a complete on-chain workflow. All parties work together in a transparent but private environment.

<YouTube id="gNhmxIYj9ME" />

## Permissioned Validators and Tokenomics

The **IntainMARKETS L1** also uses other ways to adhere to regulatory requirements. It has U.S-hosted infrastructure, which allows data to reside domestically, while validators chosen by network participants must also be verified U.S. entities and individuals. The Avalanche L1 economics are not dependent on any public token, and transaction costs are independent from those of the Avalanche C-Chain and other Avalanche L1s.

Further Readings: [Intain Launch Announcement](https://medium.com/avalancheavax/intain-launches-avalanche-subnet-to-usher-in-new-era-for-multi-trillion-dollar-securitized-877c7cc1031f)

# What is a Blockchain? (/academy/blockchain-fundamentals/02-what-is-a-blockchain/01-what-is-a-blockchain)

---
title: What is a Blockchain?
description: Understand the high-level structure of this chapter.
updated: 2024-09-01
authors: [martineckardt]
icon: Book
---

Blockchains introduce a lot of new concepts. In this chapter we will approach the concept from a high level and see how it compares with other kinds of computers we are used to:

- **Decentralized Computer:** How is a blockchain different from computers we know?
- **Decentralized Applications:** What are dApps? 
- **Use Cases:** When does it make sense to use Blockchain?


# Decentralized Computer (/academy/blockchain-fundamentals/02-what-is-a-blockchain/02-decentralized-computer)

---
title: Decentralized Computer
description: Explore how different types of computers, including smartphones, PCs, web servers, and blockchains, serve specific functions based on their unique characteristics. Understand the benefits and trade-offs of blockchain as a decentralized computer, ideal for secure transactions but less efficient and more complex than traditional centralized systems.
updated: 2024-09-01
authors: [martineckardt]
icon: BookOpen
---

We interact with various types of computers every day, each designed to serve specific functions based on its unique characteristics. Smartphones, for example, are portable and convenient, offering powerful computing capabilities in a compact form. They are ideal for tasks that require mobility, such as communication, navigation, and media consumption. However, their small screen size and limited processing power compared to larger computers make them less suitable for tasks that require intensive computing power or extensive multitasking. PCs, on the other hand, provide more robust processing power and versatility. They are well-suited for tasks like video editing, gaming, or software development, where performance and the ability to use larger screens and peripherals like a mouse and keyboard are crucial. Yet, they lack the portability of smartphones and often require more space and power to operate.

![](/common-images/blockchain-basics/decentralized-computer/different-kinds-of-computer.png)

Web servers represent another type of computer, designed to handle large volumes of data and manage multiple simultaneous requests from users across the internet. They are optimized for reliability, speed, and the ability to run continuously without interruption, making them crucial for hosting websites, online services, and cloud computing platforms. While web servers excel at handling complex backend processes and large-scale operations, they are not intended for direct user interaction or tasks requiring a graphical user interface, which is where PCs and smartphones come in. Each type of computer has its strengths and weaknesses, and they often work together within the broader digital ecosystem, each performing tasks that suit their design and capabilities best.

The internet, as we know it today, is built on a centralized architecture, where data and services are controlled and maintained by a few large entities like data centers and internet service providers. However, the advent of blockchain technologies has opened up new possibilities for a more decentralized internet, often referred to as Web 3.0 or the decentralized web.

## Blockchains are Decentralized Computers

Blockchain can be thought of as a new kind of computer. The key advantage of this new kind of computer is decentralization, meaning that no single entity has control over the entire system. Instead, control is distributed across many participants, which enhances security and transparency, as all transactions are verified by consensus and recorded on an immutable ledger. 

![](/common-images/blockchain-basics/decentralized-computer/blockchain-computer.png)

However, this decentralization comes with trade-offs. Blockchains are inherently less efficient than traditional centralized systems. The complexity of managing and maintaining a decentralized network, along with slower transaction speeds, can be significant downsides compared to more traditional, centralized computing models. 

This makes blockchain ideal for certain use cases, like secure financial transactions or decentralized applications, but less suitable for tasks requiring high speed and efficiency.


# Decentralized Applications (/academy/blockchain-fundamentals/02-what-is-a-blockchain/03-decentralized-applications)

---
title: Decentralized Applications
description: TBD
updated: 2024-09-01
authors: [martineckardt]
icon: BookOpen
---

Programs and apps are software applications designed to run on different types of computers, such as smartphones, PCs, and web servers. On smartphones, apps are typically designed for specific tasks like messaging, gaming, or social media, optimized for touch interfaces and mobile connectivity. PCs run more complex programs, such as word processors, video editors, or development tools, which take advantage of larger screens, more powerful hardware, and the ability to handle multitasking. Web servers, on the other hand, run server-side applications that power websites, process data, and handle multiple user requests simultaneously. These programs often provide the backend services that apps on smartphones and PCs rely on to function.

![](/common-images/blockchain-basics/decentralized-computer/decentralized-applications.png)

Similarly, smart contracts or decentralized applications (dApps) are programs that run on a blockchain. A smart contract is a self-executing program with the terms of the agreement directly written into code, operating without the need for a trusted central authority. dApps are more complex, often consisting of multiple smart contracts that together offer a full application experience on the blockchain. Like traditional apps, these blockchain-based programs can perform a wide range of tasks, from managing digital assets to running decentralized finance (DeFi) protocols.

![](/common-images/blockchain-basics/decentralized-computer/decentralized-applications-connected.png)

Different types of applications can interoperate across these platforms, enabling a seamless user experience. For instance, a mobile app can interact with a backend running on a web server to fetch or update data. Similarly, the same app could also interact with a smart contract on a blockchain to verify transactions or access decentralized services. This interoperability allows users to benefit from the strengths of each platform, combining the user-friendliness of mobile apps, the processing power of web servers, and the security and transparency of blockchain technology.

# Use Cases (/academy/blockchain-fundamentals/02-what-is-a-blockchain/04-use-cases)

---
title: Use Cases
description: Explore the unique advantages and challenges of blockchain technology in finance, supply chain management, and voting systems. Learn how blockchain enhances security, transparency, and decentralization, while also considering its limitations in efficiency and complexity.
updated: 2024-09-01
authors: [martineckardt]
icon: BookOpen
---

Blockchains have unique properties that make them an excellent fit for certain use cases where security, transparency, and decentralization are paramount:

### Finance
Blockchains enable secure, transparent transactions without the need for intermediaries. This is the foundation of cryptocurrencies and decentralized finance (DeFi) platforms. The immutability of blockchain records ensures that financial transactions are tamper-proof and can be audited at any time, making it ideal for high-stakes environments where trust is critical.

### Supply Chain Management
Blockchain can provide an immutable record of a product's journey from origin to consumer, increasing transparency and reducing fraud. This helps ensure that every step of the supply chain is accurately tracked and verified.

### Voting Systems
Blockchain's transparency and security ensure that votes are accurately counted and cannot be altered. This is crucial for maintaining democratic integrity and building trust in electoral processes.

## Downsides

However, the same properties that make blockchains so powerful in these areas also introduce significant challenges. Blockchains are inherently less efficient than traditional databases because they require consensus among distributed nodes, which can slow down transaction speeds and increase the complexity of operations. This makes blockchain less suitable for use cases where high speed and efficiency are critical, such as real-time data processing or high-frequency trading. Additionally, the complexity of developing and maintaining blockchain systems can be a barrier, particularly for applications that don't require the levels of security and decentralization that blockchains offer.

When deciding whether to use blockchain, consider whether your use case requires the specific advantages of decentralization, transparency, and security. Blockchain is well-suited for applications where trust between parties is a major concern and where an immutable record of transactions is essential. However, if your application demands high throughput, real-time processing, or simplicity, a traditional centralized system might be more appropriate. In short, blockchain is a powerful tool for the right situations, but its use should be carefully considered against the specific needs of your application.

# Payments Use Case (/academy/blockchain-fundamentals/03-payments-use-case/01-payments-use-case)

---
title: Payments Use Case
description: Explore how blockchain technology can revolutionize payments by building decentralized systems. This chapter delves into account balances, transactions, and user interactions, highlighting the benefits of blockchain for security, transparency, and decentralization. Discover how these concepts apply to various use cases beyond payments, including decentralized finance, voting systems, and supply chain management.
updated: 2024-09-01
authors: [martineckardt]
icon: Book
---

In this chapter we will dive deeper in the payments use case. We will explore how blockchain technology can be used to build a decentralized payment system. We will look at the different components of a payment system, such as account balances, transactions, and user interactions. We will also discuss the benefits of using blockchain technology for payments, such as security, transparency, and decentralization.

| Use Case                  | Data Structures  	| User Interactions  	|
|-----------------------	|------------------	|--------------------	|
| Payments              	| Account Balances 	| Transfer Funds     	|
| Decentralized Finance 	| Loans, ...       	| Borrow, Repay, ..  	|
| Voting Systems        	| Votes            	| Vote               	|
| Supply Chain          	| Shipments        	| Hand Over, Deliver 	|
| Identity Management   	| Certificates     	| Issue, Proof       	|

Many of the concepts we will discuss in this chapter are applicable to other use cases as well. For example, the idea of account balances and transactions is not unique to payments but can be found in other applications like decentralized finance (DeFi) or supply chain management. Similarly, user interactions such as transferring funds or voting can be applied to various use cases, each with its unique requirements and challenges.

So while we are discussing this specific use case, try to think about how these concepts could be adapted to other scenarios. This will help you understand the broader implications of blockchain technology and how it can be used to solve a wide range of problems across different industries and domains.

# Account Balances & Transfers (/academy/blockchain-fundamentals/03-payments-use-case/02-account-balances-transfers)

---
title: Account Balances & Transfers
description: Learn about account balances, which reflect the current amount of money or assets in an account after credits and debits. Discover how transfers work by moving funds between accounts, ensuring balance integrity across financial systems.
updated: 2024-09-01
authors: [martineckardt]
icon: BookOpen
---

## Account Balances

Account Balances refer to the current amount of money or assets held in a specific account at a given time. This number reflects the total value after all credits (additions) and debits (subtractions) have been accounted for, indicating how much the account holder has available to use or withdraw. For example, in a bank account, the balance represents the amount of money that the account holder can access, whether for spending, saving, or transferring.

<div className="max-w-96 mx-auto">
    ![](/common-images/blockchain-basics/payments/account-balances.png)
</div>

## Transfers

A Transfer is the process of moving money or assets from one account to another. During a transfer, the balance of the sending account is reduced by the amount being transferred, while the balance of the receiving account is increased by the same amount. This operation ensures that the total value across all accounts remains constant, maintaining the integrity of the overall financial system. 

![](/common-images/blockchain-basics/payments/transfer.png)

## Invalid Transfers

An invalid transfer occurs when a transaction request exceeds the available balance in the sending account. In such cases, the transfer cannot be executed, and the system will reject the transaction to prevent overdrafts. As a result, both the sending and receiving account balances remain unchanged, preserving the integrity of the financial records. This safeguard ensures that accounts do not inadvertently fall into negative balances and maintains accurate and reliable financial tracking.

![](/common-images/blockchain-basics/payments/transfer-invalid.png)

# Ledger (/academy/blockchain-fundamentals/03-payments-use-case/03-ledger)

---
title: Ledger
description: Understand the high-level structure of this chapter.
updated: 2024-09-01
authors: [martineckardt]
icon: BookOpen
---

A ledger is a comprehensive record-keeping system that documents all transactions. It maintains a detailed and chronological list of transactions, capturing every transfers across accounts. This ensures that every action is accurately tracked and traceable, providing a clear and complete view of the system's activity.

![](/common-images/blockchain-basics/payments/ledger.png)

## Immutability

An immutable ledger means that once a transaction is recorded, it cannot be altered or deleted. This immutability ensures that the historical record of all transactions remains intact and unchangeable, which is crucial for maintaining transparency and trust. Even if errors are made or transactions are invalid, the ledger preserves the original data, preventing tampering or unauthorized modifications.

## Append-Only

An append-only ledger operates by adding new transactions to the end of the record without altering any previous entries. This means that while the ledger grows with each new transaction, past transactions remain unchanged and preserved. Invalid transactions, which fail to execute due to issues like insufficient funds, are still recorded in the ledger to maintain a complete history. To reverse the effects of a transaction, a new transaction must be appended that counteracts the previous one, ensuring the integrity and consistency of the ledger’s overall state.

# Signatures (/academy/blockchain-fundamentals/04-signatures/01-signatures)

---
title: Signatures
description: Learn how digital signatures ensure transaction authenticity and security in blockchain systems through public-key cryptography. Understand the role of private and public keys in creating verifiable, tamper-proof transactions that maintain trust in decentralized networks.
updated: 2025-10-29
authors: [martineckardt, katherineavalabs]
icon: Book
---

Digital signatures are a fundamental component of blockchain technology, providing the cryptographic foundation for secure, authentic, and tamper-proof transactions.

As handwritten signatures do, digital signatures enable users to prove their identity, authorize transactions or attest events.

## What Are Digital Signatures?

A **digital signature** is a cryptographic mechanism that ensures the authenticity, integrity, and non-repudiation of digital messages or transactions. Think of it as an electronic "fingerprint" that uniquely binds a transaction to its originator. Unlike physical signatures, digital signatures are mathematically generated and virtually impossible to forge.

In blockchain systems, every transaction must be signed by the sender to prove that they authorize the transfer of assets. This signature provides:

- **Authentication**: Confirms the identity of the transaction sender
- **Integrity**: Ensures the transaction data hasn't been altered
- **Non-repudiation**: Prevents the sender from denying they made the transaction

## How Digital Signatures Work

Digital signatures rely on **asymmetric cryptography**, which uses a pair of mathematically related keys:

### Key Pairs

1. **Private Key**: A secret key known only to the owner. This key is used to sign transactions and must be kept secure. If someone gains access to your private key, they can impersonate you and authorize transactions on your behalf.

2. **Public Key**: A publicly shared key derived from the private key. Anyone can use this key to verify signatures created by the corresponding private key. The public key serves as your address or identity on the blockchain.

These keys are mathematically linked in a special way: data signed with the private key can be verified using the public key, but the private key cannot be derived from the public key.

### The Signing Process

When a user wants to make a transaction on a blockchain:

1. **Create Transaction**: The user creates a transaction specifying details like the recipient's address and the amount to transfer.

2. **Sign Transaction**: The user's wallet software uses their private key to create a unique digital signature for this specific transaction. The signature is generated by applying a cryptographic algorithm (like ECDSA - Elliptic Curve Digital Signature Algorithm) to the transaction data and the private key.

3. **Broadcast**: The transaction, along with the digital signature and the user's public key, is broadcast to the network.

4. **Verification**: Network nodes receive the transaction and use the provided public key to verify the signature. This confirms that:
   - The transaction was signed by the holder of the private key corresponding to the public key
   - The transaction data hasn't been modified since it was signed

5. **Accept or Reject**: If the signature is valid, the transaction is accepted for inclusion in a block. If invalid, it's rejected.

## Why Digital Signatures Matter

Digital signatures solve several critical problems in decentralized systems:

### Ownership and Authorization

In traditional systems, a bank verifies your identity when you make a transaction. In a decentralized blockchain, there's no central authority to verify identity. Digital signatures provide a mathematical proof that the person initiating a transaction owns the account and authorizes the transfer.

### Tamper Detection

If anyone tries to modify a signed transaction—even by changing a single character—the signature becomes invalid. This makes it immediately obvious that the transaction has been tampered with, and network nodes will reject it.

### Privacy with Accountability

Digital signatures allow you to prove you own an account without revealing your private key. You can transact publicly while keeping your credentials private. Every transaction is traceable to a public key, but the identity behind that key can remain pseudonymous.

### Trustless Verification

Anyone can verify a signature using the public key without needing to trust a third party. This enables the trustless, peer-to-peer nature of blockchain networks where participants don't need to know or trust each other to transact safely.

## Common Signature Schemes

Different blockchains use different cryptographic algorithms for digital signatures:

- **ECDSA (Elliptic Curve Digital Signature Algorithm)**: provides strong security with relatively small key sizes, making it efficient for blockchain applications.

- **EdDSA (Edwards-curve Digital Signature Algorithm)**: alternative to ECDSA, offering improved performance and security properties.

- **BLS (Boneh-Lynn-Shacham) Signatures**: provide small sized signature aggregations to maintain security while saving space when multiple signatures are needed.

- **Schnorr Signatures**: enable more complex use cases like multi-signature transactions in a more efficient way.

## Security Considerations

The security of digital signatures depends entirely on keeping private keys secure:

- **Never share your private key**: Anyone with access to your private key can sign transactions as you
- **Use secure storage**: Store private keys in hardware wallets or secure software wallets
- **Backup carefully**: Lose your private key, and you lose access to your assets forever
- **Beware of phishing**: Never enter your private key on untrusted websites or applications

Digital signatures are the cornerstone of blockchain security, enabling trustless, verifiable transactions in a decentralized environment. Understanding how they work is essential to grasping how blockchains maintain security without central authorities.

<Quiz quizId="1001"/>

# Transaction Ordering through Consensus (/academy/blockchain-fundamentals/04-tx-ordering-through-consensus/01-tx-ordering-through-consensus)

---
title: Transaction Ordering through Consensus
description: Explore how blockchain networks achieve agreement on transaction order through consensus mechanisms. Learn why consistent transaction ordering is critical for preventing double-spending and maintaining a unified ledger state across all network participants.
updated: 2025-10-29
authors: [martineckardt, katherineavalabs]
icon: Book
---

In a blockchain network, thousands of participants may be submitting transactions simultaneously from anywhere in the world. For the system to function correctly, all participants must agree on a single, consistent order of transactions. This agreement is achieved through **consensus mechanisms**: the protocols that enable distributed networks to coordinate and maintain a unified view of the blockchain's state.

## Why Transaction Ordering Matters

Imagine two people trying to spend the same money at the same time, this is called a **double-spending problem**. In traditional banking, a central server processes transactions one by one and ensures you can't spend the same dollar twice. But in a decentralized blockchain, there's no central authority to determine which transaction came first.

Consider this scenario:

- Alice has 10 tokens in her account
- She creates two transactions almost simultaneously:
  - Transaction A: Send 10 tokens to Bob
  - Transaction B: Send 10 tokens to Charlie
- Both transactions are valid on their own, but Alice doesn't have enough tokens to fulfill both

The network must decide which transaction to process first. Whichever transaction is ordered first will succeed, and the second will be rejected as invalid (insufficient balance). Without a consensus mechanism to establish a definitive order, different nodes might process these transactions in different orders, leading to inconsistent ledger states across the network.

This is why **transaction ordering through consensus** is fundamental to blockchain technology.

## What Is Consensus?

**Consensus** is the process by which distributed network participants agree on a single, authoritative version of the truth: in this case, the order and validity of transactions. A consensus mechanism is the set of rules and procedures that enables this agreement.

Key objectives of consensus mechanisms:

1. **Agreement**: All honest nodes eventually agree on the same transaction order
2. **Validity**: Only valid transactions (properly signed, sufficient balance, etc.) are included
3. **Termination**: The network reaches consensus in a reasonable time
4. **Integrity**: The agreed-upon order cannot be altered retroactively

## How Consensus Orders Transactions

Different consensus mechanisms use different approaches, but they generally follow a similar pattern:

### The Basic Process

1. **Transaction Submission**: Users create and broadcast transactions to the network

2. **Transaction Pool**: Each node maintains a pool (or mempool) of unconfirmed transactions it has received

3. **Block Proposal**: Specific nodes (miners, validators, or leaders, depending on the consensus mechanism) are selected or compete to propose the next block of transactions

4. **Block Validation**: Other nodes verify that the proposed block contains valid transactions in a valid order

5. **Block Acceptance**: Through the consensus mechanism, the network agrees to accept or reject the proposed block

6. **Blockchain Extension**: Once accepted, the block is added to the blockchain, and its transaction order becomes permanent

7. **State Update**: All nodes update their local copy of the blockchain state based on the newly confirmed transactions



## Consensus vs. Transaction Ordering

It's important to understand the relationship between these concepts:

- **Consensus Mechanism**: The overall protocol that enables distributed agreement
- **Transaction Ordering**: The specific outcome achieved through consensus—determining the sequence in which transactions are processed

The consensus mechanism is the tool, and transaction ordering is one of the primary goals it achieves. But consensus mechanisms do more than just order transactions, they also:

- Determine who can add new blocks to the chain
- Prevent malicious actors from rewriting history
- Ensure the network remains operational even when some nodes fail or act dishonestly
- Distribute decision-making power across the network

## Why Decentralized Consensus Is Challenging

Achieving consensus in a decentralized network is remarkably difficult because:

1. **No Central Authority**: There's no trusted party to make final decisions

2. **Network Delays**: Messages take time to propagate across the network, so different nodes may see transactions in different orders

3. **Byzantine Actors**: Some participants may be malicious and try to disrupt consensus or manipulate transaction ordering for their benefit

4. **Asynchrony**: The network doesn't operate in perfect synchronization—nodes may go offline, come back online, or experience varying network conditions



# Longest Chain Consensus (/academy/blockchain-fundamentals/04-tx-ordering-through-consensus/02-longest-chain-consensus)

---
title: Longest Chain Consensus
description: Understand the longest chain rule and how it resolves conflicts in blockchain networks. Learn why accumulated chain weight determines the valid chain and how this mechanism prevents forks from permanently splitting the network.
updated: 2025-10-29
authors: [martineckardt, katherineavalabs]
icon: BookOpen
---

The **Longest Chain Rule** is a fundamental principle used in many blockchain networks to resolve conflicts and maintain a single, unified ledger. It's the mechanism that ensures all nodes eventually agree on which version of the blockchain is the "correct" one, whether the network uses Proof of Work, Proof of Stake, or other mechanisms.

## The Problem: Competing Chains

In a distributed network where multiple block producers are working simultaneously, it's possible for two validators to propose valid blocks at nearly the same time. When this happens:

- Both validators broadcast their blocks to the network
- Different nodes might receive different blocks first
- The blockchain temporarily "forks" into two competing versions
- Each version is valid on its own, but the network must choose one

Without a clear rule for resolving this situation, the network could permanently split into different chains, destroying the consensus that makes blockchain valuable.

## What Is the Longest Chain Rule?

The **Longest Chain Rule** states: **when multiple valid versions of the blockchain exist, nodes should accept the chain with the most accumulated weight as the authoritative chain.**

"Longest" doesn't necessarily mean the most blocks—it means the chain representing the greatest cumulative weight according to the protocol's rules. The specific weight metric varies by consensus mechanism, but the principle remains the same.

### A Simpler Way to Think About It

Think of it as the "preferred" chain—the one that the protocol considers most valid based on its consensus rules. The chain with the most accumulated weight represents the majority's view of the transaction history, whether that majority is measured by computational resources, stake, or other validation criteria.

## How the Longest Chain Rule Works

Let's walk through a typical scenario:

### Step 1: The Fork

1. Block 100 is the latest confirmed block
2. Validator Alice proposes Block 101A at the same moment Validator Bob proposes Block 101B
3. Both blocks are valid and properly reference Block 100
4. Alice broadcasts Block 101A; Bob broadcasts Block 101B
5. Nodes closer to Alice add 101A to their chain; nodes closer to Bob add 101B
6. The network now has two competing chains

### Step 2: The Race

Both chains continue:
- Some validators build on top of Block 101A
- Other validators build on top of Block 101B
- Each chain is growing independently
- Neither is "wrong"—they're both valid according to protocol rules

### Step 3: Resolution

Eventually (usually within seconds or minutes):
- A validator building on Block 101A proposes Block 102A
- Now the chain ending in Block 102A is longer (has more cumulative weight)
- Nodes following the 101B chain see the longer chain
- According to the longest chain rule, they switch to the longer chain
- Block 101B is "orphaned"—it's valid but no longer part of the main chain
- Transactions in Block 101B return to the mempool to be included in future blocks

### Step 4: Convergence

- All nodes now agree on the chain: Block 100 → Block 101A → Block 102A
- The network has re-converged on a single version
- Normal operation continues

## Why Does This Work?

The longest chain rule works because of several key properties:

### Honest Majority Assumption

If honest validators control the majority of the network's validation power:
- The honest chain will grow faster on average
- Eventually, the honest chain will always be longer
- The network naturally converges on the honest version

### Self-Reinforcing Mechanism

Once one chain gets ahead:
- More validators see it as the valid chain
- More validators build on top of it
- It extends even further ahead
- The gap becomes insurmountable for the shorter chain

### Economic Incentives

Validators are incentivized to build on the longest chain:
- Only blocks in the longest chain earn rewards
- Building on a shorter chain wastes resources and validation opportunities
- Rational validators immediately switch to the longest chain when they see it

## Implications for Transaction Finality

The longest chain rule has important implications for when transactions can be considered "final":

### Confirmations

A transaction's **confirmation count** is the number of blocks added after the block containing that transaction:

- **0 confirmations**: Transaction is in the mempool but not yet in a block (unconfirmed)
- **1 confirmation**: Transaction is in the latest block
- **2 confirmations**: One block has been added after the block containing the transaction
- **Multiple confirmations**: The more confirmations, the more secure the transaction

### Why Wait for Multiple Confirmations?

The more confirmations a transaction has, the deeper it is in the blockchain:

- To reverse a transaction with 1 confirmation, an attacker needs to produce 2 blocks faster than the honest network
- To reverse a transaction with 6 confirmations, an attacker needs to produce 7 blocks faster than the honest network
- This becomes exponentially harder with each additional confirmation

**Probabilistic Finality**: In systems using the longest chain rule, finality is never 100% absolute—there's always a theoretical possibility of reversal. However, this probability becomes negligibly small after several confirmations.

## When the Longest Chain Rule Can Be Attacked

### The 51% Attack

If an attacker controls more than 50% of the network's validation power:

1. **They can create a private chain**: Produce blocks in secret without broadcasting them
2. **Outpace the honest chain**: Because they control the majority, their secret chain grows faster
3. **Release the longer chain**: Suddenly broadcast their chain, which is now longer
4. **Network switches**: Nodes follow the longest chain rule and switch to the attacker's version
5. **Transactions reversed**: Transactions in the honest chain are reversed

**Why This Rarely Happens**:
- Acquiring 51% of validation power is extremely expensive (billions of dollars for major networks)
- The attack would crash the cryptocurrency's value, destroying the attacker's investment
- The attack is detectable and the community can respond (fork to a new chain, change consensus algorithm)

### Deep Reorgs

A **deep reorganization** (reorg) occurs when a long chain is replaced by an even longer competing chain:

- **Shallow reorgs** (1-2 blocks): Common and expected, happen naturally due to network delays
- **Deep reorgs** (6+ blocks): Extremely rare and usually indicate an attack or major network problem
- **Protection**: Waiting for more confirmations protects against all but the most resourced attackers

## Key Takeaways

- The longest chain rule resolves temporary forks by having nodes accept the chain with the most accumulated weight
- It ensures the network converges on a single, consistent version of transaction history
- Transaction finality is probabilistic—more confirmations mean exponentially higher security
- The rule works because honest validators control the majority of validation power and have incentives to follow it
- 51% attacks are theoretically possible but economically impractical for large, decentralized networks

The longest chain rule is a cornerstone of many blockchain consensus mechanisms, transforming a chaotic distributed system into an ordered, synchronized ledger that all participants can trust. It's a beautifully simple solution to a complex problem: letting the network reach agreement through a clear, objective metric rather than requiring explicit coordination.

<Quiz quizId="1002"/>


# Transaction Lifecycle (/academy/blockchain-fundamentals/04-tx-ordering-through-consensus/xx-tx-lifecycle)

---
title: Transaction Lifecycle
description: Follow a blockchain transaction from creation to finalization. Learn each step in the journey—from signing with your private key to achieving confirmation deep within the blockchain.
updated: 2025-10-29
authors: [martineckardt, katherineavalabs]
icon: Notebook
---

Understanding the complete lifecycle of a blockchain transaction helps demystify how decentralized systems process payments and maintain security. Let's follow a transaction from start to finish, exploring what happens at each stage.

## Creation

A transaction begins when a user decides to transfer assets. This involves specifying several key pieces of information:

**What's Included**:
- **Sender's address**: Derived from the sender's public key, identifying who is sending the assets
- **Recipient's address**: The destination address where the assets will be sent
- **Amount**: How much cryptocurrency or tokens to transfer
- **Transaction fee**: Payment offered to miners/validators for including the transaction in a block
- **Nonce**: A sequence number that prevents the same transaction from being processed multiple times
- **Additional data**: Optional fields for smart contract interactions or notes

**User Interaction**:
The user typically interacts with wallet software (desktop app, browser extension, mobile app, or hardware wallet) that provides a user-friendly interface for creating the transaction. Behind the scenes, the wallet constructs the transaction data structure according to the blockchain's protocol specifications.

**Example**:
Alice wants to send 10 AVAX to Bob. She opens her wallet, enters Bob's address (0x742d35Cc...), specifies 10 AVAX, and reviews the estimated transaction fee of 0.01 avax. She confirms she wants to proceed.

## Signing

Once the transaction is created, it must be cryptographically signed to prove authorization:

**The Signing Process**:
1. The transaction data is hashed to create a unique fingerprint of the transaction
2. This hash is encrypted using the sender's **private key**, creating a digital signature
3. The signature is attached to the transaction along with the sender's public key
4. The combined package (transaction + signature + public key) is now ready for broadcasting

**Why Signing Matters**:
- **Authentication**: Proves the transaction was authorized by the owner of the private key
- **Integrity**: Any modification to the transaction data would invalidate the signature
- **Non-repudiation**: The sender cannot later deny creating the transaction

**Security Note**: The private key never leaves the wallet and is never transmitted over the network. Only the signature (produced using the private key) is shared.

**Example**:
Alice's wallet uses her private key to sign the transaction. The wallet computes a unique signature like "0x8f3b2a..." that mathematically binds Alice's authorization to this specific transaction sending 10 AVAX to Bob.

## Broadcasting

After signing, the transaction is broadcast to the peer-to-peer network:

**How Broadcasting Works**:
1. The wallet sends the signed transaction to one or more nodes it's connected to
2. Each node that receives the transaction performs basic validation
3. If valid, the node forwards the transaction to its peer nodes
4. This process continues until the transaction propagates throughout the network
5. Within seconds, most nodes have received the transaction

**Network Topology**:
Blockchain networks use a peer-to-peer (P2P) gossip protocol where each node connects to multiple other nodes. When a node receives a new transaction, it shares it with its neighbors, who share it with their neighbors, creating exponential propagation.

**What Gets Broadcast**:
- The complete transaction data
- The digital signature
- The sender's public key

**Example**:
Alice's wallet connects to several Avalanche nodes and sends them her signed transaction. Within 1-2 seconds, the transaction has propagated to thousands of nodes worldwide. Each node now knows that Alice wants to send 10 AVAX to Bob.

## Verification

Before accepting a transaction, nodes perform multiple checks:

**Validation Checks**:

1. **Signature Verification**:
   - Use the provided public key to verify the signature
   - Confirm the transaction was signed by the owner of the sender's address
   - Reject if signature is invalid or doesn't match the public key

2. **Balance Check**:
   - Query the current blockchain state to check the sender's balance
   - Ensure the sender has enough assets to cover both the transfer amount and the transaction fee
   - Reject if insufficient balance

3. **Nonce Verification** (account-based systems):
   - Check that the transaction nonce matches the expected sequence number
   - Prevents replay attacks and ensures transactions are processed in order
   - Reject if nonce is incorrect

4. **Format Validation**:
   - Verify the transaction follows the correct data structure
   - Check that addresses are valid
   - Ensure the transaction isn't malformed

5. **Double-Spend Prevention**:
   - Check that the same input hasn't already been spent in another transaction (UTXO systems like Bitcoin)
   - Compare against pending transactions in the mempool

**Two-Stage Validation**:
- **Fast validation**: Nodes do lightweight checks when receiving a transaction via broadcast
- **Full validation**: Miners/validators do comprehensive checks before including it in a block

**What Happens If Verification Fails**:
- The node rejects the transaction and doesn't forward it to peers
- The transaction dies and doesn't enter the mempool
- The sender's wallet may receive an error message
- The sender must fix the issue and create a new transaction

**Example**:
Nodes receive Alice's transaction and verify: (1) The signature is valid using Alice's public key, (2) Alice's account has at least 10.01 AVAX (10 AVAX + 0.01 AVAX fee), (3) The nonce is 47, which is correct for Alice's next transaction, (4) The transaction format is valid. All checks pass, so the transaction enters the mempool.

## Mempool (Transaction Pool)

After verification, valid transactions wait in a temporary holding area:

**What Is the Mempool**:
- Short for "memory pool"—a collection of unconfirmed transactions stored in each node's RAM
- Each node maintains its own mempool (they may differ slightly due to network propagation times)
- Transactions wait here until a miner or validator includes them in a block

**Transaction Ordering in Mempool**:
Transactions are typically prioritized by:
- **Fee level**: Higher fees get priority (especially important during network congestion)
- **Time received**: Older transactions may get preference among same-fee transactions
- **Dependencies**: Some transactions must wait for others to be confirmed first

**Mempool Dynamics**:
- Size fluctuates based on network activity
- During high congestion, mempools grow large and low-fee transactions may wait hours or days
- Transactions can be evicted if mempool becomes too full (lowest-fee transactions removed first)
- Users can often replace pending transactions by resubmitting with higher fees (Replace-By-Fee)

**Example**:
Alice's transaction sits in the mempool of thousands of nodes. She offered a fee of 0.01 AVAX, which is above the minimum required. The transaction will likely be included in the next block as validators select transactions to process.

## Consensus (Block Inclusion)

Validators select transactions from the mempool to include in the next block:

**Block Construction**:
1. The validator selects transactions from their mempool
2. Transactions are typically chosen by fee level and arrival time
3. The block has size or gas limits, so not all transactions can fit
4. The validator arranges transactions in order and creates a block

**Consensus Process**:
Different networks use different approaches:

In systems with Proof of Work:
- Block producers compete to solve a cryptographic puzzle
- First to solve it gets to propose their block
- Other nodes verify the solution and accept the block if valid
- Can take several minutes or even hours per block

In systems with Proof of Stake:
- Validators are selected (often based on their stake) to propose blocks
- Other validators attest that the block is valid
- Block is accepted once enough validators attest to it
- Can take seconds or minutes depending on implementation

**Block Reward**:
The validator who successfully adds the block typically receives:
- Block reward (newly created cryptocurrency, if applicable)
- All transaction fees from transactions in the block

**Example**:
A validator selects Alice's transaction along with hundreds of others and includes it in a block. Through the consensus process, the network validates and accepts the block. Alice's transaction now has 1 confirmation.

## Finalization

The final stage is when the transaction becomes permanently part of the blockchain:

**Confirmation Count**:
- **1 confirmation**: Transaction is in the most recent block
- **2 confirmations**: One additional block has been added after the block containing the transaction
- **6 confirmations**: Six blocks deep (generally considered secure in Bitcoin)
- **12+ confirmations**: Very secure, reversal extremely unlikely

**Why Multiple Confirmations Matter**:
- The deeper a transaction is in the blockchain, the harder it is to reverse
- To reverse a transaction with 6 confirmations, an attacker would need to remine 6 blocks faster than the honest network
- This becomes exponentially more difficult and expensive with each confirmation

**Finality Types**:

* **Probabilistic Finality** (PoW, longest-chain systems):
   - Never 100% final, but probability of reversal approaches zero
   - Each additional block makes reversal exponentially more difficult
   - Standard in Bitcoin, Ethereum (pre-merge), and similar systems

* **Absolute Finality** (Some PoS systems):
   - Once finalized, transactions are mathematically impossible to reverse
   - Used in systems with finality gadgets or BFT consensus
   - Provides faster economic certainty but may sacrifice some decentralization

**State Update**:
Once confirmed, the transaction's effects are reflected in the blockchain state:
- Sender's balance decreases by the amount plus fee
- Recipient's balance increases by the amount
- The nonce is incremented
- Smart contract state may be updated (if applicable)

**Example**:
A few seconds after being included in a block, Alice's transaction is considered final on Avalanche's C-Chain due to its fast-finality consensus. Bob's wallet now shows the 10 AVAX as confirmed and available to spend. Alice's balance shows 10.01 AVAX less than before (10 AVAX transferred + 0.01 AVAX fee). The transaction is complete and irreversible.

## Summary: Complete Lifecycle Visualization

```
1. CREATION
   User creates transaction
   ↓
2. SIGNING
   Wallet signs with private key
   ↓
3. BROADCASTING
   Propagates across P2P network
   ↓
4. VERIFICATION
   Nodes validate signature, balance, format
   ↓
5. MEMPOOL
   Waits in memory pool
   ↓
6. CONSENSUS
   Included in block by validator
   ↓
7. FINALIZATION
   Gains confirmations, becomes irreversible
```

## Key Takeaways

- **Creation**: User specifies transaction details in wallet software
- **Signing**: Private key cryptographically signs the transaction to prove authorization
- **Broadcasting**: Transaction propagates through P2P network in seconds
- **Verification**: Nodes check signature, balance, and format before accepting
- **Mempool**: Validated transactions wait to be included in a block
- **Consensus**: Miners/validators include transaction in a block through consensus mechanism
- **Finalization**: Additional blocks make transaction increasingly irreversible

Understanding this lifecycle helps explain why blockchain transactions take time (consensus process), why fees matter (mempool prioritization), and why multiple confirmations are recommended (finality assurance). Each step serves a crucial purpose in maintaining the security and integrity of the decentralized system.

<Quiz quizId="1003"/>

<Quiz quizId="1006"/>


# Sybil Protection (/academy/blockchain-fundamentals/05-sybil-protection/01-sybil-protection)

---
title: Sybil Protection
description: Understand Sybil attacks and how blockchain networks defend against fake identities attempting to gain disproportionate influence. Learn the crucial distinction between consensus mechanisms that order transactions and Sybil defense mechanisms that prevent identity manipulation.
updated: 2025-10-29
authors: [martineckardt, katherineavalabs]
icon: Book
---

Decentralized networks face a unique challenge: how do you prevent a single malicious actor from creating thousands of fake identities to manipulate the system? This threat is known as a **Sybil attack**, and defending against it is critical for maintaining the security and fairness of blockchain networks.

## What Is a Sybil Attack?

A **Sybil attack** occurs when a single entity creates multiple fake identities (Sybil nodes) to gain disproportionate influence or control over a network. The name comes from a famous case study of a patient with dissociative identity disorder who had multiple personalities.

In a blockchain context, imagine if:

- One person could create 1,000 fake "validator" identities
- Each identity appears to be a different, independent participant
- Together, these fake identities control enough voting power to manipulate the network
- The attacker could approve fraudulent transactions, censor legitimate transactions, or even rewrite blockchain history

### Why Sybil Attacks Are Dangerous

In a decentralized network, decision-making power is supposed to be distributed among many independent participants. But if one entity can masquerade as many participants, they can:

1. **Manipulate Consensus**: Control which transactions are included in blocks or influence the order of transactions
2. **Launch 51% Attacks**: Gain majority control to double-spend or rewrite history
3. **Censor Transactions**: Prevent specific users or types of transactions from being processed
4. **Corrupt Voting**: In governance systems, vote multiple times on protocol changes
5. **Drain Resources**: Spam the network or monopolize scarce resources

The fundamental problem is that in a truly open, permissionless network, creating a new identity is essentially free—you can generate a new public/private key pair instantly at no cost.

## Sybil Defense Mechanisms

**Sybil defense mechanisms** (also called Sybil resistance) are strategies designed to make it expensive or impractical for an attacker to create multiple identities. The goal is to ensure that influence in the network is tied to something scarce and difficult to fake.

### Making Identity Creation Costly

The most common approach is to attach a real-world cost to each identity or vote in the system:

**Resource-Based Defenses:**

1. **Computational Resources**: Require identities to perform expensive computations (Proof of Work)
2. **Financial Resources**: Require identities to stake valuable assets (Proof of Stake)
3. **Physical Resources**: Require identities to control unique hardware or network capabilities
4. **Human Verification**: Require identities to prove they are unique human beings (Proof of Personhood)

The key principle is: if creating each identity requires spending something valuable and scarce, an attacker cannot create unlimited identities without unlimited resources.

## The Crucial Difference: Consensus vs. Sybil Defense

This is one of the most important distinctions in blockchain technology, and they're often confused because the same mechanisms serve both purposes. Let's clarify:

### Consensus Mechanisms

**Purpose**: Achieve agreement among network participants on the state of the blockchain

**What They Do**:
- Determine the order of transactions
- Decide which block to add to the blockchain next
- Ensure all honest nodes converge on the same history
- Resolve conflicts when multiple blocks are proposed simultaneously

**The Question They Answer**: "What is the correct state of the blockchain that we all agree on?"

### Sybil Defense Mechanisms

**Purpose**: Prevent a single entity from controlling multiple identities to gain disproportionate influence

**What They Do**:
- Make it expensive to create new identities
- Tie influence to scarce, real-world resources
- Ensure each participant's power is limited
- Prevent attackers from simulating a large number of network participants

**The Question They Answer**: "How do we ensure that each identity in the network represents a truly independent entity?"

## Real-World Example: Bitcoin

Bitcoin uses Proof of Work:

**Consensus Role**:
- Miners compete to find valid blocks
- The network follows the longest valid chain
- This ensures all nodes agree on transaction history

**Sybil Defense Role**:
- Creating 100 fake miner identities doesn't give you more power
- What matters is computational power (hash rate), not number of identities
- To control the network, you need 51% of total hash rate, which requires massive investment in hardware and electricity
- This makes Sybil attacks prohibitively expensive

## Why Both Are Necessary

You need both consensus mechanisms AND Sybil defense for a secure blockchain:

**Without Consensus**: Nodes wouldn't agree on the transaction order or blockchain state, leading to fragmentation and inconsistency.

**Without Sybil Defense**: An attacker could create unlimited fake identities to manipulate the consensus process, undermining the entire system.

Think of it this way:
- **Sybil Defense** ensures the participants are legitimate and their influence is fair
- **Consensus Mechanisms** use these legitimate participants to agree on the blockchain state

Together, they create a system where decentralized coordination is possible without trusted authorities, and where influence is earned through real-world resources rather than granted freely to anyone who creates an account.

The choice of Sybil defense mechanism fundamentally shapes the security model, accessibility, and decentralization characteristics of a blockchain network.

<Quiz quizId="1004"/>

# Smart Contracts (/academy/blockchain-fundamentals/06-smart-contracts/01-smart-contracts)

---
title: Smart Contracts
description: Discover how smart contracts revolutionize digital agreements by automatically executing code when conditions are met. Learn how these self-enforcing programs enable decentralized applications, eliminate intermediaries, and create trustless systems on blockchain networks.
updated: 2025-10-29
authors: [martineckardt, katherineavalabs]
icon: Book
---

Blockchains began as systems for recording and transferring digital currency, but they evolved into something much more powerful: platforms for running code. **Smart contracts** are self-executing programs that run on blockchains, automatically enforcing agreements without intermediaries. They represent one of the most transformative applications of blockchain technology.

## What Are Smart Contracts?

A **smart contract** is a program stored on a blockchain that automatically executes when predetermined conditions are met. Think of it as a digital agreement written in code rather than legal language, where the blockchain automatically enforces the terms without requiring trust in any person or institution.

### Traditional Contracts vs. Smart Contracts

**Traditional Contract:**
- Written in legal language
- Requires trusted intermediaries (lawyers, courts, escrow services) to enforce
- Enforcement can be slow, expensive, and subjective
- Parties must trust the legal system to be fair

**Smart Contract:**
- Written in programming code
- Automatically enforced by the blockchain network
- Execution is immediate and deterministic
- No need to trust intermediaries—the code and blockchain guarantee execution

## How Smart Contracts Work

Smart contracts are deployed on blockchain platforms that support programmable logic, with Ethereum being the most well-known example and Avalanche being out favorite one ;).

### The Basic Process

1. **Write the Code**: A developer writes a smart contract in a programming language. The contract defines:
   - The conditions that must be met
   - The actions to take when conditions are satisfied
   - The data the contract stores and manages

2. **Deploy to Blockchain**: The compiled contract is deployed to the blockchain by submitting a special transaction. Once deployed:
   - The contract gets a unique address on the blockchain
   - The code becomes permanent and immutable
   - Anyone can interact with the contract at its address

3. **Interact with the Contract**: Users send transactions to the contract's address to:
   - Call functions defined in the contract
   - Send cryptocurrency or tokens to the contract
   - Read data stored in the contract
   - Trigger the contract's automatic behaviors

4. **Automatic Execution**: When someone interacts with the contract:
   - Every node on the network executes the contract code
   - The contract's logic determines what happens (transfer funds, update data, etc.)
   - All nodes reach consensus on the outcome
   - The blockchain records the state changes

### Key Characteristics

**Deterministic**: Given the same inputs and blockchain state, the contract always produces the same outputs. There's no randomness or external influence.

**Autonomous**: Once deployed, the contract runs exactly as programmed without human intervention. No one can stop it or change how it behaves.

**Transparent**: The contract's code and its current state are visible to everyone on the blockchain. Anyone can verify what it does and audit its behavior.

**Immutable**: After deployment, the contract's code cannot be changed. This ensures that the rules can't be altered after people start using it.

**Trustless**: Users don't need to trust the contract creator or any third party—they only need to trust that the code does what it says (which they can verify) and that the blockchain will execute it correctly.

## Real-World Applications

Smart contracts enable a vast ecosystem of decentralized applications (dApps) across many domains:

### Decentralized Finance (DeFi)

DeFi uses smart contracts to recreate traditional financial services without banks or brokers:

- **Lending Protocols**: Automatically lend cryptocurrency and calculate interest in real-time
- **Decentralized Exchanges**: Trade tokens directly with others without a centralized exchange
- **Stablecoins**: Maintain stable cryptocurrency values through algorithmic smart contracts
- **Yield Farming**: Automatically optimize returns across multiple platforms

### Non-Fungible Tokens (NFTs)

Smart contracts power the creation, ownership, and trading of unique digital assets:

- Prove ownership of digital art, collectibles, or virtual items
- Automatically pay royalties to creators on secondary sales
- Enable fractional ownership of high-value assets

### Supply Chain Management

Track goods as they move through complex supply chains:

- Record each step in a product's journey automatically
- Verify authenticity and prevent counterfeits
- Trigger payments automatically

### Decentralized Autonomous Organizations (DAOs)

Organizations governed entirely by smart contracts:

- Members vote on proposals using tokens
- Approved proposals execute automatically
- Treasury funds are managed transparently by code

### Gaming and Virtual Worlds

Enable true ownership and interoperability of digital items:

- Players truly own their in-game items as tokens
- Items can be traded or used across different games
- Game economies run on transparent, automated smart contracts

### Insurance

Automate claims processing and payouts:

- Parametric insurance that pays out automatically based on data (e.g., weather data for crop insurance)
- No claims adjusters needed for straightforward cases
- Faster payouts with lower overhead

## A Detailed Example: Token Swap

Let's walk through how a smart contract enables a trustless cryptocurrency exchange:

**Scenario**: Alice has 100 AVAX and wants to trade it for Bob's 2,000 USDC. Neither party trusts the other.

**Traditional Solution**: Use a centralized exchange to facilitate the trade. Both parties must trust the exchange to handle their funds honestly and not freeze accounts.

**Smart Contract Solution**:

```solidity
contract TokenSwap {
    address public alice;
    address public bob;
    uint256 public avaxAmount;
    uint256 public usdcAmount;
    bool public aliceDeposited;
    bool public bobDeposited;
    uint256 public deadline;
    
    IERC20 public usdcToken;
    
    // Alice creates the swap offer
    constructor(address _bob, uint256 _usdcAmount, address _usdcToken) payable {
        alice = msg.sender;
        bob = _bob;
        avaxAmount = msg.value;  // Alice deposits AVAX
        usdcAmount = _usdcAmount;
        usdcToken = IERC20(_usdcToken);
        aliceDeposited = true;
        deadline = block.timestamp + 1 hours;  // 1 hour to complete
    }
    
    // Bob deposits his USDC to complete the swap
    function depositUSDC() public {
        require(msg.sender == bob, "Only Bob can deposit");
        require(block.timestamp < deadline, "Swap expired");
        
        usdcToken.transferFrom(bob, address(this), usdcAmount);
        bobDeposited = true;
        
        // Automatically execute the swap
        executeSwap();
    }
    
    // Execute the swap once both have deposited
    function executeSwap() private {
        require(aliceDeposited && bobDeposited, "Both must deposit");
        
        // Send AVAX to Bob
        payable(bob).transfer(avaxAmount);
        
        // Send USDC to Alice
        usdcToken.transfer(alice, usdcAmount);
    }
    
    // If Bob doesn't deposit before deadline, Alice gets her AVAX back
    function refund() public {
        require(block.timestamp >= deadline, "Deadline not reached");
        require(!bobDeposited, "Swap already completed");
        
        payable(alice).transfer(avaxAmount);
    }
}
```

**How It Works**:

1. Alice creates the swap contract, specifying Bob's address and the amount of USDC she wants
2. Alice sends 100 AVAX to the contract when creating it
3. Bob has 1 hour to deposit 2,000 USDC into the contract
4. **If Bob deposits**: The contract automatically swaps—Bob gets the AVAX, Alice gets the USDC
5. **If Bob doesn't deposit**: After the deadline, Alice can call `refund()` to get her AVAX back

This is truly trustless! Neither Alice nor Bob can cheat because:
- Alice can't take back her AVAX once Bob deposits (the swap executes automatically)
- Bob can't get the AVAX without depositing his USDC
- If Bob doesn't participate, Alice simply gets her funds back
- No centralized exchange can freeze, confiscate, or misuse the funds, they are just put on a contract that can't do anything other than executing the swap with them.
- The swap is atomic: either both sides happen, or neither happens

## Challenges and Limitations

While powerful, smart contracts face several challenges:

### Security Vulnerabilities

**The Problem**: Bugs in smart contract code can be exploited. Because contracts are immutable, bugs can't be fixed after deployment.

**Famous Example**: The DAO hack in 2016 resulted in $50 million stolen due to a reentrancy vulnerability.

**Solution**: Rigorous testing, professional audits, formal verification, and secure coding patterns.

### Oracle Problem

**The Problem**: Smart contracts can't access external data (weather, stock prices, sports scores) on their own. They need "oracles" to feed them real-world information.

**Challenge**: Oracles reintroduce trust and potential points of failure into the system.

**Solution**: Decentralized oracle networks that aggregate data from multiple sources.

### Legal Uncertainty

**The Problem**: The legal status of smart contracts is unclear in many jurisdictions. What happens when code conflicts with law?

**Challenge**: Dispute resolution and liability are not always clear.

**Evolution**: Legal frameworks are gradually adapting to recognize smart contracts.

### Immutability Double-Edged Sword

**Benefit**: No one can change the rules

**Risk**: No way to fix bugs or upgrade functionality

**Solutions**: Upgradeable contract patterns or designing migration paths into new contracts.

## The Future of Smart Contracts

Smart contracts are still evolving, with exciting developments on the horizon:

- **New Languages**: Enabling more complex logic and safer programming
- **Cross-Chain Contracts**: Contracts that operate across multiple blockchains
- **Formal Verification**: Mathematical proofs that contracts behave correctly
- **Privacy-Preserving Contracts**: Using zero-knowledge proofs to execute contracts privately

Smart contracts represent a fundamental shift in how we create and enforce agreements. By removing intermediaries and automating execution, they enable new forms of trust, coordination, and economic activity that were previously impossible. As the technology matures, smart contracts are poised to reshape industries from finance to governance to entertainment, creating a more automated, transparent, and accessible digital economy.

## Key Takeaways

- Smart contracts are self-executing programs on blockchains that automatically enforce agreements
- They eliminate the need for trusted intermediaries in many situations
- Once deployed, they are immutable, transparent, and execute deterministically
- They enable decentralized applications across finance, gaming, supply chain, and more
- While powerful, they require careful design to avoid security vulnerabilities

Understanding smart contracts is essential for anyone looking to build on or understand modern blockchain platforms. They're the foundation of the decentralized application ecosystem and represent one of blockchain technology's most significant innovations beyond simple currency.

<Quiz quizId="1005"/>


# Native Tokens (/academy/blockchain-fundamentals/07-independent-tokenomics/01-native-tokens)

---
title: Native Tokens
description: Learn about native tokens and their role in blockchain ecosystems.
updated: 2024-09-03
authors: [0xstt]
icon: Book
---

A **native token** in a blockchain running the Ethereum Virtual Machine (EVM) refers to the primary digital currency or cryptocurrency native to that blockchain. Native tokens act as the foundation for value transfer and network operation within their respective ecosystems.

- **Ethereum**: ETH
- **Avalanche C-Chain**: AVAX
- **Dexalot**: ALOT
- many more...

---

### The Role of Native Tokens

Native tokens serve multiple key roles within EVM-based blockchain networks, such as:

- **Value Transfer**: Native tokens act as the primary currency for peer-to-peer transactions within the network, enabling value exchange between participants.
- **Gas Fees**: Native tokens are used as **gas** to pay for transaction fees, contract deployments, and other network operations. This ensures that resources are allocated efficiently within the network.
- **Security**: In Proof-of-Stake (PoS) networks, native tokens are often used for staking to secure the network and validate transactions.
- **Governance**: In some cases, native tokens grant holders governance rights, allowing them to participate in decision-making processes that shape the blockchain’s future.

---

Native tokens are the backbone of blockchain ecosystems, serving multiple roles that maintain the network's stability, security, and functionality.

# ERC-20 Tokens (/academy/blockchain-fundamentals/07-independent-tokenomics/02-erc-20-tokens)

---
title: ERC-20 Tokens
description: Learn about ERC-20 tokens and their role in blockchain ecosystems.
updated: 2024-09-03
authors: [0xstt]
icon: Book
---

While a blockchain has a single **native token**, the **ERC-20** token standard was developed to allow for the representation of a wide range of assets on EVM-compatible chains. 

**ERC** stands for **Ethereum Request for Comment**, and **20** is the identifier for the specific proposal that defines the standard.

ERC-20 tokens are **fungible**, meaning each token is identical to another and can be exchanged on a one-to-one basis. These tokens are created and managed through smart contracts that adhere to the ERC-20 standard, ensuring interoperability between different tokens and decentralized applications (DApps).

---

### ERC-20 Token Architecture

At the core of every ERC-20 token is a simple **mapping** of addresses to balances, representing the number of tokens an address holds.

```solidity
abstract contract ERC20 is Context, IERC20, IERC20Metadata, IERC20Errors {
    
  mapping(address account => uint256) private _balances;
  
  //...
}
```

Addresses holding ERC-20 tokens can belong to either **Externally Owned Accounts (EOAs)** or **smart contracts**. Both types of accounts can store and transfer ERC-20 tokens, making ERC-20 tokens versatile in decentralized finance (DeFi) and decentralized applications.

---

### Role of ERC-20 Tokens in Blockchain Ecosystems

ERC-20 tokens play an essential role in enabling the creation of decentralized applications with various functionalities:

- **Tokenized Assets**: ERC-20 tokens can represent anything from digital currencies to tokenized real-world assets.
- **DeFi Protocols**: Many DeFi protocols use ERC-20 tokens for lending, staking, and liquidity pools.
- **Token Sales**: ICOs (Initial Coin Offerings) and other fundraising models rely heavily on ERC-20 tokens.

---

### The ERC-20 Interface

All ERC-20 tokens follow a standard interface to ensure compatibility with decentralized applications (DApps). This allows tokens to be easily transferred, approved for spending, and managed by any DApp that follows the same rules.

```solidity
interface IERC20 {
    function name() external view returns (string memory);

    function symbol() external view returns (string memory);

    function decimals() external view returns (uint8);

    function totalSupply() external view returns (uint256);

    function balanceOf(address _owner) external view returns (uint256 balance);

    function transfer(address _to, uint256 _value) external returns (bool success);

    function transferFrom(address _from, address _to, uint256 _value) external returns (bool success);

    function approve(address _spender, uint256 _value) external returns (bool success);

    function allowance(address _owner, address _spender) external view returns (uint256 remaining);
}
```

You can review the full **ERC-20 standard** [here](https://eips.ethereum.org/EIPS/eip-20).

---

### Transferring ERC-20 Tokens

To transfer ERC-20 tokens between accounts, you use the `transfer()` function, where the sender specifies the recipient’s address and the amount to be transferred.

For more complex interactions, such as allowing a smart contract to transfer tokens on behalf of someone else, the ERC-20 standard includes the `approve()` and `transferFrom()` functions. 


<Accordions>
<Accordion title="transfer()">
Transfers tokens from the sender’s account to another account, decreasing the sender's balance and increasing the recipient’s.
</Accordion>
<Accordion title="approve()">
This function allows the owner of a token balance to approve another account (the **spender**) to withdraw up to a specified amount of tokens. The spender can withdraw from the owner's balance multiple times, as long as the total amount doesn’t exceed the approved limit.
</Accordion>
<Accordion title="allowance()">
The `allowance()` function returns the amount that a spender is still allowed to withdraw from an owner's balance.
</Accordion>
<Accordion title="transferFrom()">
This function facilitates the transfer of tokens from one account to another on behalf of the account owner. It is typically used in scenarios where smart contracts need to execute token transfers according to the contract's logic.
</Accordion>
</Accordions>

---

ERC-20 tokens revolutionized the blockchain space by enabling the tokenization of assets and simplifying the creation of decentralized applications. Their standardization ensures compatibility across platforms and DApps, making them an integral part of the broader crypto ecosystem.

# Deploy and Transfer an ERC-20 Token (/academy/blockchain-fundamentals/07-independent-tokenomics/03-deploy-and-transfer-erc-20-tokens)

---
title: Deploy and Transfer an ERC-20 Token
description: Learn how to deploy an ERC-20 token and transfer it between accounts.
updated: 2024-09-03
authors: [0xstt]
icon: Terminal
---

In this section, you will follow a step-by-step guide to deploy an ERC-20 token on a blockchain network and transfer it between accounts. This will provide practical experience with token creation, deployment, and handling transactions.

### Objectives:
- Deploy an ERC-20 token smart contract.
- Interact with your token by transferring it between different accounts.

To learn how to deploy an ERC-20 token and interact with your token on a blockchain, follow [this guide](/academy/interchain-token-transfer/03-tokens/08-transfer-an-erc-20-token) to explore the deployment process using the CLI on our Avalanche L1.

<Quiz quizId="201"/>


# Wrapped Native Tokens (/academy/blockchain-fundamentals/07-independent-tokenomics/04-wrapped-tokens)

---
title: Wrapped Native Tokens
description: Learn about wrapped tokens and their role in blockchain ecosystems.
updated: 2024-09-03
authors: [0xstt]
icon: Book
---

**Wrapped tokens** are blockchain assets that represent a native cryptocurrency (e.g., AVAX, ALOT, ETH) in a tokenized form, typically conforming to the **ERC-20 token standard**. Wrapping a native token allows it to be used in decentralized applications (dApps) and protocols that require ERC-20 tokens.

---

### What Are Wrapped Tokens?

Wrapped tokens are created through a process where the native cryptocurrency is locked in a smart contract, and an equivalent amount of the wrapped token is minted. These wrapped tokens are backed 1:1 by the underlying native asset, ensuring that the value of the wrapped token mirrors that of the original native cryptocurrency.

This **ERC-20 compatibility** is crucial for enabling the native asset to interact with dApps, decentralized exchanges (DEXs), and smart contracts within the EVM ecosystem, where ERC-20 tokens are the standard.

---

### Why Are Wrapped Tokens Important?

Wrapped tokens play an essential role in **interoperability** within the EVM ecosystem, facilitating seamless use across decentralized applications and protocols. Some key benefits include:

- **Liquidity**: Wrapped tokens increase liquidity in DeFi by enabling users to participate in protocols that require ERC-20 tokens, even when their original asset is a native token.
- **Cross-Chain Compatibility**: Wrapped tokens allow assets from one blockchain (e.g., Bitcoin) to be used on another chain, enhancing cross-chain functionality.
- **DeFi Integration**: Wrapped tokens are vital in DeFi protocols such as lending, borrowing, staking, and liquidity pools, where ERC-20 tokens are the standard.

---

### Wrapped Token Contract Interface

A **wrapped token contract** is typically an implementation of the ERC-20 token standard, with added functions for minting and burning tokens to facilitate the wrapping and unwrapping process. Here's a basic contract interface for a wrapped token:

```solidity
interface IWrappedToken {
    function deposit() external payable;
    function withdraw(uint256 amount) external;
    
    function totalSupply() external view returns (uint256);
    function balanceOf(address account) external view returns (uint256);
    function transfer(address recipient, uint256 amount) external returns (bool);
    function allowance(address owner, address spender) external view returns (uint256);
    function approve(address spender, uint256 amount) external returns (bool);
    function transferFrom(address sender, address recipient, uint256 amount) external returns (bool);
}
```

<Accordions>
<Accordion title="deposit()">
This function is used to wrap native tokens. When a user calls deposit(), they send the native cryptocurrency (e.g., AVAX, ETH) to the contract, which then mints an equivalent amount of the wrapped token.
</Accordion>
<Accordion title="withdraw()">
This function is used to unwrap the tokens. It burns the specified amount of wrapped tokens and returns the equivalent amount of native cryptocurrency to the user.
</Accordion>
</Accordions>

# Deploy and Interact with Wrapped Token (/academy/blockchain-fundamentals/07-independent-tokenomics/05-deploy-and-interact-wrapped-tokens)

---
title: Deploy and Interact with Wrapped Token
description: Learn how to deploy and interact with wrapped tokens
updated: 2024-09-03
authors: [0xstt]
icon: Terminal
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

In this section, we will deploy and interact with a wrapped token using **Forge** and **cast** commands. Forge simplifies smart contract deployment, and cast allows you to interact with deployed contracts.

---

<Steps>
<Step>

#### 1. Write the Wrapped Token Contract
Here is a basic implementation of a wrapped token contract in Solidity:

```solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

import "@openzeppelin/contracts/token/ERC20/ERC20.sol";

contract WrappedToken is ERC20 {
    address public nativeTokenHolder;

    constructor() ERC20("Wrapped Token", "WTKN") {}

    function deposit() external payable {
        _mint(msg.sender, msg.value);
        nativeTokenHolder = msg.sender;
    }

    function withdraw(uint256 amount) external {
        _burn(msg.sender, amount);
        payable(msg.sender).transfer(amount);
    }
}
```

</Step>
<Step>

### Deploy ERC20 Receiver
Deploy the Contract Using Forge's `create` Command

```bash
forge create --rpc-url myblockchain --private-key $PK WrappedToken.sol:WrappedToken --broadcast
```

</Step>

<Step>

### Save the Wrapped Token Address

Save the `Deployed to` address in an environment variable.

```bash
export WRAPPED_TOKEN=<address>
```

</Step>

<Step>

### Interacting with the Deployed Contract

Once the contract is deployed, you can interact with it using **cast** commands.


<Accordions>
<Accordion title="Depositing Native Tokens (Wrapping)">

To deposit native tokens and mint wrapped tokens, use the following `cast send` command:

```bash
cast send $WRAPPED_TOKEN "deposit()" --value <AMOUNT> --rpc-url myblockchain --private-key $PK
```

- `<AMOUNT>`: The amount of native tokens you want to wrap (in wei).
</Accordion>
<Accordion title="Withdrawing Native Tokens (Unwrapping)">

To burn the wrapped tokens and retrieve the equivalent amount of native tokens:

```bash
cast send $WRAPPED_TOKEN "withdraw(uint256)" <AMOUNT> --rpc-url myblockchain --private-key $PK
```

- `<AMOUNT>`: The number of wrapped tokens to burn and convert back to native tokens.
</Accordion>
</Accordions>

You can use the following page for [**wei conversions**](https://snowtrace.io/unitconverter).

</Step>

</Steps>

<Quiz quizId="202"/>

# Token Decimals (/academy/blockchain-fundamentals/07-independent-tokenomics/06-token-decimals)

---
title: Token Decimals
description: Learn about token decimals and their impact on blockchain applications.
updated: 2024-09-03
authors: [0xstt]
icon: Book
---

**Token decimals** refer to the level of precision used to define a token’s smallest unit. When a token contract is created, the number of decimals is specified to determine how divisible the token will be. This can have significant implications for user experience, application development, and overall token functionality.

For example:
- **6 decimals**: A token with 6 decimals means the smallest unit is 0.000001.
- **18 decimals**: A token with 18 decimals means the smallest unit is 0.000000000000000001.

---

### Why Are Token Decimals Important?

Token decimals are critical because they determine how small a fraction of the token can be used in transactions. The choice of decimals directly affects how the token is used in various applications, including decentralized finance (DeFi), payments, and staking.

- **Greater Precision**: More decimals allow for finer divisions of the token, which is useful in systems where very small amounts of a token need to be handled (e.g., high-frequency trading, micro-payments, or rewards distribution).
- **User Perception**: The number of decimals can also influence how users perceive the value of the token. A token with fewer decimals might appear more “whole,” making it seem like larger amounts are being used in transactions.

---

**Conclusion**: Token decimals are a fundamental aspect of token design. Choosing the right number of decimals depends on the token's use case, balancing the need for precision with user experience and technical requirements.

# Virtual Machines and Blockchains (/academy/blockchain-fundamentals/08-vms-and-blockchains/01-vms-and-blockchains)

---
title: Virtual Machines and Blockchains
description: Learn about Virtual Machines.
updated: 2024-05-31
authors: [martineckardt]
icon: Book
---

<YouTube id="b-slW7w65VQ" />

Virtual Machines are defining the behaviour of a blockchain. They can be the execution environment for smart contracts and decentralized applications. In this section, you will learn about the Virtual Machines used in Avalanche.

## What You Will Learn

In this section, you will go through the following topics:

- **State Machine:** Understand what a State Machine is and how it works
- **Blockchain:** Learn about the role of VMs in blockchains
- **Variety of VMs:** Learn how Avalanche supports different VMs

# What is a State Machine? (/academy/blockchain-fundamentals/08-vms-and-blockchains/02-state-machine)

---
title: What is a State Machine?
description: Learn about the State Machines in blockchain systems.
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

A virtual machine in the context of a blockchain system is like a decentralized computer that can execute a program in a controlled environment. A Virtual Machine (VM) defines the application-level logic of a blockchain. In technical terms, it specifies the blockchain’s state, state transition function, transactions, and the API through which users can interact with the blockchain.

When you write a VM, you don't need to concern yourself with lower-level logic like networking, consensus, and blockchain structure. Avalanche does this behind the scenes, so you can focus on building.

The most popular VM in blockchain is the Ethereum Virtual Machine (EVM) used in the Ethereum blockchain and others. It enables the creation and execution of smart contracts. However, blockchain systems are not limited to the EVM and many blockchains operate with different virtual machines today. For instance, Solana and Cardano use completely different Virtual Machines.

## Soda Dispenser: A Simple Machine

To better comprehend Virtual Machines, take this analogy of a simple, everyday machine: a soda dispenser. 

For optimal functionality, this machine must **consistently monitor its state**. In this instance, the state may represent the current balance, total revenue, and the number of cans available per brand.

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/avalanche-fundamentals/28-njnfTjsYzVjFGF671wQLlnRwFU9GoV.png)

<Quiz quizId="109"/>

This dispenser permits several **operations**, such as:
- Inserting coins
- Selecting a soda flavor

User operations trigger **state transitions**. For example, when a user inserts a coin, the balance increases. Selecting a soda brand leads to a decrease of the balance by the soda's price and reduces the quantity of that specific brand by one. 

<Quiz quizId="110"/>

Additionally, certain logic might be incorporated to dictate various operational outcomes based on the current state. For example, the machine checks if the balance is sufficient when a user chooses a soda brand. As a result, the outcome could be different in cases where the balance is adequate compared to instances where it isn't.


## Advantages of VMs

Implementing state machines comes with several advantages:

**Clear Interface:** The range of operations provides clarity on how to interact with it. Once familiarized with the interface, you can interact with all soda machines (following the same blueprint) in the same manner.

**Reproducibility:** With a Virtual Machine blueprint, one can create multiple identical instances. These behave consistently, implying that if you conduct the same operations in the same sequence on two different machines, the state will remain identical.

<Quiz quizId="111"/>

# Blockchains (/academy/blockchain-fundamentals/08-vms-and-blockchains/03-blockchains)

---
title: Blockchains
description: Learn about how VMs work in blockchain.
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

Let’s look at how VMs work in blockchain. Each validator operates an instance of our hypothetical soda dispenser. So, they have their own instance of a machine running on their server. They do this so they do not have to trust a single party with the operation of a soda dispenser,  and to make it easy for everyone to verify the outcome of operations.

When a user wishes to execute an operation on this distributed soda dispenser, they transmit the transaction to the network. The validators then reach consensus on the sequence in which transactions are carried out. In Avalanche, validators use Avalanche Consensus, which we talked about earlier.

<Quiz quizId="112"/>

Next, each validator executes the operation on their instance of the VM independently. Because each instance of our Virtual Machine behaves identically, validators maintain a uniform view of the machine’s state, so they balance and the number of available soda per flavor.

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/avalanche-fundamentals/28-njnfTjsYzVjFGF671wQLlnRwFU9GoV.png)

Subsequently, each validator executes the operation on their instance independently. Again, because each instance behaves identically, validators maintain a uniform view of the system's state, encompassing balance and available soda quantities. 

Let’s take the example further. Assume we have 100 validators in our Soda Dispenser Avalanche L1. I submit multiple operations to the validators:

- Insert a quarter
- A little while later, I Insert another quarter
- Choose lemonade

Each of the validators executes the operations on their own machine. After the first quarter the state of the machine states that the balance is 25 cents. After the second operation the balance is 50 cents. After choosing lemonade, the balance goes back to zero and the amount of available lemonades decreases from 8 to 7 on each instance running on each validators server.

This is the fundamental principle of Blockchains in Avalanche: A collective of validators operate identical virtual machines, come to consensus on the order of transactions, execute them, and have a uniform view on the machine's current state.

<Quiz quizId="113"/>

# Variety of Virtual Machines (/academy/blockchain-fundamentals/08-vms-and-blockchains/04-variety-of-vm)

---
title: Variety of Virtual Machines
description: Learn about different types of Virtual Machines.
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

We can take this concept even further: The same network of validators can run two or more blockchains. These could operate different VMs, like a soda dispenser and a candy dispenser, or identical VMs, like two soda dispensers. When a user wants to issue an operation, they specify which blockchain to interact with.

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/avalanche-fundamentals/30-dZcAyNCtqUOXo4LREKAsLTERgAK4Yp.png)

You can think of a Virtual Machine (VM) as a blueprint for a blockchain, where the same VM can create multiple blockchains, each adhering to the same rules but remaining logically independent from the others. 

Even though two blockchains may use the same virtual machine, they each have an independent state. As an example, it could be the case that in one soda dispenser, a user has a credit of 1 dollar to their name while in the other soda dispenser, they do not have any credits to their name.

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/avalanche-fundamentals/31-QO8n2upUS0rKCExySCPex6Yju50Sln.png)

The number of blockchains a validator can validate is primarily limited by the additional computational resources required to operate the virtual machines of all the chains.

<Quiz quizId="114"/>

# Regulation (/academy/blockchain-fundamentals/xx-regulation/01-regulation)

---
title: Regulation
description: TBD
updated: 2024-05-31
authors: [martineckardt]
icon: Book
---


# Proof of Work (/academy/blockchain-fundamentals/xx-tbd-sections/02-proof-of-work)

---
title: Proof of Work
description: TBD
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

TBD

# Proof of Stake (/academy/blockchain-fundamentals/xx-tbd-sections/03-proof-of-stake)

---
title: Proof of Stake
description: TBD
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

- Carrots and Sticks

## Staking Rewards

- Carrot

## Slashing

- Stick

# Signature Schemes (/academy/blockchain-fundamentals/xx-tbd-sections/xx-signature-schemes)

---
title: Signature Schemes
description: TBD
updated: 2024-05-31
authors: [martineckardt]
icon: Notebook
---

While transactions on ledgers in the analogue world were often authorized by hand-written signatures, that is not going to work for the adoption in blockchain. To utilize the concept of a ledger in the modern age, we leverage cryptography instead. 

import SignatureSchemes from "@/content/common/cryptography/signature-schemes.mdx"

import defaultMdxComponents from "fumadocs-ui/mdx";

<SignatureSchemes components={defaultMdxComponents}/>

# Origin of the EVM (/academy/customizing-evm/02-intro-to-evm/01-origin-of-evm)

---
title: Origin of the EVM
description: Learn about the origin of the Ethereum Virtual Machine.
updated: 2024-09-27
authors: [ashucoder9, owenwahlgren]
icon: BookOpen
---

The **Ethereum Virtual Machine (EVM)** is a fundamental component of Ethereum’s infrastructure, responsible for executing smart contracts across the network. The origins of the EVM can be traced back to the creation of the Ethereum blockchain itself, proposed in a whitepaper by **Vitalik Buterin** in late 2013.

Buterin and the founding Ethereum team envisioned a platform where developers could build **decentralized applications (dApps)** on a blockchain. To accomplish this, they needed a way to execute arbitrary, complex computations in a secure and decentralized manner. This is how the concept of the EVM was born.

The EVM, an integral part of the Ethereum ecosystem, operates as a **quasi-Turing complete machine**. This means it can run nearly any algorithm, given enough resources. It's isolated from the main network, providing a sandboxed environment for smart contract execution.

Following the publication of the whitepaper, the Ethereum project moved into development. The first live version of the Ethereum network, including the EVM, launched on **July 30, 2015**. The Ethereum blockchain was designed with the EVM at the protocol level, enabling users to create and execute smart contracts. These smart contracts are essentially programs that autonomously execute the terms of an agreement. They are written in high-level languages like **Solidity** or **Vyper**, which are then compiled down to EVM bytecode for execution on the EVM.

Since its creation, the EVM has become a crucial component of the Ethereum blockchain and has set a standard for other blockchain platforms that have adopted similar models for executing smart contracts. The advent of the EVM has undoubtedly revolutionized the blockchain world by introducing the concept of **programmable blockchains**.


# Accounts, Keys, and Addresses (/academy/customizing-evm/02-intro-to-evm/02-accounts-keys-address)

---
title: Accounts, Keys, and Addresses
description: Learn about Accounts, Keys, and Addresses in EVM.
updated: 2024-09-27
authors: [ashucoder9, owenwahlgrne]
icon: BookOpen
---

## Accounts

In the EVM, there are two types of accounts:

1. **Externally Owned Accounts (EOAs)**: These accounts are controlled by private keys and do not have associated code. They can send transactions by creating and signing them with their private keys. If you're an end user of Ethereum, you're likely using an EOA.

2. **Contract Accounts**: These accounts have associated code (smart contracts). Contract accounts can't initiate transactions on their own; instead, they only perform actions when instructed by an EOA. This could be as simple as a token transfer or a function call within a smart contract.

## Public and Private Keys

In Ethereum, as in many blockchain platforms, the **Elliptic Curve Digital Signature Algorithm (ECDSA)** is used to generate a pair of keys: a public key and a private key.

- The **private key** is a 32-byte number generated randomly.
- The **public key** is derived from the private key using elliptic curve cryptography. It is 64 bytes long, made up of two concatenated 32-byte coordinates.

## Addresses

An EVM address is derived from the public key through the following steps:

1. **Keccak-256 Hashing**: The public key is first passed through the Keccak-256 hashing function (the version of SHA-3 used by Ethereum). Keccak-256 outputs a 64-byte string, for example:
   `025ad33e2479a53b02dc0be66eb0ce272fc0f4358c57a8f0a442410c3d831a`

2. **Rightmost 20 bytes**: The resulting string is truncated to keep only the last 20 bytes. In hexadecimal, this means retaining the rightmost 40 hex digits (since two hex digits represent one byte), like so:
   `e66eb0ce272fc0f4358c57a8f0a442410c3d831a`

3. **Adding '0x'**: Finally, "0x" is prefixed to the address for a total of 42 characters. The "0x" indicates that the following characters represent a hexadecimal number, a common convention in Ethereum:
   `0xe66eb0ce272fc0f4358c57a8f0a442410c3d831a`

This process ensures that each Ethereum address uniquely corresponds to a public key. Since the address is a truncated hash of the public key, it's impossible to reverse-engineer the public key from the address.


# Transactions and Blocks (/academy/customizing-evm/02-intro-to-evm/03-transactons-and-blocks)

---
title: Transactions and Blocks
description: Learn about another fundamental aspect of the Ethereum ecosystem - Transactions and Blocks.
updated: 2024-09-27
authors: [ashucoder9, owenwahlgren]
icon: BookOpen
---

## Transactions

In the EVM, a transaction is the smallest unit of work that can be included in a block. It represents a **state transition**, modifying account data and transferring Ether across the network.

Transactions can either transfer Ether or invoke smart contracts. Each transaction includes the following components:

- **Nonce**: A unique value set by the sender to ensure the transaction is processed only once, preventing replay attacks.
- **Gas Price**: The amount the sender is willing to pay per unit of gas, typically measured in `nanoAvax` (1 `nAvax` = 1/(10^9) Avax). It consists of three parts:
  - **Base Gas Fee**: The minimum `nAvax` required per unit of gas.
  - **Maximum Priority Gas Fee**: Additional `nAvax` the sender is willing to pay on top of the base fee.
  - **Maximum Total Gas Fee**: The maximum `nAvax` the sender is willing to spend per unit of gas. If the sum of the base gas fee and the priority gas fee exceeds this amount, the gas price paid will be capped at the maximum total gas fee.
- **Gas Limit**: The maximum amount of gas units the sender is willing to pay for executing the transaction. If this limit is reached, the transaction fails, preventing indefinite execution.
- **To**: The recipient's Ethereum address or the target smart contract.
- **V, R, S**: Cryptographic data used to create the sender's signature.

## Blocks

A block in the EVM is a bundle of validated transactions, grouped together and linked to the previous block. Each block contains:

- **Block Number**: The index of the block, representing its position in a zero-indexed linked list.
- **Timestamp**: The time the block was mined.
- **Transactions Root**: The Merkle root of all transactions within the block.
- **Receipts Root**: The Merkle root of all transaction receipts.
- **State Root**: A hash of the entire Ethereum state after executing all transactions in the block.
- **Parent Hash**: The hash of the previous (parent) block.
- **Gas Limit**: The maximum gas all transactions in the block can consume.
- **Gas Used**: The total gas consumed by all transactions in the block.
- **Extra Data**: An optional field for including arbitrary data up to 32 bytes.
- **Validator**: The address of the node that proposed the block.


# Different Versions of EVM (/academy/customizing-evm/02-intro-to-evm/05-different-evm-versions)

---
title: Different Versions of EVM
description: Learn about the different versions of the Ethereum Virtual Machine in the Avalanche ecosystem.
updated: 2024-09-27
authors: [ashucoder9, owenwahlgren]
icon: BookOpen
---

## Geth

Geth (or [go-ethereum](https://github.com/ethereum/go-ethereum)) is the official implementation of an Ethereum client, written in the Go programming language. It is one of the original and most widely used Ethereum clients today. Geth handles transactions, deploys and executes smart contracts, and contains the Ethereum Virtual Machine.

## Coreth

[Coreth](https://github.com/ava-labs/coreth) is a fork of Geth maintained by Ava Labs. It implements the EVM for the C-Chain and has been adapted to work with Avalanche Consensus.

## Subnet-EVM

[Subnet-EVM](https://github.com/ava-labs/subnet-evm) is a fork of Coreth designed to facilitate launching customized EVM-based blockchains on an Avalanche L1. It differs from Coreth in the following ways:

- **Configurable Fees and Gas Limits**: Customizable fees and gas limits can be set in the genesis file.
- **Unified Subnet-EVM Hardfork**: All Avalanche hardforks are merged into a single "Subnet-EVM" hardfork.
- **Atomic Transactions and Shared Memory Removed**: Support for atomic transactions and shared memory has been removed.
- **Multicoin Contracts and State Removed**: Multicoin contracts and state tracking are no longer supported.

## Precompile-EVM

Precompile-EVM allows precompiles to be registered with Subnet-EVM without needing to fork the Subnet-EVM codebase. This simplifies common customizations to Subnet-EVM, making them more accessible and easier to maintain. It also streamlines updates for Subnet-EVM.


# Set Up Development Environment (/academy/customizing-evm/03-development-env-setup/00-intro)

---
title: Set Up Development Environment
description: Start by setting up your development environment.
updated: 2024-05-31
authors: [ashucoder9]
icon: Book
---

It's time to set up the development environment necessary for customizing the EVM! While the primary focus of this course is teaching you about precompiles, it's also crucial to configure a development environment that ensures a smooth and efficient workflow.

In this section, we will cover the following:

- Creating a GitHub repository for our customized EVM
- Setting up a default test account in your Core Wallet
- Exploring different types of development setups
- Choosing the setup for developing precompiles

Let's get started! 🚀


# Create Codespaces (/academy/customizing-evm/03-development-env-setup/02-create-codespaces)

---
title: Create Codespaces
description: Learn how to create GitHub Codespaces.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

## Open Precompile-EVM Repository in a Github Codespace

Open a Codespace on the [Precompile-EVM](https://github.com/ava-labs/precompile-evm/tree/avalanche-academy-start) Repository on the `avalanche-academy-start` branch by clicking the button below: 

[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://github.com/codespaces/new?hide_repo_select=true&ref=avalanche-academy-start&repo=605560683&machine=standardLinux32gb)

Next a window opens and the Codespace is built. This may take a few minutes.

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/customizing-evm/11-Z5CM89rf9qvVIENBpZF2wlKt3bALSq.png)

When the building is completed, you can access the Codespace through the browser IDE.

## Closing Codespaces

The codespace time out after 30 minutes of inactivity by default. So if you are not too worried about the 30 hour/month limit, just close the window or the tab. Alternatively, you can open the command prompt (Cmd + Shift + P) and issue the command: **Stop Current Codespace**.

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/customizing-evm/12-rESxJrPr97KL08SWhP30BMEjHN7UAS.png)

## Reopen Codespaces

You can see your Codespaces on https://github.com/codespaces/. There you can stop them, reopen them and delete them.

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/customizing-evm/13-BHHk6FjT3nu1ATITEUdeJhezVCpd6G.png)

# Codespace in VS Code (/academy/customizing-evm/03-development-env-setup/03-codespace-in-vscode)

---
title: Codespace in VS Code
description: Learn how to setup GitHub Codespaces.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

## Switch from Browser to VS Code

You can switch any time from the browser IDE to Visual Studio Code:

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/customizing-evm/14-aVKH0qkDNUpTwxRaB1qSFNuSk55Mfu.png)

The first time you switch, you will be asked to install the [Codespaces extension](https://marketplace.visualstudio.com/items?itemName=GitHub.codespaces) and connect VS Code to you GitHub account, if it is not already connceted.

# Your Own EVM Blockchain (/academy/customizing-evm/04-your-evm-blockchain/00-intro)

---
title: Your Own EVM Blockchain
description: Learn how to spin up your own EVM blockchain.
updated: 2024-09-27
authors: [ashucoder9, owenwahlgren]
icon: Book
---

In this part of the course, we'll explore how to run your own Avalanche L1 with a custom EVM. Running your own EVM allows you to address specific use cases, showcasing one of the key advantages of multi-chain systems over monolithic blockchains.

## Topics

We’ll cover the following topics:

- **Avalanche CLI**: Learn how to configure and launch an Avalanche L1 using the Avalanche CLI.
- **Token Transfer**: Explore how to perform token transfers with Foundry.

This hands-on exercise will solidify your knowledge and allow you to observe how customizations impact EVM performance.

## Learning Objective

By the end of this section, you’ll have the skills to effectively run your own Avalanche L1 with a custom EVM blockchain, empowering you to start building your blockchain projects!


# Avalanche CLI (/academy/customizing-evm/04-your-evm-blockchain/01-avalanche-cli)

---
title: Avalanche CLI
description: Learn about the Avalanche Command-Line Interface tooling.
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

## What is the Avalanche CLI?

The Avalanche CLI is a command-line tool that gives developers comprehensive access to Avalanche's functionalities, making it easier to build and test independent blockchains.

Each Avalanche network includes the Primary Network, which consists of the Contract (C), Platform (P), and Exchange (X) chains. It's important to note that "Primary Network" refers to a special Avalanche L1 rather than a distinct, standalone network.

Your local network operates independently from both the Mainnet and Fuji Testnet. You can even run an Avalanche L1 offline. Local Avalanche networks support, but are not limited to, the following commands:

- **Start and Stop a Network**: Easily start or stop a local network.
- **Health Check**: Check the health status of each node in the network.
- **Create Blockchains**: Spin up new blockchains with custom parameters.

Managing a local network with multiple nodes can be complex, but the Avalanche CLI simplifies the process with user-friendly commands.

## Usage

The Precompile-EVM repository comes preloaded with the Avalanche CLI and Foundry, so you don’t need to install additional tools when working within Codespaces. Just use the terminal in your Codespace to run Avalanche CLI commands and start building.


# Create Your Blockchain (/academy/customizing-evm/04-your-evm-blockchain/02-create-your-blockchain)

---
title: Create Your Blockchain
description: Learn how to use Avalanche-CLI to spin up your own EVM blockchain.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

import CreateDefaultBlockchain from "@/content/common/avalanche-starter-kit/create-default-blockchain.mdx";

import defaultMdxComponents from "fumadocs-ui/mdx";

<CreateDefaultBlockchain components={defaultMdxComponents}/>

# Sending Tokens (/academy/customizing-evm/04-your-evm-blockchain/03-sending-tokens)

---
title: Sending Tokens
description: Learn how to send tokens on your EVM blockchain.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

To ensure that the blockchain is up and running, let's perform a simple token transfer to a random address, `0x321f6B73b6dFdE5C73731C39Fd9C89c7788D5EBc`, using Foundry:

```bash
cast send --rpc-url myblockchain --private-key $PK 0x321f6B73b6dFdE5C73731C39Fd9C89c7788D5EBc --value 1ether
```
To verify if the transaction was successful, check the balance of the address with the following command:


```bash
cast balance --rpc-url myblockchain 0x321f6B73b6dFdE5C73731C39Fd9C89c7788D5EBc
```
```bash
1000000000000000000
```
You should see that the balance of the address `0x321f6B73b6dFdE5C73731C39Fd9C89c7788D5EBc` is now 1 (1 * 10^18).


Congratulations! You have successfully sent tokens on your EVM blockchain. 🎉




# EVM Configuration (/academy/customizing-evm/05-genesis-configuration/00-vm-configuration)

---
title: EVM Configuration
description: Learn about Virtual Machine configuration.
updated: 2024-09-27
authors: [ashucoder9]
icon: Book
---

In this part of the course, we'll explore how to optimize your EVM through chain configuration, tailoring it to fit specific use cases. Customizing EVM configurations is a key advantage of multi-chain systems.

## Exercise

In this section, you won’t need to write any Go code. Instead, we’ll adjust values in the JSON file of the genesis block.

## Topics

We will cover the following topics:

- **Genesis Block**: The foundation of any blockchain. We’ll review its components and how to customize its properties.
- **Fee Configuration**: Learn how to balance validator incentives with user affordability. This is crucial for managing network congestion and discouraging wasteful transactions on public networks.
- **Initial Token Allocation**: Understand how to define the initial token distribution in your custom EVM, setting your network up for success.
- **Preinstalled Precompiles**: Discover how to configure preinstalled precompiles to leverage features like restricting who can issue transactions or deploy contracts on your chain.

Finally, we’ll demonstrate how to run a local EVM with a custom Genesis Block. This exercise will solidify your understanding and allow you to observe the performance impact of your EVM customizations.

## Learning Objective

By the end of this section, you'll be able to effectively customize the EVM in Avalanche, unlocking new possibilities for your blockchain projects. Let’s dive into EVM customization and chain configuration together!


# Genesis Block (/academy/customizing-evm/05-genesis-configuration/01-genesis-block)

---
title: Genesis Block
description: Learn about the Genesis Block.
updated: 2024-09-27
authors: [ashucoder9]
icon: BookOpen
---

## Background

Each blockchain begins with a genesis state when it is created. For instance, the Ethereum mainnet genesis block included the addresses and balances from the Ethereum pre-sale, marking the initial distribution of ether.

For Subnet-EVM and Precompile-EVM, the genesis block contains additional parameters that allow us to configure the behavior of our customized EVM to meet specific requirements. Since each blockchain has its own genesis block, you can create two blockchains with the same VM but different genesis blocks.

## Format

Here’s an example of a genesis block:

```json
{
  "config": {
    "chainId": 43214,
    "homesteadBlock": 0,
    "eip150Block": 0,
    "eip150Hash": "0x2086799aeebeae135c246c65021c82b4e15a2c451340993aacfd2751886514f0",
    "eip155Block": 0,
    "eip158Block": 0,
    "byzantiumBlock": 0,
    "constantinopleBlock": 0,
    "petersburgBlock": 0,
    "istanbulBlock": 0,
    "muirGlacierBlock": 0,
    "subnetEVMTimestamp": 0,
    "feeConfig": {
      "gasLimit": 15000000,
      "minBaseFee": 25000000000,
      "targetGas": 15000000,
      "baseFeeChangeDenominator": 36,
      "minBlockGasCost": 0,
      "maxBlockGasCost": 1000000,
      "targetBlockRate": 2,
      "blockGasCostStep": 200000
    },
    "allowFeeRecipients": false, 
    "txAllowListConfig": {
      "blockTimestamp": 0,
      "adminAddresses": [
        "0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC"
      ]
    }
  },
  "alloc": {
    "8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC": {
      "balance": "0x295BE96E64066972000000"
    }
  },
  "nonce": "0x0",
  "timestamp": "0x0",
  "extraData": "0x00",
  "gasLimit": "0xe4e1c0",
  "difficulty": "0x0",
  "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
  "coinbase": "0x0000000000000000000000000000000000000000",
  "number": "0x0",
  "gasUsed": "0x0",
  "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000"
}
```
We will explore the relevant configurable parameters in the upcoming activities. Some parameters (e.g., `eip150Block`, `byzantiumBlock`) are omitted here as they are not relevant for most use cases.

This version provides a clean and concise explanation of the genesis block and its structure, keeping the focus on what's essential.


# Create Your Genesis File (/academy/customizing-evm/05-genesis-configuration/02-create-your-genesis)

---
title: Create Your Genesis File
description: Learn how to create your own genesis file.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

import { Callout } from 'fumadocs-ui/components/callout';

## Create File

In your Precompile-EVM project, create a file called `evm-configuration-genesis.json` in the directory `tests/precompile/genesis/` and open it. You can use the command below as a shortcut to open the file in VSCode:

```bash
code ./tests/precompile/genesis/evm-configuration-genesis.json
```

## Fill with template

Paste the following template in the new file:

```json
{
    "config": {
      "chainId":  <your-chain-id>,
      "homesteadBlock": 0,
      "eip150Block": 0,
      "eip150Hash": "0x2086799aeebeae135c246c65021c82b4e15a2c451340993aacfd2751886514f0",
      "eip155Block": 0,
      "eip158Block": 0,
      "byzantiumBlock": 0,
      "constantinopleBlock": 0,
      "petersburgBlock": 0,
      "istanbulBlock": 0,
      "muirGlacierBlock": 0,
      "subnetEVMTimestamp": 0,
      "feeConfig": {
        "gasLimit": <your-gas-limit>,
        "minBaseFee": <your-min-base-fee>,
        "targetGas": <your-target-gas>,
        "baseFeeChangeDenominator": 36,
        "minBlockGasCost": <your-min-block-gas-cost>,
        "maxBlockGasCost": <your-max-block-gas-cost>,
        "targetBlockRate": <your-target-block-rate>,
        "blockGasCostStep": <your-block-gas-cost-step>
      },
      "allowFeeRecipients": false
    },
    "alloc": {
      "<your-test-wallet-address>": {
        "balance": "<your-initial-balance-converted-to-hex>"
      }
    },
    "nonce": "0x0",
    "timestamp": "0x0",
    "extraData": "0x00",
    "gasLimit": <your-gas-limit>,
    "difficulty": "0x0",
    "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "coinbase": "0x0000000000000000000000000000000000000000",
    "number": "0x0",
    "gasUsed": "0x0",
    "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000"
  }
```

<Callout title="Warning about gasLimit" type="warn">
If you do decide to set your own gasLimit, please set all gasLimit keys equal to the same value! 

If you set the 'gasLimit' keys to different values, you will still be able to deploy a blockchain, but it will halt during initialization!
</Callout>

# Setup Your ChainID (/academy/customizing-evm/05-genesis-configuration/03-setup-chainid)

---
title: Setup Your ChainID
description: Learn how to setup ChainID for your own blockchain.
updated: 2024-09-27
authors: [ashucoder9]
icon: Terminal
---

## What is ChainID?

The `ChainID` of an EVM blockchain is a unique identifier that distinguishes Ethereum chains from one another. Introduced in Ethereum Improvement Proposal (EIP) 155, this mechanism prevents transaction replay attacks, which could occur when the same transaction is valid across multiple chains.

## Setting the ChainID

To set the `ChainID` for your blockchain, configure it in the `genesis` JSON file at the top level with the value `99999`.

If you wish to use a custom `ChainID`, check [chainlist.org](https://chainlist.org) to ensure your proposed `ChainID` is not in use by any other network. Be sure to cross-check with Testnets as well!

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/customizing-evm/28-LNcOo16PhvaDVIb7crVasGVKvs8kR6.png)


# Gas Fees and Gas Limit (/academy/customizing-evm/05-genesis-configuration/04-gas-fees-and-limit)

---
title: Gas Fees and Gas Limit
description: Learn about Gas Fees and Gas Limit in the context of the EVM.
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

## Background

In the context of the EVM, gas is a unit that measures the computational effort required to execute specific operations. Each operation performed by a contract or transaction on an EVM chain consumes a certain number of gas units based on its complexity. Operations that require more computational resources cost more gas. The EVM calculates the required gas units automatically, and developers are encouraged to optimize their contract code to reduce gas consumption.

The cost of executing a transaction is determined by the gas units consumed and the gas price, calculated as follows:

```
Transaction Cost = Gas Units * Gas Price
```

For EVM Avalanche L1s, gas payment can be configured to better suit the use case of the Avalanche L1. This means that the Avalanche L1 design can decide whether the gas fees are burned, paid to incentivize validators, or used for any other custom behavior.

## Purpose

The primary goal of setting and enforcing computational costs via gas is to prevent spam and abuse on the network. By requiring users to pay for each computational step, the network deters malicious actors from launching denial-of-service (DoS) attacks, which involve flooding the network with spurious transactions. Essentially, the gas system serves as a deterrent against such attacks.

## Gas Price and Gas Limit

Each transaction specifies the gas price and gas limit:

**`Gas Price`:** The gas price is the amount of the Avalanche L1's native token that the sender is willing to spend per unit of gas, typically denoted in `gwei` (1 native token = 1,000,000,000 `gwei`). A well-designed gas mechanism adapts the gas price according to network activity to protect the network from spam.

**`Gas Limit`:** The gas limit is the maximum amount of gas the sender is willing to use for the transaction. It was introduced to prevent infinite loops in contract execution. In a Turing-complete language like Solidity (the main programming language in the EVM), it is possible to write a contract with an infinite loop, either accidentally or intentionally. While an infinite loop might be a nuisance in traditional computing, it could cause significant issues in a decentralized blockchain by causing the network to hang as it attempts to process a never-ending transaction. The gas limit prevents this by halting execution once the gas consumed reaches the limit.

If a transaction exceeds the gas limit, it fails, but the fee amounting to the gas limit is still paid by the sender.


# Gas Fees Configuration (/academy/customizing-evm/05-genesis-configuration/05-gas-fee-configuration)

---
title: Gas Fees Configuration
description: Learn how to configure gas fees in your EVM blockchain.
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

## Configuration Format

The fees are configured in the `chainConfig` in the `feeConfig` field:

```json
{
  "config": {
    // ...
    "feeConfig": { // [!code highlight]
      "gasLimit": 15000000,
      "minBaseFee": 25000000000,
      "targetGas": 15000000,
      "baseFeeChangeDenominator": 36,
      "minBlockGasCost": 0,
      "maxBlockGasCost": 1000000,
      "targetBlockRate": 2,
      "blockGasCostStep": 200000
    },
    "allowFeeRecipients": false
  },
  "alloc": {
    // ...
  },
  // ...
    
  "gasLimit": 0xe4e1c0,
  // ...
}
```

## Gas Configuration Parameters

### `gasLimit`

Sets the maximum amount of gas consumed per block. This restriction caps the computational capacity of a single block and thereby limits the maximum gas usage allowed for any single transaction. For reference, the C-Chain value is set to 15,000,000.

You might notice that the `gasLimit` field appears twice. This is because Avalanche introduced its own fee configuration under the `feeConfig` key while maintaining compatibility with the standard EVM configuration. Ensure that both fields have the same decimal and hexadecimal equivalent values.

### `targetBlockRate`

Specifies the target rate of block production in seconds. For instance, a target of 2 aims to produce a block every 2 seconds. If blocks are produced faster than this rate, it signals that more blocks are being issued to the network than anticipated, leading to an increase in base fees. For C-Chain, this value is set to 2.

### `minBaseFee`

Establishes a lower bound on the EIP-1559 base fee for a block. This minimum base fee effectively sets the minimum gas price for any transaction included in that block.

### `targetGas`

Indicates the targeted amount of gas (including block gas cost) to be consumed within a rolling 10-second window. The dynamic fee algorithm adjusts the base fee proportionally based on how actual network activity compares to this target. If network activity exceeds the `targetGas`, the base fee is increased accordingly.

### `baseFeeChangeDenominator`

Determines how much to adjust the base fee based on the difference between actual and target utilization. A larger denominator results in a slower-changing base fee, while a smaller denominator allows for quicker adjustments. For C-Chain, this value is set to 36, meaning the base fee changes by a factor of 1/36 of the parent block's base fee.

### `minBlockGasCost`

Sets the minimum amount of gas charged for the production of a block. In the C-Chain, this value is set to 0.

### `maxBlockGasCost`

Specifies the maximum amount of gas charged for the production of a block.

### `blockGasCostStep`

Defines how much to increase or decrease the block gas cost based on the time elapsed since the previous block. If a block is produced at the target rate, the block gas cost remains the same as the parent block. If the production rate deviates from the target, the block gas cost is adjusted by the `blockGasCostStep` value for each second faster or slower than the target block rate.


# Configure Gas Fees (/academy/customizing-evm/05-genesis-configuration/06-configuring-gas-fees)

---
title: Configure Gas Fees
description: Learn how to configure gas fees in your EVM blockchain.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

## Benchmarks

You can take these numbers below as a benchmark:

```json
"feeConfig": {
        "gasLimit": 15000000,
        "minBaseFee": 25000000000,
        "targetGas": 15000000,
        "baseFeeChangeDenominator": 36,
        "minBlockGasCost": 0,
        "maxBlockGasCost": 1000000,
        "targetBlockRate": 2,
        "blockGasCostStep": 200000
      },
        
"gasLimit": 0xe4e1c0,
```

## Choose Your Own Values

### `gasLimit`

As previously discussed, the `gasLimit` acts as a restriction on the amount of computation that can be executed in a single block, and hence caps the maximum transaction size, as the entire transaction needs to be processed within the same block.

Your choice of `gasLimit` values should depend on the specific use case and computational demands of your application. Here are some considerations:

**High Throughput:** If your application requires a high volume of transactions, you might want to allow for more transactions (i.e., more computation) to be packed into a single block. This increases the block capacity and enables handling a higher transaction load.

**Heavy Transactions:** Transactions that involve deploying large contracts or executing complex operations tend to consume more gas. If your application involves such operations, ensure that your `gasLimit` accommodates the full execution of these heavy transactions or contract deployments.

Be cautious with setting excessively high `gasLimit` values. Larger computational allowances per block can translate to increased hardware requirements for your blockchain. Therefore, align the `gasLimit` with your use case and infrastructure requirements for validators. Avoid setting an unusually large value "just in case." For reference, consider that a typical native token transaction costs around 21,000 gas units, and the C-Chain `gasLimit` is set to 15,000,000.

### Gas Price Parameters

The following parameters affect the gas pricing and dynamic adjustments in your network:

- **`minBaseFee`**: Sets the minimum base fee per unit of gas, establishing the lower bound for transaction costs in a block.
- **`targetGas`**: Defines the target amount of gas to be consumed within a rolling 10-second window. Adjust this based on the expected network activity under normal conditions.
- **`baseFeeChangeDenominator`**: Controls how quickly the base fee adjusts in response to fluctuations in gas usage. A smaller denominator allows for faster adjustments.
- **`minBlockGasCost`**: Specifies the minimum gas cost for producing a block.
- **`maxBlockGasCost`**: Sets the maximum gas cost for producing a block.
- **`targetBlockRate`**: Determines the desired block production rate in seconds. Choose this based on your expected block issuance frequency.
- **`blockGasCostStep`**: Adjusts the block gas cost based on the deviation from the target block rate. A higher step value increases the block gas cost more rapidly with deviations.

These parameters should be selected based on the stability of gas usage in your network. Since gas fees are crucial for protecting against spam and abuse, carefully consider how these parameters will adapt to changes in network activity. The goal is to dynamically adjust transaction costs during irregular activity periods while maintaining stability under normal conditions.


# Initial Token Allocation (/academy/customizing-evm/05-genesis-configuration/07-initial-token-allocation)

---
title: Initial Token Allocation
description: Learn about the initial token allocation and configure in your EVM blockchain.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

import { Callout } from 'fumadocs-ui/components/callout';

## Background

`Alloc` defines the initial balances of addresses at the time of chain creation. This field should be modified according to the specific requirements of each chain.

If no genesis allocation is provided, you won't be able to interact with your new chain, as all transactions require a fee to be paid from the sender's balance. Without an initial allocation, there will be no funds available to cover transaction fees.

## Format

The `alloc` field expects key-value pairs. Keys must be valid addresses, and the balance field in each value can be either a hexadecimal or decimal number representing the initial balance of the address.

```json
{
  "config": {
    // ...
  },
  "alloc": { // [!code highlight]
    "8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC": {
      "balance": "0x295BE96E64066972000000" // 50,000,000 tokens
    }
  },
  // ...
}
```

Keys in the allocation are hex addresses without the canonical 0x prefix. Balances are denominated in `Wei` (10^18 `Wei` = 1 Whole Unit of the native token of the chain) and expressed as hex strings with the canonical 0x prefix. Use [this converter](https://www.rapidtables.com/convert/number/hex-to-decimal.html) for translating between decimal and hex numbers.

The default configuration for testing purposes allocates a significant number of tokens to the address `8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC`. 

The private key for this address (as defined in the `.devcontainer`) is: `56289e99c94b6912bfc12adc093c9b51124f0dc54ac7a766b2bc5ccf558d8027`.

<Callout title="Warning" type="warn"> Never use this address or private key for anything other than testing on a local test network. The private key is publicly known, and any real funds transferred to this address are likely to be stolen. </Callout>


## Configure

Allocate tokens to two addresses:

- The well-known test address `8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC`.
- Another test address that you have created (avoid using addresses associated with real funds).

```json
{
  "config": {
    // ...
  },
  "alloc": {
    "8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC": { // [!code highlight]
      "balance": "0x295BE96E64066972000000" // 50,000,000 tokens
    },
    "<your_address>": { // [!code highlight]
      "balance": "0x295BE96E64066972000000" // 50,000,000 tokens
    }
  },
  // ...
}

```

# Build and Run Custom Genesis EVM (/academy/customizing-evm/05-genesis-configuration/08-build-and-run-custom-genesis-blockchain)

---
title: Build and Run Custom Genesis EVM
description: Learn how to build and run your blockchain with custom genesis file.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

<Steps>
<Step>

### Build Your Precompile-EVM

There's a simple build script in the Precompile-EVM we can utilize to build. First, make sure you are in the root folder of you Precompile-EVM:

```bash
cd $GOPATH/src/github.com/ava-labs/precompile-evm
```

Then run the command to initiate the build script:

```bash
./scripts/build.sh
```

</Step>
<Step>

### Create your blockchain configuration

You can run your Precompile-EVM by using the Avalanche CLI.

First, create the configuration for your blockchain:

```bash
avalanche blockchain create myblockchain \
 --custom \
 --vm $VM_PATH \
 --genesis "./.devcontainer/genesis-example.json" \
 --force \
 --sovereign=false \
 --evm-token "TOK" \
 --warp \
 --icm
```

</Step>
<Step>

### Launch L1 with you customized EVM

```bash
avalanche blockchain deploy myblockchain --local
```

After around 1 minute, the blockchain should have been created, and additional output will appear in
the terminal. You'll also see the RPC URL of your blockchain in the terminal.

</Step>
</Steps>



# What are Precompiles? (/academy/customizing-evm/06-precompiles/01-what-are-precompiles)

---
title: What are Precompiles?
description: Learn about Precompiled Smart Contracts in EVM.
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

Precompiled contracts allow the execution of code written in the low-level programming language Go from the EVM, which is significantly faster and more efficient than Solidity.

## Overview

If you're familiar with Python, you might recognize a similar concept where many Python functions and libraries are implemented in C for efficiency. Python developers can import these precompiled modules and call functions as if they were written in Python. The main difference is that the modules execute faster and more efficiently.

Precompiles can be called from a Solidity smart contract just like any other contract. The EVM maintains a list of reserved addresses mapped to precompiles. When a smart contract calls a function of a contract at one of these addresses, the EVM executes the precompile written in Go instead of the Solidity contract.

For example, if we map the address `0x030...01` to the SHA256 precompile that hashes its input using the SHA256 hash function, we can call the precompile as follows:

```solidity
// SPDX-License-Identifier: MIT

pragma solidity >=0.8.0;

interface ISHA256 {
    // Computes the SHA256 hash of value
    function hashWithSHA256(string memory value) external view returns(bytes32 hash);
}

contract MyContract {  
    ISHA256 mySHA256Precompile = ISHA256(0x0300000000000000000000000000000000000001);
    
    function doSomething() public {
        bytes32 hash = mySHA256Precompile.hashWithSHA256("test");
    }
}
```
In the code above, we call the precompile using the defined interface for our SHA256 precompile within `MyContract`.

Note that there is no implementation of the precompile in Solidity itself. This will only work if the precompile is implemented in Go and registered at the address `0x030...01`.

### PrecompiledContract Interface

When implementing a precompile in the Avalanche L1-EVM, the following function of the `StatefulPrecompiledContract` interface must be implemented in Go:

```go
// StatefulPrecompiledContract is the interface for executing a precompiled contract
type StatefulPrecompiledContract interface {
    // Run executes the precompiled contract.
    Run(accessibleState AccessibleState, 
        caller common.Address, 
        addr common.Address, 
        input []byte, 
        suppliedGas uint64, 
        readOnly bool) 
        (ret []byte, remainingGas uint64, err error)
}
```

We will cover the meaning of "stateful" and the first parameter `accessibleState` later. For now, let's focus on the function that specifies the logic of our precompile, which provides access to the following data:

- caller: The address of the account that called the precompile.
- addr: The address of the precompile being called.
- input: All inputs encoded in a byte array.
- suppliedGas: The amount of gas supplied for the precompile call.
- readOnly: A boolean flag indicating if the interaction is only reading or modifying the state.

The precompile implementation must return the following values:

- ret: All return values encoded in a byte array.
- remainingGas: The amount of gas remaining after execution.
- err: If an error occurs, return it. Otherwise, return nil.

# Why Precompiles? (/academy/customizing-evm/06-precompiles/02-why-precompiles)

---
title: Why Precompiles?
description: Learn about why you should utilize Precompiles in your smart contracts.
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

Adding precompiles to the EVM offers several significant advantages, which we will outline in this chapter.

## Performance Optimization

Precompiles primarily optimize the performance of specific computations. Introducing a new precompile can greatly reduce the computational resources required for certain tasks, thereby enhancing the performance of smart contracts and decentralized applications (DApps) that rely on these tasks.

For instance, the SHA256 hash function (0x02) and the RIPEMD160 hash function (0x03) serve as examples of precompiles that significantly boost performance. Implementing these functions within a smart contract would be computationally expensive and slow, whereas as precompiles, they execute quickly and efficiently.

## Security

Incorporating a function as a precompile allows developers to leverage libraries that have been thoroughly reviewed and audited, thus reducing the risk of bugs and vulnerabilities, which enhances overall security.

For example, the ModExp (0x05) precompile safely performs modular exponentiation, a complex mathematical operation utilized in various cryptographic functions.

## Access to Go Libraries

Precompiles are implemented in Go, allowing access to the rich ecosystem of existing Go libraries. This access eliminates the need for reimplementation, which can be labor-intensive and carries the risk of introducing bugs during the translation from Go to Solidity.

Consider the implementation of the SHA256 hash algorithm to understand the complexity involved in reimplementing it in Solidity.

## Gas Efficiency

Introducing a new precompile to the EVM can enhance gas efficiency for specific computations, thereby lowering execution costs. This makes it feasible to incorporate more complex operations into smart contracts, expanding their functionality without significantly increasing transaction costs.

The identity precompile (0x04), which copies and returns input data, exemplifies this. Though simple, it provides gas efficiency by being faster and cheaper than implementing the same functionality in a standard contract.

## Advanced Features and Functionality

By adding new precompiles to the EVM, developers can introduce advanced features and functionalities, such as complex mathematical calculations, advanced cryptographic operations, and new data structures. This can unlock new possibilities for DApps and smart contracts, enabling them to execute tasks that would otherwise be too computationally demanding or technically challenging.

Precompiles for elliptic curve operations, such as ecadd (0x06), ecmul (0x07), and ecpairing (0x08), enable advanced cryptographic functionality within EVM smart contracts. These precompiles are crucial for implementing zk-SNARKs, a form of zero-knowledge proof, in Ethereum.

## Interoperability

Certain precompiles can enhance the interoperability of the EVM with other blockchains or systems. For instance, precompiles can be utilized to verify proofs from other chains or perform operations compatible with different cryptographic standards.

The BLS12-381 elliptic curve operations precompiles (0x0a through 0x13, added in the Istanbul upgrade) improve EVM interoperability by allowing operations that are compatible with the BLS signature scheme, potentially facilitating inter-blockchain communication.


# Interact with a Precompile (/academy/customizing-evm/06-precompiles/03-interact-wtih-precompile)

---
title: Interact with a Precompile
description: Learn about why you should utilize Precompiles in your smart contracts.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

So let's get to it and interact with a precompile on the C-Chain of your local network. The SHA256 precompile is already available on the C-Chain.

## Call Precompile from Foundry

In this example, we will call the SHA256 precompile to generate hash of the input string.

**Precompile Address:** `0x0000000000000000000000000000000000000002`

```bash 
cast call --rpc-url local-c --private-key $PK 0x0000000000000000000000000000000000000002 "run(string)(bytes32)" "test"
```

You should see a bytes32 hash of the input string `test` as the output. 

```bash
0xa770b926e13a31fb823282e9473fd1da9e85afe23690336770c490986ef1b1fc
```

# Overview (/academy/customizing-evm/07-hash-function-precompile/00-intro)

---
title: Overview
description: Learn how to create a Hash Function Precompile.
updated: 2024-05-31
authors: [ashucoder9]
icon: Book
---
import {Step, Steps} from 'fumadocs-ui/components/steps';

## What We're Building

In this section, we'll create a precompile for the MD5 hash function. By utilizing the existing Go library for this hash function, we can avoid reimplementing the algorithm in Solidity and take advantage of Go's superior efficiency.

<Accordions>
<Accordion title="What is a Hash Function?">

A hash function is a special type of function that takes input data of any size (such as a letter, a word, the text of a book, or even all combined texts available on the internet) and converts it into a fixed-size output. This output, known as a hash value, represents the original data. The process is often referred to as "hashing."

Hash functions possess several key properties:

- **Deterministic**: Given the same input, a hash function will always produce the same output. For instance, hashing the word "apple" a thousand times will yield the same hash value each time.
- **Fixed Size**: Regardless of the input data size—whether it's a single character or an entire novel—the hash function always produces an output (the hash value) of a consistent length.
- **Fast Computation**: Hash functions are designed to be quick and efficient, returning a hash value with minimal computational resources and time.
- **Preimage Resistance**: It's computationally infeasible to retrieve the original input data from the hash value alone. This property is especially crucial in cryptographic hash functions for data security.
- **Avalanche Effect**: A small change to the input should cause significant changes in the output, making the new hash value appear uncorrelated with the old one. For example, hashing "apple" and "Apple" should produce completely different hash values.
- **Collision Resistance**: It is highly unlikely for two different pieces of input data to yield the same hash value. However, due to the limited length of hash values, collisions are theoretically possible. A good hash function minimizes the occurrence of such collisions.

Hash functions are utilized in various applications across computer science, including data retrieval, data integrity verification, password storage, and in blockchain technology for cryptocurrencies like Bitcoin.

</Accordion>
</Accordions>

## Reference Implementation

To aid your understanding of building precompiles, we will compare each step with a reference example: a precompile for the SHA256 hash function. Both precompiles are quite similar, featuring a single function that returns the hashed value.

## Overview of Steps

Here's an overview of the steps involved:
<Steps>
<Step>
Create a Solidity interface for the precompile.
</Step>
<Step>
Generate the ABI.
</Step>
<Step>
Write the precompile code in Go.
</Step>
<Step>
Configure and register the precompile.
</Step>
<Step>
Build and run your customized EVM.
</Step>
<Step>
Connect Remix to your customized EVM and interact with the precompile.
</Step>
</Steps>
Let's get started!


# Create an MD5 Solidity Interface (/academy/customizing-evm/07-hash-function-precompile/01-create-solidity-interface)

---
title: Create an MD5 Solidity Interface
description: Learn how to create an MD5 Solidity Interface
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

The first step is defining the interface that will wrap the precompile implementation and that other contracts and users will interact with. In addition to declaring the way users can interact with our MD5 precompile, defining the MD5 interface will also allow us to utilize a generator script. A precompile consists of many files, and generating boilerplate Go files will make implementing the precompile much easier.

## SHA-256 Precompile Interface

Before defining the MD5 interface, we will first look at the interface of the very similar SHA-256 precompile. This reference implementation is included in the repository we have created earlier.

```solidity title="contracts/contracts/interfaces/ISHA256.sol"
// SPDX-License-Identifier: MIT

pragma solidity >=0.8.0;

interface ISHA256 {
    /// Compute the hash of value
    /// @param value the value to be hashed
    /// @return hash the hash of the value
    function hashWithSHA256(string memory value) external view returns(bytes32 hash);
    }
```

ISHA256 contains a single function `hashWithSHA256`. `hashWithSHA256` takes in a value of type string, which is the value which is to be hashed, and outputs a 32-byte hash.

## Creating the Solidity Interface For The MD5 Precompile

Now it's your turn to define a precompile interface!

Create the interface for the MD5 hash function. Start by going into the same directory where `ISHA256.sol` lives (`contracts/contracts/interfaces/`) and create a new file named `IMD5.sol`. Note that:

&rarr; MD5 returns a 16-byte hash instead of a 32-byte hash

&rarr; Make sure to name all parameters and return values

<Accordions>
<Accordion title="Solution">

```solidity title="contracts/contracts/interfaces/IMD5.sol"
// SPDX-License-Identifier: MIT

pragma solidity >=0.8.0;

interface IMD5 {
    function hashWithMD5(string memory value) external view returns (bytes16 hash);
}
```

</Accordion>
</Accordions>

## Generate the ABI

Now that we have an interface of our precompile, let's create an ABI of our Solidity interface. Open the integrated VS Code terminal (control + \`), and change to the `/contracts` directory.

```bash
cd contracts
```

Run the command to compile the solidity interface to the ABI:

```bash
npx solc@latest --abi ./contracts/interfaces/IMD5.sol -o ./abis --base-path . --include-path ./node_modules
```

Rename the file:

```bash
mv ./abis/contracts_interfaces_IMD5_sol_IMD5.abi ./abis/IMD5.abi
```

Now, you should have a file called `IMD5.abi` in the folder `/contracts/abis` with the following content:

```json
[
    {
        "inputs": [
            {
                "internalType": "string",
                "name": "value",
                "type": "string"
            }
        ],
        "name": "hashWithMD5",
        "outputs": [
            {
                "internalType": "bytes16",
                "name": "hash",
                "type": "bytes16"
            }
        ],
        "stateMutability": "view",
        "type": "function"
    }
]
```


# Generate the Precompile (/academy/customizing-evm/07-hash-function-precompile/02-generate-the-precompile)

---
title: Generate the Precompile
description: Learn how to generate your precompile.
updated: 2024-09-27
authors: [ashucoder9, owenwahlgren]
icon: Terminal
comments: true
---

import { File, Files, Folder } from 'fumadocs-ui/components/files';

In the last section, we created the ABI for our precompile contract. Now, we'll use the precompile generation script provided by the precompile-evm template to generate a boilerplate code in go for the precompile implementation that will be wrapped in the solidity interface we created in the previous step.

## Running the Generation Script

To start, go to the root directory of your precompile-evm project: 

```bash
cd ..
```

Now generate the files necessary for the precompile.

```bash
./scripts/generate_precompile.sh --abi ./contracts/abis/IMD5.abi --type Md5 --pkg md5 --out ./md5
```

Now you should have a new directory in your root directory called `md5`:

<Files>
  <File name="LICENSE" />
  <File name="README.md" />
  <Folder name="contracts">
    <File name="..." />
  </Folder>
  <File name="go.mod" />
  <File name="go.sum" />
  <Folder name="sha256">
    <File name="..." />
  </Folder>
  <Folder name="md5" defaultOpen>
    <File name="README.md" />
    <File name="config.go" />
    <File name="config_test.go" />
    <File name="contract.abi" />
    <File name="contract.go" />
    <File name="contract_test.go" />
    <File name="module.go" />
  </Folder>
  <Folder name="plugin">
    <File name="main.go" />
  </Folder>
  <Folder name="scripts">
    <File name="build.sh" />
    <File name="..." />
  </Folder>
  <Folder name="tests">
    <File name="..." />
  </Folder>
</Files>

### `contract.go`

For the rest of this chapter, we'll work with the `md5/contract.go` file. If you generated the Go files related to your precompile, `contract.go` should look like the code below.

Do not be intimidated if much of this code does not make sense to you. We'll cover the different parts and add some code to implement the logic of our MD5 precompile.

```go
// Code generated
// This file is a generated precompile contract config with stubbed abstract functions.
// The file is generated by a template. Please inspect every code and comment in this file before use.

package md5

import (
	"errors"
	"fmt"
	"math/big"

	"github.com/ava-labs/subnet-evm/accounts/abi"
	"github.com/ava-labs/subnet-evm/precompile/contract"
	"github.com/ava-labs/subnet-evm/vmerrs"

	_ "embed"

	"github.com/ethereum/go-ethereum/common"
)

const (
	// Gas costs for each function. These are set to 1 by default.
	// You should set a gas cost for each function in your contract.
	// Generally, you should not set gas costs very low as this may cause your network to be vulnerable to DoS attacks.
	// There are some predefined gas costs in contract/utils.go that you can use.
	HashWithMD5GasCost uint64 = 1 /* SET A GAS COST HERE */
)

// CUSTOM CODE STARTS HERE
// Reference imports to suppress errors from unused imports. This code and any unnecessary imports can be removed.
var (
	_ = abi.JSON
	_ = errors.New
	_ = big.NewInt
	_ = vmerrs.ErrOutOfGas
	_ = common.Big0
)

// Singleton StatefulPrecompiledContract and signatures.
var (

	// Md5RawABI contains the raw ABI of Md5 contract.
	//go:embed contract.abi
	Md5RawABI string

	Md5ABI = contract.ParseABI(Md5RawABI)

	Md5Precompile = createMd5Precompile()
)

// UnpackHashWithMD5Input attempts to unpack [input] into the string type argument
// assumes that [input] does not include selector (omits first 4 func signature bytes)
func UnpackHashWithMD5Input(input []byte) (string, error) {
	res, err := Md5ABI.UnpackInput("hashWithMD5", input)
	if err != nil {
		return "", err
	}
	unpacked := *abi.ConvertType(res[0], new(string)).(*string)
	return unpacked, nil
}

// PackHashWithMD5 packs [value] of type string into the appropriate arguments for hashWithMD5.
// the packed bytes include selector (first 4 func signature bytes).
// This function is mostly used for tests.
func PackHashWithMD5(value string) ([]byte, error) {
	return Md5ABI.Pack("hashWithMD5", value)
}

// PackHashWithMD5Output attempts to pack given hash of type [16]byte
// to conform the ABI outputs.
func PackHashWithMD5Output(hash [16]byte) ([]byte, error) {
	return Md5ABI.PackOutput("hashWithMD5", hash)
}

// UnpackHashWithMD5Output attempts to unpack given [output] into the [16]byte type output
// assumes that [output] does not include selector (omits first 4 func signature bytes)
func UnpackHashWithMD5Output(output []byte) ([16]byte, error) {
	res, err := Md5ABI.Unpack("hashWithMD5", output)
	if err != nil {
		return [16]byte{}, err
	}
	unpacked := *abi.ConvertType(res[0], new([16]byte)).(*[16]byte)
	return unpacked, nil
}

func hashWithMD5(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {
	if remainingGas, err = contract.DeductGas(suppliedGas, HashWithMD5GasCost); err != nil {
		return nil, 0, err
	}
	// attempts to unpack [input] into the arguments to the HashWithMD5Input.
	// Assumes that [input] does not include selector
	// You can use unpacked [inputStruct] variable in your code
	inputStruct, err := UnpackHashWithMD5Input(input)
	if err != nil {
		return nil, remainingGas, err
	}

	// CUSTOM CODE STARTS HERE
	_ = inputStruct // CUSTOM CODE OPERATES ON INPUT

	var output [16]byte // CUSTOM CODE FOR AN OUTPUT
	packedOutput, err := PackHashWithMD5Output(output)
	if err != nil {
		return nil, remainingGas, err
	}

	// Return the packed output and the remaining gas
	return packedOutput, remainingGas, nil
}

// createMd5Precompile returns a StatefulPrecompiledContract with getters and setters for the precompile.

func createMd5Precompile() contract.StatefulPrecompiledContract {
	var functions []*contract.StatefulPrecompileFunction

	abiFunctionMap := map[string]contract.RunStatefulPrecompileFunc{
		"hashWithMD5": hashWithMD5,
	}

	for name, function := range abiFunctionMap {
		method, ok := Md5ABI.Methods[name]
		if !ok {
			panic(fmt.Errorf("given method (%s) does not exist in the ABI", name))
		}
		functions = append(functions, contract.NewStatefulPrecompileFunction(method.ID, function))
	}
	// Construct the contract with no fallback function.
	statefulContract, err := contract.NewStatefulPrecompileContract(nil, functions)
	if err != nil {
		panic(err)
	}
	return statefulContract
}
```


# Packing and Unpacking (/academy/customizing-evm/07-hash-function-precompile/03-unpack-input-pack-output)

---
title: Packing and Unpacking
description: Learn how to unpack inputs and pack outputs.
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

In this first segment of examining the `contract.go` file generated for us, we will go over the packing and unpacking functions in this file.   

## The Notion of Packing

Those eager to implement the MD5 algorithm might be wondering why we're discussing packing. However, there is good reason to discuss packing, and it comes down to the specification of the `staticcall` function in Solidity.

We begin by referring to the example of calling the SHA-256 precompiled contract:

```go
(bool ok, bytes memory out) = address(2).staticcall(abi.encode(numberToHash));
```

As seen above, the `staticcall` function accepts input in bytes format, generated by `abi.encode`, and returns a boolean value indicating success, along with a bytes format output.

Therefore, our precompiled contract should be designed to accept and return data in bytes format, involving the packing and unpacking of values. Since packing is a deterministic process, there's no concern about data corruption during translation. However, some preprocessing or postprocessing is necessary to ensure the contract functions correctly.

## Unpacking Inputs

In `contract.go`, the function `UnpackHashWithMd5Input` unpacks our data and converts it into a type relevant to us. It takes a byte array as an input and returns a Go string. We will look at more complex precompiles that have multiple functions that may take multiple inputs later.

```go
// UnpackHashWithMD5Input attempts to unpack [input] into the string type argument
// assumes that [input] does not include selector (omits first 4 func signature bytes)
func UnpackHashWithMD5Input(input []byte) (string, error) {
    res, err := Md5ABI.UnpackInput("hashWithMD5", input)
    if err != nil {
        return "", err
    }
    unpacked := *abi.ConvertType(res[0], new(string)).(*string)
    return unpacked, nil
}
```

## Packing Outputs

Ignoring `hashWithMD5` for now, note that whatever value `hashWithMD5` outputs, we will need to postprocess it (i.e. pack it). `PackHashWithMD5Output` does just this, taking in an input of type [16]byte and outputting a byte array which can be returned by `staticcall`.

```go
// PackHashWithMd5Output attempts to pack given hash of type [16]byte
// to conform the ABI outputs.
func PackHashWithMd5Output(hash [16]byte) ([]byte, error) {
    return Md5ABI.PackOutput("hash_with_md5", hash)
}
```

This may seem trivial, but if our Solidity interface defined our function to return a uint or string, the type of our input to this function would differ accordingly.


# Implement the Precompile (/academy/customizing-evm/07-hash-function-precompile/04-implementing-precompile)

---
title: Implement the Precompile
description: Learn how to implement the Precompile.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

Now, we'll implement the logic of the precompile in Go. We'll hash our string using the MD5 algorithm.

## SHA-256 Precompile Implementation

Before defining the logic of our MD5 precompile, let's look at the logic of the function `hashWithSHA256` (located in `sha256/contract.go`), which computes the SHA-256 hash of a string:

```go title="sha256/contract.go"
import (
    "crypto/sha256"
    //...
)

// ...

func hashWithSHA256(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {
    if remainingGas, err = contract.DeductGas(suppliedGas, HashWithSHA256GasCost); err != nil {
        return nil, 0, err
    }
    // attempts to unpack [input] into the arguments to the HashWithSHA256Input.
    // Assumes that [input] does not include selector
    // You can use unpacked [inputStruct] variable in your code
    inputStruct, err := UnpackHashWithSHA256Input(input)
    if err != nil {
        return nil, remainingGas, err
    }

    // CUSTOM CODE STARTS HERE
    _ = inputStruct // CUSTOM CODE OPERATES ON INPUT

    var output [32]byte // CUSTOM CODE FOR AN OUTPUT

    output = sha256.Sum256([]byte(inputStruct))
    
    packedOutput, err := PackHashWithSHA256Output(output)
    if err != nil {
        return nil, remainingGas, err
    }

    // Return the packed output and the remaining gas
    return packedOutput, remainingGas, nil
}
```

As you can see, we're performing the following steps:

- Line 1: Importing the sha256 function from the crypto library (at the top of the Go file)
- Line 15: Unpacking the input to the variable inputStruct. It doesn't make sense that the variable has Struct in its name, but you will see why it is done like this when we have multiple inputs in a later example
- Line 24: Calling the sha256 function and assign its result to the output variable
- Line 26: Packing the output into a byte array
- Line 32: Returning the packed output, the remaining gas and nil, since no error has occurred

## Implementing the MD5 Precompile in `contract.go`

Go ahead and implement the `md5/contract.go` for the MD5 precompile. You should only have to write a few lines of code. If you're unsure which function to use, the following documentation might help: [Go Documentation Crypto/md5](https://pkg.go.dev/crypto/md5#Sum)

<Accordions>
<Accordion title="Solution">

```go title="md5/contract.go"
import (
	"crypto/md5"
	// ...
)

// ...

func hashWithMD5(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {func hashWithMD5(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {
	if remainingGas, err = contract.DeductGas(suppliedGas, HashWithMD5GasCost); err != nil {
		return nil, 0, err
	}
	// attempts to unpack [input] into the arguments to the HashWithMD5Input.
	// Assumes that [input] does not include selector
	// You can use unpacked [inputStruct] variable in your code
	inputStruct, err := UnpackHashWithMD5Input(input)
	if err != nil {
		return nil, remainingGas, err
	}

	// CUSTOM CODE STARTS HERE
	_ = inputStruct // CUSTOM CODE OPERATES ON INPUT

	var output [16]byte // CUSTOM CODE FOR AN OUTPUT
	output = md5.Sum([]byte(inputStruct))

	packedOutput, err := PackHashWithMD5Output(output)
	if err != nil {
		return nil, remainingGas, err
	}

	// Return the packed output and the remaining gas
	return packedOutput, remainingGas, nil
}
```

To solve this task, we did the following things:

- Import the md5 function from the crypto library
- Unpack the input to a variable inputStruct (It does not make sense that the variable has Struct in its name, but you will see why it is done like this when we have multiple inputs in a later example)
- Call the md5 function and assign it's result to the output variable
- Pack the output into a byte array
- Return the packed output, the remaining gas and nil, since no error has occurred

</Accordion>
</Accordions>

# ConfigKey, ContractAddress, and Genesis (/academy/customizing-evm/07-hash-function-precompile/05-configkey-and-contractaddr)

---
title: ConfigKey, ContractAddress, and Genesis
description: Learn how to set ConfigKey, ContractAddress, and update the genesis configuration.
updated: 2024-09-27
authors: [ashucoder9, owenwahlgren]
icon: Terminal
---

## Config Key

The precompile config key is used to configure the precompile in the `chainConfig`. It's set in the `module.go` file of our precompile.

The generator chooses an initial value that should be sufficient for many cases. In our case:

```go title="md5/module.go"
// ConfigKey is the key used in json config files to specify this precompile precompileconfig.
// must be unique across all precompiles.
const ConfigKey = "md5Config"
```
This key is used for each precompile in the geneis configuration to set the activation timestamp of the precompile.

## Contract Address

Each precompile has a unique contract address we can use to call it. This is the address we used earlier to instantiate the precompile in our solidity code or in remix when we interacted with the sha256 precompile.

```go title="md5/module.go"
// ContractAddress is the defined address of the precompile contract.
// This should be unique across all precompile contracts.
// See precompile/registry/registry.go for registered precompile contracts and more information.

var ContractAddress = common.HexToAddress("{ASUITABLEHEXADDRESS}") // SET A SUITABLE HEX ADDRESS HERE
```

The `0x01` range is reserved for precompiles added by Ethereum.

The `0x02` range is reserved for precompiles provided by Avalanche.

The `0x03` range is reserved for custom precompiles.

Lets set our contract address to `0x0300000000000000000000000000000000000002`

```go title="md5/module.go"
var ContractAddress = common.HexToAddress("0x0300000000000000000000000000000000000002") // SET A SUITABLE HEX ADDRESS HERE
```

## Update Genesis Configuration
Now that the `ConfigKey` and `ContractAddress` are set, we need to update the genesis configuration to register the precompile.

```json title=".devcontainer/genesis-example.json"
{
  "config": {
    "chainId": 99999,
    "homesteadBlock": 0,
    "eip150Block": 0,
    "eip150Hash": "0x2086799aeebeae135c246c65021c82b4e15a2c451340993aacfd2751886514f0",
    "eip155Block": 0,
    "eip158Block": 0,
    "byzantiumBlock": 0,
    "constantinopleBlock": 0,
    "petersburgBlock": 0,
    "istanbulBlock": 0,
    "muirGlacierBlock": 0,
    "subnetEVMTimestamp": 0,
    "feeConfig": {
      "gasLimit": 20000000,
      "minBaseFee": 1000000000,
      "targetGas": 100000000,
      "baseFeeChangeDenominator": 48,
      "minBlockGasCost": 0,
      "maxBlockGasCost": 10000000,
      "targetBlockRate": 2,
      "blockGasCostStep": 500000
    },
    "sha256Config": {
      "blockTimestamp": 0
    },
    "md5Config": { // [!code highlight:3]
      "blockTimestamp": 0
    } 
  },
  "alloc": {
    "8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC": {
      "balance": "0x52B7D2DCC80CD2E4000000"
    }
  },
  "nonce": "0x0",
  "timestamp": "0x0",
  "extraData": "0x00",
  "gasLimit": "0x1312D00",
  "difficulty": "0x0",
  "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
  "coinbase": "0x0000000000000000000000000000000000000000",
  "number": "0x0",
  "gasUsed": "0x0",
  "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000"
}
```

# Register Your Precompile (/academy/customizing-evm/07-hash-function-precompile/06-register-precompile)

---
title: Register Your Precompile
description: Learn how to register your precompile.
updated: 2024-09-27
authors: [owenwahlgren]
icon: Terminal
---

The next step in developing our precompile is to **register it with precompile-evm**. Take a look at `plugin/main.go`. You should see the following file:

```go title="plugin/main.go"
// (c) 2019-2023, Ava Labs, Inc. All rights reserved.
// See the file LICENSE for licensing terms.

package main

import (
    "fmt"

    "github.com/ava-labs/avalanchego/version"
    "github.com/ava-labs/subnet-evm/plugin/evm"
    "github.com/ava-labs/subnet-evm/plugin/runner"

    // Each precompile generated by the precompilegen tool has a self-registering init function
    // that registers the precompile with the subnet-evm. Importing the precompile package here
    // will cause the precompile to be registered with the subnet-evm.
    // ADD YOUR PRECOMPILE HERE
    //_ "github.com/ava-labs/precompile-evm/{yourprecompilepkg}"
)

const Version = "v0.1.4"

func main() {
    versionString := fmt.Sprintf("Precompile-EVM/%s Avalanche L1-EVM/%s [AvalancheGo=%s, rpcchainvm=%d]", Version, evm.Version, version.Current, version.RPCChainVMProtocol)
    runner.Run(versionString)
}
```

As of now, we do not have any precompile registered. To reigster a precompile, simply import the precompile package in the `plugin/main.go` file.

```go title="plugin/main.go"
// (c) 2019-2023, Ava Labs, Inc. All rights reserved.
// See the file LICENSE for licensing terms.

package main

import (
    "fmt"

    "github.com/ava-labs/avalanchego/version"
    "github.com/ava-labs/subnet-evm/plugin/evm"
    "github.com/ava-labs/subnet-evm/plugin/runner"

    // Each precompile generated by the precompilegen tool has a self-registering init function
    // that registers the precompile with the subnet-evm. Importing the precompile package here
    // will cause the precompile to be registered with the subnet-evm.
    _ "github.com/ava-labs/precompile-evm/sha256"// [!code highlight:2]
    _ "github.com/ava-labs/precompile-evm/md5" 
)

const Version = "v0.1.4"

func main() {
    versionString := fmt.Sprintf("Precompile-EVM/%s Avalanche L1-EVM/%s [AvalancheGo=%s, rpcchainvm=%d]", Version, evm.Version, version.Current, version.RPCChainVMProtocol)
    runner.Run(versionString)
}
```


# Build and Run (/academy/customizing-evm/07-hash-function-precompile/07-build-and-run)

---
title: Build and Run
description: Learn how to build and run your custom VM on a local network.
updated: 2024-09-27
authors: [ashucoder9, owenwahlgren]
icon: Terminal
---

Time to build and run your customized EVM. Follow the steps below to build and run your custom VM on a local network.

<Steps>
<Step>

### Build Your Custom VM

There's a simple build script in the Precompile-EVM we can utilize to build. First, make sure you are in the root folder of you Precompile-EVM:

```bash
cd $GOPATH/src/github.com/ava-labs/precompile-evm
```

Then run the command to initiate the build script:

```bash
./scripts/build.sh
```

If you do not see any error, the build was successful.

</Step>
<Step>

### Create your blockchain configuration

You can run you customized Precompile-EVM by using the Avalanche CLI.

First, create the configuration for your blockchain with custom VM.

```bash
avalanche blockchain create myblockchain \
 --custom \
 --vm $VM_PATH \
 --genesis "./.devcontainer/genesis-example.json" \
 --force \
 --sovereign=false \
 --evm-token "TOK" \
 --warp \
 --icm
```

</Step>
<Step>

### Launch L1 with you customized EVM

Next, launch the Avalanche L1 with your custom VM:

```bash
avalanche blockchain deploy myblockchain --local
```

After around 1 minute the blockchain should have been created and some more output should appear in
the terminal. You'll also see the RPC URL of your blockchain in the terminal.
</Step>
</Steps>


# Interact with Precompile (/academy/customizing-evm/07-hash-function-precompile/08-interact-with-md5)

---
title: Interact with Precompile
description: Interact with the MD5 precompile we just deployed.
updated: 2024-08-27
authors: [owenwahlgren]
icon: Terminal
---

## Call Precompile from Foundry

Now we will call our MD5 precompile to generate a bytes16 hash of the input string.

**MD5 Precompile Address:** `0x0300000000000000000000000000000000000002`

```bash 
cast call --rpc-url myblockchain --private-key $PK 0x0300000000000000000000000000000000000002 "hashWithMD5(string)(bytes16)" "test"
```

You should see the bytes16 hash of the input string `test` as the output. 

```bash
0x098f6bcd4621d373cade4e832627b4f6
```

# Overview (/academy/customizing-evm/08-calculator-precompile/00-intro)

---
title: Overview
description: Learn how to create a Calculator precompile.
updated: 2024-05-31
authors: [ashucoder9]
icon: Book
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

## Reference Implementation

In this section, we will showcase how to build a more complex precompile that offers selected simple math operations. Our calculator will support the following operations:

1. Add two numbers and return the result (3 + 5 = 8)
2. Get the next two greater numbers (7 => 8, 9)
3. Repeat a string x times (4, b => bbbb)

This is somewhat odd calculator and real-life usability might not be the best, but as you will see in a bit the operations have been chosen to demonstrate some different scenarios we might face while building precompiles.

## What You Are Building

Similar to the Calculator precompile, you will be building a precompile called **CalculatorPlus** which contains the following mathematical functions:

- **Powers of Three**: takes in as input an integer base; returns the square, cube, and 4th power of the input
- **Modulo+**: takes in as input two arguments: the dividend and the divisor. Returns how many times the dividend fits in the divisor, and the remainder.
- **Simplify Fraction**: takes in two arguments: the numerator and the denominator. Returns the simplfied version of the fraction (if the denominator is 0, we return 0)

## Overview of Steps

Compared to the process before, we will now also add tests for our precompile. Here's a quick overview of the steps we're going to follow:
 
<Steps>
<Step>
Create a Solidity interface for the precompile
</Step>
<Step>
Generate the ABI
</Step>
<Step>
Write the precompile code in Go
</Step>
<Step>
Configure and register the precompile
</Step>
<Step>
Add and run tests
</Step>
<Step>
Build and run your customized EVM
</Step>
<Step>
Connect Remix to your customized EVM and interact with the precompile
</Step>
</Steps>

This tutorial will help you understand how to create more complex precompiles. Let's begin!


# Create Solidity Interface (/academy/customizing-evm/08-calculator-precompile/01-create-solidity-interface)

---
title: Create Solidity Interface
description: Learn how to create the Solidity interface for your calculator precompile.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

Just like in the MD5 section, we will start off by first demonstrating the Solidity interface for the Calculator precompile before guiding you on how to build the **CalculatorPlus** precompile. To start, let's take a look at the Calculator Solidity interface:

```solidity title="contracts/contracts/interfaces/ICalculator.sol"
// SPDX-License-Identifier: MIT

pragma solidity >=0.8.0;

interface ICalculator {
    function add(uint value1, uint value2) external view returns(uint result);

    function nextTwo(uint value1) external view returns(uint result1, uint result2);

    function repeat(uint times, string memory text) external view returns(string memory result);
}
```

With this in mind, let's define the CalculatorPlus Solidity interface. Your interface should have the following three functions:

1. `powOfThree`: takes in an unsigned integer base, and returns three unsigned integers named secondPow, thirdPow, fourthPow . 
2. `moduloPlus`: takes in unsigned integers dividend and divisor as input, and returns two unsigned integers named multiple and remainder .
3. `simplFrac`: takes in unsigned integers named numerator and denominator, and returns two unsigned integers named simplNum and simplDenom

<Accordions>
<Accordion title="Solution">

```solidity title="solidity/interfaces/ICalculatorPlus.sol"
// SPDX-License-Identifier: MIT

pragma solidity >=0.8.0;

interface ICalculatorPlus {
    function powOfThree(uint256 base) external view returns(uint256 secondPow, uint256 thirdPow, uint256 fourthPow);

    function moduloPlus(uint256 dividend, uint256 divisor) external view returns(uint256 multiple, uint256 remainder);

    function simplFrac(uint256 numerator, uint256 denominator) external view returns(uint256 simplNum, uint256 simplDenom);
}
```

</Accordion>
</Accordions>

## Generate the ABI

Now that we have an interface of our precompile, let's create an ABI of our Solidity interface. Open the terminal (control + \`), change to the `/contracts` directory and run the following command to compile the solidity interface to the ABI:

```bash
# Go to the upper contracts directory of your project
cd contracts

# Compile ICalculatorPlus.sol to ABI
npx solc@latest --abi ./contracts/interfaces/ICalculatorPlus.sol -o ./abis --base-path . --include-path ./node_modules

# Rename using this script or manually
mv ./abis/contracts_interfaces_ICalculatorPlus_sol_ICalculatorPlus.abi ./abis/ICalculatorPlus.abi
```

Now you should have a file called `ICalculatorPlus.abi` in the folder `/contracts/abis` with the following content:

```json title="/contracts/abis/ICalculatorPlus.abi"
[
  {
    "inputs": [
      {
        "internalType": "uint256",
        "name": "dividend",
        "type": "uint256"
      },
      {
        "internalType": "uint256",
        "name": "divisor",
        "type": "uint256"
      }
    ],
    "name": "moduloPlus",
    "outputs": [
      {
        "internalType": "uint256",
        "name": "multiple",
        "type": "uint256"
      },
      {
        "internalType": "uint256",
        "name": "remainder",
        "type": "uint256"
      }
    ],
    "stateMutability": "view",
    "type": "function"
  },
  {
    "inputs": [
      {
        "internalType": "uint256",
        "name": "base",
        "type": "uint256"
      }
    ],
    "name": "powOfThree",
    "outputs": [
      {
        "internalType": "uint256",
        "name": "secondPow",
        "type": "uint256"
      },
      {
        "internalType": "uint256",
        "name": "thirdPow",
        "type": "uint256"
      },
      {
        "internalType": "uint256",
        "name": "fourthPow",
        "type": "uint256"
      }
    ],
    "stateMutability": "view",
    "type": "function"
  },
  {
    "inputs": [
      {
        "internalType": "uint256",
        "name": "numerator",
        "type": "uint256"
      },
      {
        "internalType": "uint256",
        "name": "denominator",
        "type": "uint256"
      }
    ],
    "name": "simplFrac",
    "outputs": [
      {
        "internalType": "uint256",
        "name": "simplNum",
        "type": "uint256"
      },
      {
        "internalType": "uint256",
        "name": "simplDenom",
        "type": "uint256"
      }
    ],
    "stateMutability": "view",
    "type": "function"
  }
]
```


# Generating the Precompile (/academy/customizing-evm/08-calculator-precompile/02-generating-precompile)

---
title: Generating the Precompile
description: Learn how to generating the precompile
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

In this step, we will again utilize the precompile generation script to generate all the Go files based on the ABI for your calculator.

## Run Generation Script

Change to the root directory of your precompile-evm project and run the command to generate the go files:

```bash
# Change to root
cd ..

# Generate go files
./scripts/generate_precompile.sh --abi ./contracts/abis/ICalculatorPlus.abi --type Calculatorplus --pkg calculatorplus --out ./calculatorplus
```

Now you should have a new directory called `calculatorplus` in the root directory of your project.

If you check our the generated contract.go file you will see right away that it is much longer than in our hash function precompile from earlier. This is due to the fact that our calculator precompile has more functions and parameters. Browse through the code and see if you can spot the new elements:

```go title="contract.go"
// Code generated
// This file is a generated precompile contract config with stubbed abstract functions.
// The file is generated by a template. Please inspect every code and comment in this file before use.

package calculatorplus

import (
    "errors"
    "fmt"
    "math/big"

    "github.com/ava-labs/subnet-evm/accounts/abi"
    "github.com/ava-labs/subnet-evm/precompile/contract"
    "github.com/ava-labs/subnet-evm/vmerrs"

    _ "embed"

    "github.com/ethereum/go-ethereum/common"
)

const (
    // Gas costs for each function. These are set to 1 by default.
    // You should set a gas cost for each function in your contract.
    // Generally, you should not set gas costs very low as this may cause your network to be vulnerable to DoS attacks.
    // There are some predefined gas costs in contract/utils.go that you can use.
    ModuloPlusGasCost uint64 = 1 /* SET A GAS COST HERE */
    PowOfThreeGasCost uint64 = 1 /* SET A GAS COST HERE */
    SimplFracGasCost  uint64 = 1 /* SET A GAS COST HERE */
)

// CUSTOM CODE STARTS HERE
// Reference imports to suppress errors from unused imports. This code and any unnecessary imports can be removed.
var (
    _ = abi.JSON
    _ = errors.New
    _ = big.NewInt
    _ = vmerrs.ErrOutOfGas
    _ = common.Big0
)

// Singleton StatefulPrecompiledContract and signatures.
var (
    // CalculatorplusRawABI contains the raw ABI of Calculatorplus contract.
    //go:embed contract.abi
    CalculatorplusRawABI string

    CalculatorplusABI = contract.ParseABI(CalculatorplusRawABI)

    CalculatorplusPrecompile = createCalculatorplusPrecompile()
)

type ModuloPlusInput struct {
    Dividend *big.Int
    Divisor  *big.Int
}

type ModuloPlusOutput struct {
    Multiple  *big.Int
    Remainder *big.Int
}

type PowOfThreeOutput struct {
    SecondPow *big.Int
    ThirdPow  *big.Int
    FourthPow *big.Int
}

type SimplFracInput struct {
    Numerator   *big.Int
    Denominator *big.Int
}

type SimplFracOutput struct {
    SimplNum   *big.Int
    SimplDenom *big.Int
}

// UnpackModuloPlusInput attempts to unpack [input] as ModuloPlusInput
// assumes that [input] does not include selector (omits first 4 func signature bytes)
func UnpackModuloPlusInput(input []byte) (ModuloPlusInput, error) {
    inputStruct := ModuloPlusInput{}
    err := CalculatorplusABI.UnpackInputIntoInterface(&inputStruct, "moduloPlus", input)

    return inputStruct, err
}

// PackModuloPlus packs [inputStruct] of type ModuloPlusInput into the appropriate arguments for moduloPlus.
func PackModuloPlus(inputStruct ModuloPlusInput) ([]byte, error) {
    return CalculatorplusABI.Pack("moduloPlus", inputStruct.Dividend, inputStruct.Divisor)
}

// PackModuloPlusOutput attempts to pack given [outputStruct] of type ModuloPlusOutput
// to conform the ABI outputs.
func PackModuloPlusOutput(outputStruct ModuloPlusOutput) ([]byte, error) {
    return CalculatorplusABI.PackOutput("moduloPlus",
        outputStruct.Multiple,
        outputStruct.Remainder,
    )
}

// UnpackModuloPlusOutput attempts to unpack [output] as ModuloPlusOutput
// assumes that [output] does not include selector (omits first 4 func signature bytes)
func UnpackModuloPlusOutput(output []byte) (ModuloPlusOutput, error) {
    outputStruct := ModuloPlusOutput{}
    err := CalculatorplusABI.UnpackIntoInterface(&outputStruct, "moduloPlus", output)

    return outputStruct, err
}

func moduloPlus(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {
    if remainingGas, err = contract.DeductGas(suppliedGas, ModuloPlusGasCost); err != nil {
        return nil, 0, err
    }
    // attempts to unpack [input] into the arguments to the ModuloPlusInput.
    // Assumes that [input] does not include selector
    // You can use unpacked [inputStruct] variable in your code
    inputStruct, err := UnpackModuloPlusInput(input)
    if err != nil {
        return nil, remainingGas, err
    }

    // CUSTOM CODE STARTS HERE
    _ = inputStruct             // CUSTOM CODE OPERATES ON INPUT
    var output ModuloPlusOutput // CUSTOM CODE FOR AN OUTPUT
    packedOutput, err := PackModuloPlusOutput(output)
    if err != nil {
        return nil, remainingGas, err
    }

    // Return the packed output and the remaining gas
    return packedOutput, remainingGas, nil
}

// UnpackPowOfThreeInput attempts to unpack [input] into the *big.Int type argument
// assumes that [input] does not include selector (omits first 4 func signature bytes)
func UnpackPowOfThreeInput(input []byte) (*big.Int, error) {
    res, err := CalculatorplusABI.UnpackInput("powOfThree", input)
    if err != nil {
        return new(big.Int), err
    }
    unpacked := *abi.ConvertType(res[0], new(*big.Int)).(**big.Int)
    return unpacked, nil
}

// PackPowOfThree packs [base] of type *big.Int into the appropriate arguments for powOfThree.
// the packed bytes include selector (first 4 func signature bytes).
// This function is mostly used for tests.
func PackPowOfThree(base *big.Int) ([]byte, error) {
    return CalculatorplusABI.Pack("powOfThree", base)
}

// PackPowOfThreeOutput attempts to pack given [outputStruct] of type PowOfThreeOutput
// to conform the ABI outputs.
func PackPowOfThreeOutput(outputStruct PowOfThreeOutput) ([]byte, error) {
    return CalculatorplusABI.PackOutput("powOfThree",
        outputStruct.SecondPow,
        outputStruct.ThirdPow,
        outputStruct.FourthPow,
    )
}

// UnpackPowOfThreeOutput attempts to unpack [output] as PowOfThreeOutput
// assumes that [output] does not include selector (omits first 4 func signature bytes)
func UnpackPowOfThreeOutput(output []byte) (PowOfThreeOutput, error) {
    outputStruct := PowOfThreeOutput{}
    err := CalculatorplusABI.UnpackIntoInterface(&outputStruct, "powOfThree", output)

    return outputStruct, err
}

func powOfThree(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {
    if remainingGas, err = contract.DeductGas(suppliedGas, PowOfThreeGasCost); err != nil {
        return nil, 0, err
    }
    // attempts to unpack [input] into the arguments to the PowOfThreeInput.
    // Assumes that [input] does not include selector
    // You can use unpacked [inputStruct] variable in your code
    inputStruct, err := UnpackPowOfThreeInput(input)
    if err != nil {
        return nil, remainingGas, err
    }

    // CUSTOM CODE STARTS HERE
    _ = inputStruct             // CUSTOM CODE OPERATES ON INPUT
    var output PowOfThreeOutput // CUSTOM CODE FOR AN OUTPUT
    packedOutput, err := PackPowOfThreeOutput(output)
    if err != nil {
        return nil, remainingGas, err
    }

    // Return the packed output and the remaining gas
    return packedOutput, remainingGas, nil
}

// UnpackSimplFracInput attempts to unpack [input] as SimplFracInput
// assumes that [input] does not include selector (omits first 4 func signature bytes)
func UnpackSimplFracInput(input []byte) (SimplFracInput, error) {
    inputStruct := SimplFracInput{}
    err := CalculatorplusABI.UnpackInputIntoInterface(&inputStruct, "simplFrac", input)

    return inputStruct, err
}

// PackSimplFrac packs [inputStruct] of type SimplFracInput into the appropriate arguments for simplFrac.
func PackSimplFrac(inputStruct SimplFracInput) ([]byte, error) {
    return CalculatorplusABI.Pack("simplFrac", inputStruct.Numerator, inputStruct.Denominator)
}

// PackSimplFracOutput attempts to pack given [outputStruct] of type SimplFracOutput
// to conform the ABI outputs.
func PackSimplFracOutput(outputStruct SimplFracOutput) ([]byte, error) {
    return CalculatorplusABI.PackOutput("simplFrac",
        outputStruct.SimplNum,
        outputStruct.SimplDenom,
    )
}

// UnpackSimplFracOutput attempts to unpack [output] as SimplFracOutput
// assumes that [output] does not include selector (omits first 4 func signature bytes)
func UnpackSimplFracOutput(output []byte) (SimplFracOutput, error) {
    outputStruct := SimplFracOutput{}
    err := CalculatorplusABI.UnpackIntoInterface(&outputStruct, "simplFrac", output)

    return outputStruct, err
}

func simplFrac(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {
    if remainingGas, err = contract.DeductGas(suppliedGas, SimplFracGasCost); err != nil {
        return nil, 0, err
    }
    // attempts to unpack [input] into the arguments to the SimplFracInput.
    // Assumes that [input] does not include selector
    // You can use unpacked [inputStruct] variable in your code
    inputStruct, err := UnpackSimplFracInput(input)
    if err != nil {
        return nil, remainingGas, err
    }

    // CUSTOM CODE STARTS HERE
    _ = inputStruct            // CUSTOM CODE OPERATES ON INPUT
    var output SimplFracOutput // CUSTOM CODE FOR AN OUTPUT
    packedOutput, err := PackSimplFracOutput(output)
    if err != nil {
        return nil, remainingGas, err
    }

    // Return the packed output and the remaining gas
    return packedOutput, remainingGas, nil
}

// createCalculatorplusPrecompile returns a StatefulPrecompiledContract with getters and setters for the precompile.

func createCalculatorplusPrecompile() contract.StatefulPrecompiledContract {
    var functions []*contract.StatefulPrecompileFunction

    abiFunctionMap := map[string]contract.RunStatefulPrecompileFunc{
        "moduloPlus": moduloPlus,
        "powOfThree": powOfThree,
        "simplFrac":  simplFrac,
    }

    for name, function := range abiFunctionMap {
        method, ok := CalculatorplusABI.Methods[name]
        if !ok {
            panic(fmt.Errorf("given method (%s) does not exist in the ABI", name))
        }
        functions = append(functions, contract.NewStatefulPrecompileFunction(method.ID, function))
    }
    // Construct the contract with no fallback function.
    statefulContract, err := contract.NewStatefulPrecompileContract(nil, functions)
    if err != nil {
        panic(err)
    }
    return statefulContract
}
```

# Unpacking Multiple Inputs & Packing Multiple Outputs (/academy/customizing-evm/08-calculator-precompile/03-unpacking-and-packing)

---
title: Unpacking Multiple Inputs & Packing Multiple Outputs
description: Learn how to unpack multiple inputs and packing multiple outputs.
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

## Unpack/Pack Functions For Each Operation

As with the MD5 precompile, the generator created the pack/unpack functions for each operation of our Calculator and CalculatorPlus precompiles. However, you might have noticed that the generator also created some struct in each respective `contract.go` file. In the case of CalculatorPrecompile, we have:

```go title="contract.go"
type AddInput struct {
    Value1 *big.Int
    Value2 *big.Int
}

type NextTwoOutput struct {
    Result1 *big.Int
    Result2 *big.Int
}

type RepeatInput struct {
    Times *big.Int
    Text  string
}
```

The generator creates these structs whenever a function defined in the respective Solidity interface has more than one input or more than one output. These multiple values are now stored together via structs.

## Unpacking Multiple Inputs

To understand how unpacking works when structs are introduced, let's take a look at the add function in the Calculator precompile, which takes in two inputs, and the nextTwo, which takes in only one input.

```go
// UnpackAddInput attempts to unpack [input] as AddInput
// assumes that [input] does not include selector (omits first 4 func signature bytes)
func UnpackAddInput(input []byte) (AddInput, error) {
    inputStruct := AddInput{}
    err := CalculatorABI.UnpackInputIntoInterface(&inputStruct, "add", input)
    return inputStruct, err
}

// UnpackNextTwoInput attempts to unpack [input] into the *big.Int type argument
// assumes that [input] does not include selector (omits first 4 func signature bytes)
func UnpackNextTwoInput(input []byte) (*big.Int, error) {
    res, err := CalculatorABI.UnpackInput("nextTwo", input)
    if err != nil {
        return big.NewInt(0), err
    }
    unpacked := *abi.ConvertType(res[0], new(*big.Int)).(**big.Int)
    return unpacked, nil
}
```

As you can see, both unpacker functions take a byte array as an input but the `UnpackAddInput` returns a value of the type `AddInput` (which contains two `big.Int` values) and `UnpackNextTwoInput` returns a value of the type `big.Int`.

In each case, the respective unpacking function takes in a byte array as an input. However, `UnpackAddInput` returns a value of the type `AddInput`, which is a struct that contains two `big.Int` values. `UnpackNextTwo`, meanwhile, returns an value of type `big.Int`. 

To demonstrate how one could use the output of unpacking functions like `UnpackAddInput`, below is the implementation of the add function of the Calculator precompile:

```go
func add(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {
    if remainingGas, err = contract.DeductGas(suppliedGas, AddGasCost); err != nil {
        return nil, 0, err
    }
    // attempts to unpack [input] into the arguments to the AddInput.
    // Assumes that [input] does not include selector
    // You can use unpacked [inputStruct] variable in your code
    inputStruct, err := UnpackAddInput(input)
    if err != nil {
        return nil, remainingGas, err
    }

    // CUSTOM CODE STARTS HERE
    var output *big.Int // CUSTOM CODE FOR AN OUTPUT

    output = big.NewInt(0).Add(inputStruct.Value1, inputStruct.Value2)

    packedOutput, err := PackAddOutput(output)
    if err != nil {
        return nil, remainingGas, err
    }

    // Return the packed output and the remaining gas
    return packedOutput, remainingGas, nil
}
```

## Packing Multiple Outputs

To understand how structs affect the packing of outputs, lets refer to `PackNextTwoOutput` for the Calculator precompile:

```go
// PackHashWithMd5Output attempts to pack given hash of type [16]
// PackNextTwoOutput attempts to pack given [outputStruct] of type NextTwoOutput
// to conform the ABI outputs.
func PackNextTwoOutput(outputStruct NextTwoOutput) ([]byte, error) {
    return CalculatorABI.PackOutput("nextTwo",
        outputStruct.Result1,
        outputStruct.Result2,
    )
}
```           
        
Notice here that even though we are no longer working with singular types, the generator still is able to pack our struct so that it is of the type bytes.

As a result, we are able to return the packed version of any `NextTwoOutput` struct as bytes at the end of nextTwo.


# Implementing Precompile (/academy/customizing-evm/08-calculator-precompile/04-implementing-precompile)

---
title: Implementing Precompile
description: Learn how to implement the precompile in `contract.go`
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

In this section, we will go define the logic for our CalculatorPlus precompile; in particular, we want to add the logic for the following three functions: `powOfThree`, `moduloPlus`, and `simplFrac`.

For those worried about this section - don't be! Our solution only added 12 lines of code to `contract.go`.

## Looking at Calculator

Before we define the logic of CalculatorPlus, we first will examine the implementation of the Calculator precompile:

```go
func add(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {
    if remainingGas, err = contract.DeductGas(suppliedGas, AddGasCost); err != nil {
        return nil, 0, err
    }
    // attempts to unpack [input] into the arguments to the AddInput.
    // Assumes that [input] does not include selector
    // You can use unpacked [inputStruct] variable in your code
    inputStruct, err := UnpackAddInput(input)
    if err != nil {
        return nil, remainingGas, err
    }

    // CUSTOM CODE STARTS HERE
  
    _ = inputStruct          // CUSTOM CODE OPERATES ON INPUT
  
    var output *big.Int // CUSTOM CODE FOR AN OUTPUT

    output = big.NewInt(0).Add(inputStruct.Value1, inputStruct.Value2)

    packedOutput, err := PackAddOutput(output)
    if err != nil {
        return nil, remainingGas, err
    }

    // Return the packed output and the remaining gas
    return packedOutput, remainingGas, nil
}
// ...

func repeat(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {
    if remainingGas, err = contract.DeductGas(suppliedGas, RepeatGasCost); err != nil {
        return nil, 0, err
    }
    // attempts to unpack [input] into the arguments to the RepeatInput.
    // Assumes that [input] does not include selector
    // You can use unpacked [inputStruct] variable in your code
    inputStruct, err := UnpackRepeatInput(input)
    if err != nil {
        return nil, remainingGas, err
    }

    // CUSTOM CODE STARTS HERE
    _ = inputStruct          // CUSTOM CODE OPERATES ON INPUT
  
    var output string // CUSTOM CODE FOR AN OUTPUT

    output = strings.Repeat(inputStruct.Text, int(inputStruct.Times.Int64()))

    packedOutput, err := PackRepeatOutput(output)
    if err != nil {
        return nil, remainingGas, err
    }

    // Return the packed output and the remaining gas
    return packedOutput, remainingGas, nil
}

// ...

func nextTwo(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {
    if remainingGas, err = contract.DeductGas(suppliedGas, NextTwoGasCost); err != nil {
        return nil, 0, err
    }
    // attempts to unpack [input] into the arguments to the NextTwoInput.
    // Assumes that [input] does not include selector
    // You can use unpacked [inputStruct] variable in your code
    inputStruct, err := UnpackNextTwoInput(input)
    if err != nil {
        return nil, remainingGas, err
    }

    // CUSTOM CODE STARTS HERE
  
    _ = inputStruct          // CUSTOM CODE OPERATES ON INPUT
  
    var output NextTwoOutput // CUSTOM CODE FOR AN OUTPUT

    output.Result1 = big.NewInt(0).Add(inputStruct, big.NewInt(1))
    output.Result2 = big.NewInt(0).Add(inputStruct, big.NewInt(2))

    packedOutput, err := PackNextTwoOutput(output)
    if err != nil {
        return nil, remainingGas, err
    }

    // Return the packed output and the remaining gas
    return packedOutput, remainingGas, nil
}
```

Although the code snippet above may be long, you might notice that we added only four lines of code to the autogenerated code provided to us by Precompile-EVM! In particular, we only added lines 19, 48, 79, and 80. In general, note the following:

- Structs vs Singular Values: make sure to keep track which inputs/outputs are structs and which one are values like big.Int. As an example, in `nextTwo`, we are dealing with a big.Int type input. However, in repeat, we are passed in a input of type struct RepeatInput.
- Documentation: for both Calculator and CalculatorPlus, the big package documentation is of great reference: https://pkg.go.dev/math/big 

Now that we have looked at the implementation for the Calculator precompile, its time you define the CalculatorPlus precompile!

## Implementing moduloPlus

We start by looking at the starter code for `moduloPlus`:

```go
func moduloPlus(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {
    if remainingGas, err = contract.DeductGas(suppliedGas, ModuloPlusGasCost); err != nil {
        return nil, 0, err
    }
    // attempts to unpack [input] into the arguments to the ModuloPlusInput.
    // Assumes that [input] does not include selector
    // You can use unpacked [inputStruct] variable in your code
    inputStruct, err := UnpackModuloPlusInput(input)
    if err != nil {
        return nil, remainingGas, err
    }

    // CUSTOM CODE STARTS HERE
    _ = inputStruct             // CUSTOM CODE OPERATES ON INPUT
    var output ModuloPlusOutput // CUSTOM CODE FOR AN OUTPUT
    
    packedOutput, err := PackModuloPlusOutput(output)
    if err != nil {
        return nil, remainingGas, err
    }

    // Return the packed output and the remaining gas
    return packedOutput, remainingGas, nil
}
```

We want to note the following:

- `inputStruct` is the input that we want to work with (i.e. `inputStruct` contains the two numbers that we want to use for the modulo calculation)
- All of our code will go after line 15
- We want the struct output to contain the result of our modulo operation (the struct will contain the multiple and remainder)

With this in mind, try to implement `moduloPlus`.

<Accordions>
<Accordion title="Solution">

```go
func moduloPlus(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {func moduloPlus(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {
	if remainingGas, err = contract.DeductGas(suppliedGas, ModuloPlusGasCost); err != nil {
		return nil, 0, err
	}
	// attempts to unpack [input] into the arguments to the ModuloPlusInput.
	// Assumes that [input] does not include selector
	// You can use unpacked [inputStruct] variable in your code
	inputStruct, err := UnpackModuloPlusInput(input)
	if err != nil {
		return nil, remainingGas, err
	}

	// CUSTOM CODE STARTS HERE
	_ = inputStruct             // CUSTOM CODE OPERATES ON INPUT
	var output ModuloPlusOutput // CUSTOM CODE FOR AN OUTPUT
	output.Multiple, output.Remainder = big.NewInt(0).DivMod(inputStruct.Dividend, inputStruct.Divisor, output.Remainder)

	packedOutput, err := PackModuloPlusOutput(output)
	if err != nil {
		return nil, remainingGas, err
	}

	// Return the packed output and the remaining gas
	return packedOutput, remainingGas, nil
}
```

</Accordion>
</Accordions>

## Implementing powOfThree

Likewise, for `powOfThree`, we want to define the logic of the function in the custom code section. However, note that while we are working with an output struct, our input is a singular value. With this in mind, take a crack at implementing `powOfThree`:

<Accordions>
<Accordion title="Solution">

```go
func powOfThree(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {func powOfThree(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {
	if remainingGas, err = contract.DeductGas(suppliedGas, PowOfThreeGasCost); err != nil {
		return nil, 0, err
	}
	// attempts to unpack [input] into the arguments to the PowOfThreeInput.
	// Assumes that [input] does not include selector
	// You can use unpacked [inputStruct] variable in your code
	inputStruct, err := UnpackPowOfThreeInput(input)
	if err != nil {
		return nil, remainingGas, err
	}

	// CUSTOM CODE STARTS HERE
	_ = inputStruct             // CUSTOM CODE OPERATES ON INPUT
	var output PowOfThreeOutput // CUSTOM CODE FOR AN OUTPUT

	output.SecondPow = big.NewInt(0).Exp(inputStruct, big.NewInt(2), nil)
	output.ThirdPow = big.NewInt(0).Exp(inputStruct, big.NewInt(3), nil)
	output.FourthPow = big.NewInt(0).Exp(inputStruct, big.NewInt(4), nil)

	packedOutput, err := PackPowOfThreeOutput(output)
	if err != nil {
		return nil, remainingGas, err
	}

	// Return the packed output and the remaining gas
	return packedOutput, remainingGas, nil
}
```

</Accordion>
</Accordions>

## Implementing simplFrac

For implementing `simplFrac`, note the following:

- The documentation for the big package will be of use here
- Remember to take care of the case when the denominator is 0

<Accordions>
<Accordion title="Solution">

```go
func simplFrac(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {func simplFrac(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {
	if remainingGas, err = contract.DeductGas(suppliedGas, SimplFracGasCost); err != nil {
		return nil, 0, err
	}
	// attempts to unpack [input] into the arguments to the SimplFracInput.
	// Assumes that [input] does not include selector
	// You can use unpacked [inputStruct] variable in your code
	inputStruct, err := UnpackSimplFracInput(input)
	if err != nil {
		return nil, remainingGas, err
	}

	// CUSTOM CODE STARTS HERE
	_ = inputStruct            // CUSTOM CODE OPERATES ON INPUT
	var output SimplFracOutput // CUSTOM CODE FOR AN OUTPUT

	// If denominator is 0, return both 0
	if inputStruct.Denominator.Cmp(big.NewInt(0)) == 0 {
		output.SimplDenom = big.NewInt(0)
		output.SimplNum = big.NewInt(0)
	} else {
		// First, find common denominator
		var gcd big.Int
		gcd.GCD(nil, nil, inputStruct.Numerator, inputStruct.Denominator)

		// Now, simplify fraction
		output.SimplNum = big.NewInt(0).Div(inputStruct.Numerator, &gcd)
		output.SimplDenom = big.NewInt(0).Div(inputStruct.Denominator, &gcd)
	}

	packedOutput, err := PackSimplFracOutput(output)
	if err != nil {
		return nil, remainingGas, err
	}

	// Return the packed output and the remaining gas
	return packedOutput, remainingGas, nil
}
```

</Accordion>
</Accordions>

## Final Solution

Below is the final solution for the CalculatorPlus precompile:

<Accordions>
<Accordion title="Solution">

```go
// Code generated
// This file is a generated precompile contract config with stubbed abstract functions.
// The file is generated by a template. Please inspect every code and comment in this file before use.

package calculatorplus

import (
	"errors"
	"fmt"
	"math/big"

	"github.com/ava-labs/subnet-evm/accounts/abi"
	"github.com/ava-labs/subnet-evm/precompile/contract"
	"github.com/ava-labs/subnet-evm/vmerrs"

	_ "embed"

	"github.com/ethereum/go-ethereum/common"
)

const (
	// Gas costs for each function. These are set to 1 by default.
	// You should set a gas cost for each function in your contract.
	// Generally, you should not set gas costs very low as this may cause your network to be vulnerable to DoS attacks.
	// There are some predefined gas costs in contract/utils.go that you can use.
	ModuloPlusGasCost uint64 = 1 /* SET A GAS COST HERE */
	PowOfThreeGasCost uint64 = 1 /* SET A GAS COST HERE */
	SimplFracGasCost  uint64 = 1 /* SET A GAS COST HERE */
)

// CUSTOM CODE STARTS HERE
// Reference imports to suppress errors from unused imports. This code and any unnecessary imports can be removed.
var (
	_ = abi.JSON
	_ = errors.New
	_ = big.NewInt
	_ = vmerrs.ErrOutOfGas
	_ = common.Big0
)

// Singleton StatefulPrecompiledContract and signatures.
var (

	// CalculatorplusRawABI contains the raw ABI of Calculatorplus contract.
	//go:embed contract.abi
	CalculatorplusRawABI string

	CalculatorplusABI = contract.ParseABI(CalculatorplusRawABI)

	CalculatorplusPrecompile = createCalculatorplusPrecompile()
)

type ModuloPlusInput struct {
	Dividend *big.Int
	Divisor  *big.Int
}

type ModuloPlusOutput struct {
	Multiple  *big.Int
	Remainder *big.Int
}

type PowOfThreeOutput struct {
	SecondPow *big.Int
	ThirdPow  *big.Int
	FourthPow *big.Int
}

type SimplFracInput struct {
	Numerator   *big.Int
	Denominator *big.Int
}

type SimplFracOutput struct {
	SimplNum   *big.Int
	SimplDenom *big.Int
}

// UnpackModuloPlusInput attempts to unpack [input] as ModuloPlusInput
// assumes that [input] does not include selector (omits first 4 func signature bytes)
func UnpackModuloPlusInput(input []byte) (ModuloPlusInput, error) {
	inputStruct := ModuloPlusInput{}
	err := CalculatorplusABI.UnpackInputIntoInterface(&inputStruct, "moduloPlus", input)

	return inputStruct, err
}

// PackModuloPlus packs [inputStruct] of type ModuloPlusInput into the appropriate arguments for moduloPlus.
func PackModuloPlus(inputStruct ModuloPlusInput) ([]byte, error) {
	return CalculatorplusABI.Pack("moduloPlus", inputStruct.Dividend, inputStruct.Divisor)
}

// PackModuloPlusOutput attempts to pack given [outputStruct] of type ModuloPlusOutput
// to conform the ABI outputs.
func PackModuloPlusOutput(outputStruct ModuloPlusOutput) ([]byte, error) {
	return CalculatorplusABI.PackOutput("moduloPlus",
		outputStruct.Multiple,
		outputStruct.Remainder,
	)
}

// UnpackModuloPlusOutput attempts to unpack [output] as ModuloPlusOutput
// assumes that [output] does not include selector (omits first 4 func signature bytes)
func UnpackModuloPlusOutput(output []byte) (ModuloPlusOutput, error) {
	outputStruct := ModuloPlusOutput{}
	err := CalculatorplusABI.UnpackIntoInterface(&outputStruct, "moduloPlus", output)

	return outputStruct, err
}

func moduloPlus(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {
	if remainingGas, err = contract.DeductGas(suppliedGas, ModuloPlusGasCost); err != nil {
		return nil, 0, err
	}
	// attempts to unpack [input] into the arguments to the ModuloPlusInput.
	// Assumes that [input] does not include selector
	// You can use unpacked [inputStruct] variable in your code
	inputStruct, err := UnpackModuloPlusInput(input)
	if err != nil {
		return nil, remainingGas, err
	}

	// CUSTOM CODE STARTS HERE
	_ = inputStruct             // CUSTOM CODE OPERATES ON INPUT
	var output ModuloPlusOutput // CUSTOM CODE FOR AN OUTPUT
	output.Multiple, output.Remainder = big.NewInt(0).DivMod(inputStruct.Dividend, inputStruct.Divisor, output.Remainder)

	packedOutput, err := PackModuloPlusOutput(output)
	if err != nil {
		return nil, remainingGas, err
	}

	// Return the packed output and the remaining gas
	return packedOutput, remainingGas, nil
}

// UnpackPowOfThreeInput attempts to unpack [input] into the *big.Int type argument
// assumes that [input] does not include selector (omits first 4 func signature bytes)
func UnpackPowOfThreeInput(input []byte) (*big.Int, error) {
	res, err := CalculatorplusABI.UnpackInput("powOfThree", input)
	if err != nil {
		return new(big.Int), err
	}
	unpacked := *abi.ConvertType(res[0], new(*big.Int)).(**big.Int)
	return unpacked, nil
}

// PackPowOfThree packs [base] of type *big.Int into the appropriate arguments for powOfThree.
// the packed bytes include selector (first 4 func signature bytes).
// This function is mostly used for tests.
func PackPowOfThree(base *big.Int) ([]byte, error) {
	return CalculatorplusABI.Pack("powOfThree", base)
}

// PackPowOfThreeOutput attempts to pack given [outputStruct] of type PowOfThreeOutput
// to conform the ABI outputs.
func PackPowOfThreeOutput(outputStruct PowOfThreeOutput) ([]byte, error) {
	return CalculatorplusABI.PackOutput("powOfThree",
		outputStruct.SecondPow,
		outputStruct.ThirdPow,
		outputStruct.FourthPow,
	)
}

// UnpackPowOfThreeOutput attempts to unpack [output] as PowOfThreeOutput
// assumes that [output] does not include selector (omits first 4 func signature bytes)
func UnpackPowOfThreeOutput(output []byte) (PowOfThreeOutput, error) {
	outputStruct := PowOfThreeOutput{}
	err := CalculatorplusABI.UnpackIntoInterface(&outputStruct, "powOfThree", output)

	return outputStruct, err
}

func powOfThree(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {
	if remainingGas, err = contract.DeductGas(suppliedGas, PowOfThreeGasCost); err != nil {
		return nil, 0, err
	}
	// attempts to unpack [input] into the arguments to the PowOfThreeInput.
	// Assumes that [input] does not include selector
	// You can use unpacked [inputStruct] variable in your code
	inputStruct, err := UnpackPowOfThreeInput(input)
	if err != nil {
		return nil, remainingGas, err
	}

	// CUSTOM CODE STARTS HERE
	_ = inputStruct             // CUSTOM CODE OPERATES ON INPUT
	var output PowOfThreeOutput // CUSTOM CODE FOR AN OUTPUT

	output.SecondPow = big.NewInt(0).Exp(inputStruct, big.NewInt(2), nil)
	output.ThirdPow = big.NewInt(0).Exp(inputStruct, big.NewInt(3), nil)
	output.FourthPow = big.NewInt(0).Exp(inputStruct, big.NewInt(4), nil)

	packedOutput, err := PackPowOfThreeOutput(output)
	if err != nil {
		return nil, remainingGas, err
	}

	// Return the packed output and the remaining gas
	return packedOutput, remainingGas, nil
}

// UnpackSimplFracInput attempts to unpack [input] as SimplFracInput
// assumes that [input] does not include selector (omits first 4 func signature bytes)
func UnpackSimplFracInput(input []byte) (SimplFracInput, error) {
	inputStruct := SimplFracInput{}
	err := CalculatorplusABI.UnpackInputIntoInterface(&inputStruct, "simplFrac", input)

	return inputStruct, err
}

// PackSimplFrac packs [inputStruct] of type SimplFracInput into the appropriate arguments for simplFrac.
func PackSimplFrac(inputStruct SimplFracInput) ([]byte, error) {
	return CalculatorplusABI.Pack("simplFrac", inputStruct.Numerator, inputStruct.Denominator)
}

// PackSimplFracOutput attempts to pack given [outputStruct] of type SimplFracOutput
// to conform the ABI outputs.
func PackSimplFracOutput(outputStruct SimplFracOutput) ([]byte, error) {
	return CalculatorplusABI.PackOutput("simplFrac",
		outputStruct.SimplNum,
		outputStruct.SimplDenom,
	)
}

// UnpackSimplFracOutput attempts to unpack [output] as SimplFracOutput
// assumes that [output] does not include selector (omits first 4 func signature bytes)
func UnpackSimplFracOutput(output []byte) (SimplFracOutput, error) {
	outputStruct := SimplFracOutput{}
	err := CalculatorplusABI.UnpackIntoInterface(&outputStruct, "simplFrac", output)

	return outputStruct, err
}

func simplFrac(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {
	if remainingGas, err = contract.DeductGas(suppliedGas, SimplFracGasCost); err != nil {
		return nil, 0, err
	}
	// attempts to unpack [input] into the arguments to the SimplFracInput.
	// Assumes that [input] does not include selector
	// You can use unpacked [inputStruct] variable in your code
	inputStruct, err := UnpackSimplFracInput(input)
	if err != nil {
		return nil, remainingGas, err
	}

	// CUSTOM CODE STARTS HERE
	_ = inputStruct            // CUSTOM CODE OPERATES ON INPUT
	var output SimplFracOutput // CUSTOM CODE FOR AN OUTPUT

	// If denominator is 0, return both 0
	if inputStruct.Denominator.Cmp(big.NewInt(0)) == 0 {
		output.SimplDenom = big.NewInt(0)
		output.SimplNum = big.NewInt(0)
	} else {
		// First, find common denominator
		var gcd big.Int
		gcd.GCD(nil, nil, inputStruct.Numerator, inputStruct.Denominator)

		// Now, simplify fraction
		output.SimplNum = big.NewInt(0).Div(inputStruct.Numerator, &gcd)
		output.SimplDenom = big.NewInt(0).Div(inputStruct.Denominator, &gcd)
	}

	packedOutput, err := PackSimplFracOutput(output)
	if err != nil {
		return nil, remainingGas, err
	}

	// Return the packed output and the remaining gas
	return packedOutput, remainingGas, nil
}

// createCalculatorplusPrecompile returns a StatefulPrecompiledContract with getters and setters for the precompile.

func createCalculatorplusPrecompile() contract.StatefulPrecompiledContract {
	var functions []*contract.StatefulPrecompileFunction

	abiFunctionMap := map[string]contract.RunStatefulPrecompileFunc{
		"moduloPlus": moduloPlus,
		"powOfThree": powOfThree,
		"simplFrac":  simplFrac,
	}

	for name, function := range abiFunctionMap {
		method, ok := CalculatorplusABI.Methods[name]
		if !ok {
			panic(fmt.Errorf("given method (%s) does not exist in the ABI", name))
		}
		functions = append(functions, contract.NewStatefulPrecompileFunction(method.ID, function))
	}
	// Construct the contract with no fallback function.
	statefulContract, err := contract.NewStatefulPrecompileContract(nil, functions)
	if err != nil {
		panic(err)
	}
	return statefulContract
}
```

</Accordion>
</Accordions>


# Setting the ConfigKey & ContractAddress (/academy/customizing-evm/08-calculator-precompile/05-set-configkey-contractaddr)

---
title: Setting the ConfigKey & ContractAddress
description: Learn how to set the ConfigKey, ContractAddress and register the Precompile.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

## ConfigKey

Just as with the MD5 precompile in the previous section, go to the `module.go` file and set a `ConfigKey`.

## Contract Address

In the same file, set a `ContractAddress`. Choose one that has not been used by other precompiles of earlier sections.

## Registration

Go to the `plugin/main.go` file and register the new precompile.

# Creating Genesis Block with precompileConfig (/academy/customizing-evm/08-calculator-precompile/06-create-genesis-block)

---
title: Creating Genesis Block with precompileConfig
description: Learn how to create a genesis block with precompileConfig.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

In order to create a new Blockchain from our customized EVM, we have to define a Genesis block just as we did in out section earlier.

To incorporate the CalculatorPlus precompile as part of the genesis block, we need to create a new genesis file and include a key for the CalculatorPlus precompile in the configuration JSON. This key, in particular, is the `configKey` that we specified in the `module.go` file of the Calculator precompile in the previous section.

Copy over `Calculator.json` into a new file called `CalculatorPlus.json` and add the necessary key-pair value to the config.

<Accordions>
<Accordion title="Solution">

```json title="CalculatorPlus.json"
{
  "config": {
    "chainId": 99999,
    "homesteadBlock": 0,
    "eip150Block": 0,
    "eip150Hash": "0x2086799aeebeae135c246c65021c82b4e15a2c451340993aacfd2751886514f0",
    "eip155Block": 0,
    "eip158Block": 0,
    "byzantiumBlock": 0,
    "constantinopleBlock": 0,
    "petersburgBlock": 0,
    "istanbulBlock": 0,
    "muirGlacierBlock": 0,
    "subnetEVMTimestamp": 0,
    "feeConfig": {
      "gasLimit": 20000000,
      "minBaseFee": 1000000000,
      "targetGas": 100000000,
      "baseFeeChangeDenominator": 48,
      "minBlockGasCost": 0,
      "maxBlockGasCost": 10000000,
      "targetBlockRate": 2,
      "blockGasCostStep": 500000
    },
    "sha256Config": {
      "blockTimestamp": 0
    },
    "calculatorConfig": {
      "blockTimestamp": 0
    },
    "calculatorplusConfig" : {
        "blockTimestamp": 0
    }
  },
  "alloc": {
    "8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC": {
      "balance": "0x52B7D2DCC80CD2E4000000"
    }
  },
  "nonce": "0x0",
  "timestamp": "0x0",
  "extraData": "0x00",
  "gasLimit": "0x1312D00",
  "difficulty": "0x0",
  "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
  "coinbase": "0x0000000000000000000000000000000000000000",
  "number": "0x0",
  "gasUsed": "0x0",
  "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000"
}
```

</Accordion>
</Accordions>

# Testing Precompiles via Go (/academy/customizing-evm/08-calculator-precompile/07-testing-precompile)

---
title: Testing Precompiles via Go
description: Learn how to test your Precompiles using Golang.
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

> Program testing can be used to show the presence of bugs, but never to show their absence. - Edsger W. Dijkstra

Let's once again examine the functions of the Calculator precompile and what each one does (in layman terms):

- `add`: computes the sum of two numbers
- `nextTwo`: returns the next two numbers that come after the input given 
- `repeat`: repeats a string N number of times

While we spent a good amount of time in the previous sections examining Calculator Solidity interface and the Go logic, we forgot to do one thing: *test the functionality of Calculator*.

But why test? For some, it may seems pointless to test such basic functions. However, testing all functions is important because it helps validate our belief that the logic of our functions is what we intended them to be.

In this section, we will focus on utilizing three types of tests for our Calculator precompile:

1. Autogenerated Tests
2. Unit Tests
3. Fuzz Tests

# Modify Autogenerated Tests (/academy/customizing-evm/08-calculator-precompile/08-autogenerated-tests)

---
title: Modify Autogenerated Tests
description: Learn how to modify autogenerated tests in Go.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

The autogenerated tests will help us making sure, that our precompile throw an error in case not enough gas is supplied. To start, go to calculator/contract_test.go, where you will see the following:

```go
// Code generated
// This file is a generated precompile contract test with the skeleton of test functions.
// The file is generated by a template. Please inspect every code and comment in this file before use.

package calculator

import (
    "testing"

    "github.com/ava-labs/subnet-evm/core/state"
    "github.com/ava-labs/subnet-evm/precompile/testutils"
    "github.com/ava-labs/subnet-evm/vmerrs"
    "github.com/ethereum/go-ethereum/common"
    "github.com/stretchr/testify/require"
)

// These tests are run against the precompile contract directly with
// the given input and expected output. They're just a guide to
// help you write your own tests. These tests are for general cases like
// allowlist, readOnly behaviour, and gas cost. You should write your own
// tests for specific cases.
var (
    tests = map[string]testutils.PrecompileTest{
        "insufficient gas for add should fail": {
            Caller: common.Address{1},
            InputFn: func(t testing.TB) []byte {
                // CUSTOM CODE STARTS HERE
                // populate test input here
                testInput := AddInput{}
                input, err := PackAdd(testInput)
                require.NoError(t, err)
                return input
            },
            SuppliedGas: AddGasCost - 1,
            ReadOnly:    false,
            ExpectedErr: vmerrs.ErrOutOfGas.Error(),
        },
        "insufficient gas for nextTwo should fail": {
            Caller: common.Address{1},
            InputFn: func(t testing.TB) []byte {
                // CUSTOM CODE STARTS HERE
                // set test input to a value here
                var testInput *big.Int
                input, err := PackNextTwo(testInput)
                require.NoError(t, err)
                return input
            },
            SuppliedGas: NextTwoGasCost - 1,
            ReadOnly:    false,
            ExpectedErr: vmerrs.ErrOutOfGas.Error(),
        },
        "insufficient gas for repeat should fail": {
            Caller: common.Address{1},
            InputFn: func(t testing.TB) []byte {
                // CUSTOM CODE STARTS HERE
                // populate test input here
                testInput := RepeatInput{}
                input, err := PackRepeat(testInput)
                require.NoError(t, err)
                return input
            },
            SuppliedGas: RepeatGasCost - 1,
            ReadOnly:    false,
            ExpectedErr: vmerrs.ErrOutOfGas.Error(),
        },
    }
)

// TestCalculatorEmptyRun tests the Run function of the precompile contract.
func TestCalculatorEmptyRun(t *testing.T) {
    // Run tests.
    for name, test := range tests {
        t.Run(name, func(t *testing.T) {
            test.Run(t, Module, state.NewTestStateDB(t))
        })
    }
}

func BenchmarkCalculatorEmpty(b *testing.B) {
    // Benchmark tests.
    for name, test := range tests {
        b.Run(name, func(b *testing.B) {
            test.Bench(b, Module, state.NewTestStateDB(b))
        })
    }
}
```

There is a lot to digest in `contract_test.go`, but the file can be divided into the following three sections:

- Unit Tests
- TestCalculatorEmptyRun
- BenchmarkCalculator

The autogenerated unit tests are stored in the variable var, which is a mapping from strings (the description of the tests cases) to individual unit tests (`testutils.PrecompileTest`). Upon inspecting the keys of each pair, you will see that all three autogenerated unit tests are checking the same thing that: `add`, `nextTwo`, and `repeat` fail if not enough gas is provided. Each test expects to fail when supplying too little gas:

```go
{
  // ...
  SuppliedGas: RepeatGasCost - 1,
  ExpectedErr: vmerrs.ErrOutOfGas.Error(),
}
```

As of currently, if you attempt to build and run the test cases, you will not get very far because there is one step we need to do to: pass in arguments for each autogenerated unit test. For each variable testInput defined in each unit test, add an argument. What argument to put down does not matter, it just needs to be a valid argument. An example of what arguments to put in can be found below:

```go
var (
    tests = map[string]testutils.PrecompileTest{
        "insufficient gas for add should fail": {
            Caller: common.Address{1},
            InputFn: func(t testing.TB) []byte {
                // CUSTOM CODE STARTS HERE
                // populate test input here
                testInput := AddInput{big.NewInt(1), big.NewInt(1)}
                input, err := PackAdd(testInput)
                require.NoError(t, err)
                return input
            },
            SuppliedGas: AddGasCost - 1,
            ReadOnly:    false,
            ExpectedErr: vmerrs.ErrOutOfGas.Error(),
        },
        "insufficient gas for nextTwo should fail": {
            Caller: common.Address{1},
            InputFn: func(t testing.TB) []byte {
                // CUSTOM CODE STARTS HERE
                // set test input to a value here
                // var testInput *big.Int
                testInput := big.NewInt(1)
                input, err := PackNextTwo(testInput)
                require.NoError(t, err)
                return input
            },
            SuppliedGas: NextTwoGasCost - 1,
            ReadOnly:    false,
            ExpectedErr: vmerrs.ErrOutOfGas.Error(),
        },
        "insufficient gas for repeat should fail": {
            Caller: common.Address{1},
            InputFn: func(t testing.TB) []byte {
                // CUSTOM CODE STARTS HERE
                // populate test input here
                testInput := RepeatInput{big.NewInt(1), "EGS"}
                input, err := PackRepeat(testInput)
                require.NoError(t, err)
                return input
            },
            SuppliedGas: RepeatGasCost - 1,
            ReadOnly:    false,
            ExpectedErr: vmerrs.ErrOutOfGas.Error(),
        },
    }
)
```

Now run the test by running the following command from the project root:

```bash
./scripts/build_test.sh
```

# Adding Unit Tests (/academy/customizing-evm/08-calculator-precompile/09-unit-tests)

---
title: Adding Unit Tests
description: Learn how to add unit tests.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

Although the autogenerated units tests were useful in finding whether if the gas requirements of our functions were being fulfilled, we are yet to test the actual logic of our functions. We can add more unit tests by simply adding more mappings to the tests variable.

To start, lets define the tests that we want to write for each function within our Calculator precompile:

- `add`: check that **add(1, 2)** returns 3
- `nextTwo`: check that **nextTwo(1)** returns 2, 3
- `repeat`: check that **repeat(2, "EGS")** returns "EGSEGS"

With this in mind, lets add the three units tests to the tests variable! Below is a code excerpt which shows the three unit tests incorporated:

```go
var (
    expectedNextTwoOutcome, _ = PackNextTwoOutput(NextTwoOutput{big.NewInt(2), big.NewInt(3)})
    expectedRepeatOutcome, _  = PackRepeatOutput("EGSEGS")
    expectedAddOutcome        = common.LeftPadBytes(big.NewInt(3).Bytes(), common.HashLength)

    tests = map[string]testutils.PrecompileTest{
        "insufficient gas for add should fail": {
            Caller: common.Address{1},
            InputFn: func(t testing.TB) []byte {
                // CUSTOM CODE STARTS HERE
                // populate test input here
                testInput := AddInput{big.NewInt(1), big.NewInt(1)}
                input, err := PackAdd(testInput)
                require.NoError(t, err)
                return input
            },
            SuppliedGas: AddGasCost - 1,
            ReadOnly:    false,
            ExpectedErr: vmerrs.ErrOutOfGas.Error(),
        },
        "insufficient gas for nextTwo should fail": {
            Caller: common.Address{1},
            InputFn: func(t testing.TB) []byte {
                // CUSTOM CODE STARTS HERE
                // set test input to a value here
                // var testInput *big.Int
                testInput := big.NewInt(1)
                input, err := PackNextTwo(testInput)
                require.NoError(t, err)
                return input
            },
            SuppliedGas: NextTwoGasCost - 1,
            ReadOnly:    false,
            ExpectedErr: vmerrs.ErrOutOfGas.Error(),
        },
        "insufficient gas for repeat should fail": {
            Caller: common.Address{1},
            InputFn: func(t testing.TB) []byte {
                // CUSTOM CODE STARTS HERE
                // populate test input here
                testInput := RepeatInput{big.NewInt(1), "EGS"}
                input, err := PackRepeat(testInput)
                require.NoError(t, err)
                return input
            },
            SuppliedGas: RepeatGasCost - 1,
            ReadOnly:    false,
            ExpectedErr: vmerrs.ErrOutOfGas.Error(),
        },
        "testing add": {
            Caller: common.Address{1},
            InputFn: func(t testing.TB) []byte {
                value1 := big.NewInt(1)
                value2 := big.NewInt(2)
                testInput := AddInput{value1, value2}
                input, err := PackAdd(testInput)
                require.NoError(t, err)
                return input
            },
            SuppliedGas: AddGasCost,
            ReadOnly:    true,
            ExpectedRes: expectedAddOutcome,
        },
        "testing nextTwo": {
            Caller: common.Address{1},
            InputFn: func(t testing.TB) []byte {
                testInput := big.NewInt(1)
                input, err := PackNextTwo(testInput)
                require.NoError(t, err)
                return input
            },
            SuppliedGas: NextTwoGasCost,
            ReadOnly:    true,
            ExpectedRes: expectedNextTwoOutcome,
        },
        "testing repeat": {
            Caller: common.Address{1},
            InputFn: func(t testing.TB) []byte {
                baseString := "EGS"
                timesToRepeat := big.NewInt(2)
                input, err := PackRepeat(RepeatInput{timesToRepeat, baseString})
                require.NoError(t, err)
                return input
            },
            SuppliedGas: RepeatGasCost,
            ReadOnly:    true,
            ExpectedRes: expectedRepeatOutcome,
        },
    }
)
```


# Adding Fuzz Tests (/academy/customizing-evm/08-calculator-precompile/10-fuzz-tests)

---
title: Adding Fuzz Tests
description: Learn how to add Fuzz tests.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

Units tests are useful when comparing the outcome of a predetermined input with the expected outcome. If we wanted to check that our function works as expected for all given inputs, the only way to show this would be to test every possible input.

However, this is not possible for types such as uint256, as it would require us to test for 2^256 possible inputs. Even if we tested 1 input per second (or 2, 3, 4, 1000, etc.), this process would outlast the universe itself.

Rather than testing every possible output, we can strengthen our confidence of the expected behavior of a function by testing a random sample of inputs. By testing randomly, we can test for inputs that we wouldn't have originally thought of and are able to see how our function behaves over a range of values.

However, given that generating random inputs is not deterministic, we cannot use the tests variable itself. Rather, we will need to leverage the `TestCalculatorRun` function:

```go
// TestCalculatorEmptyRun tests the Run function of the precompile contract.
func TestCalculatorRun(t *testing.T) {
    // Run tests.
    for name, test := range tests {
        t.Run(name, func(t *testing.T) {
            test.Run(t, Module, state.NewTestStateDB(t))
        })
    }
}
```

The `TestCalculatorRun` function, by default, iterates through each unit test defined in the tests variable on runs said tests. However, we are not limited to just using `TestCalculatorRun` for the unit tests in tests. We can expand the functionality of `TestCalculatorRun` by adding our fuzz tests.

In particular, we can define the following logic for `TestCalculatorRun`:

- Iterate N number of times
- For each iteration, pick two numbers in the range from 0 to n
- After picking two random numbers, create a unit test with the two random numbers as inputs and execute said unit test

With this logic in mind, below is the code for how we would go about implementing fuzzing in `TestCalculatorRun`:

```go
// TestCalculatorRun tests the Run function of the precompile contract.
func TestCalculatorRun(t *testing.T) {
    // Run tests.
    for name, test := range tests {
        t.Run(name, func(t *testing.T) {
            test.Run(t, Module, state.NewTestStateDB(t))
        })
    }
    // Defining own test cases here
    N := 1_000
    n := new(big.Int).Exp(big.NewInt(2), big.NewInt(int64(128)), nil)

    // Fuzzing N times
    for i := 0; i < N; i++ {
        // Adding randomization test here
        randomInt1, err := rand.Int(rand.Reader, n)
        randomInt2, err := rand.Int(rand.Reader, n)
        // Expected outcome
        expectedRandOutcome := common.LeftPadBytes(big.NewInt(0).Add(randomInt1, randomInt2).Bytes(), common.HashLength)

        // Pack add input
        randTestInput := AddInput{randomInt1, randomInt2}
        randInput, err := PackAdd(randTestInput)
        require.NoError(t, err)

        randTest := testutils.PrecompileTest{
            Caller:      common.Address{1},
            Input:       randInput,
            SuppliedGas: AddGasCost,
            ReadOnly:    true,
            ExpectedRes: expectedRandOutcome,
        }

        t.Run("Testing random sum!", func(t *testing.T) {
            randTest.Run(t, Module, state.NewTestStateDB(t))
        })

    }

}
```


# Testing CalculatorPlus (/academy/customizing-evm/08-calculator-precompile/11-test-calculatorplus)

---
title: Testing CalculatorPlus
description: Learn how to test CalculatorPlus precompile.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

import { Callout } from 'fumadocs-ui/components/callout';

Now that we have gone through an example of how to test the Calculator precompile, it is time that you develop your own tests for CalculatorPlus.

Rather than explicitly tell you what test cases to write, we decided to leave that to you. After all, testing is a subjective profession - a test suite that fits one security needs might be inadequate for someone else.

However, if you want an idea for what to test for, the following are some recommendations:

- Unit Tests: create some unit tests involving values that you can come up with. Ideally, write 3-5 unit tests for each function. 
- Fuzz Tests: test more than 1000 random inputs for each function

<Callout title="Note">For both unit and fuzz tests, make sure to account for the case when the denominator is equal to 0 in `simplFrac`.</Callout>

# What are Stateful Precompiles? (/academy/customizing-evm/09-stateful-precompiles/00-intro)

---
title: What are Stateful Precompiles?
description: Learn about Stateful Precompiles in Avalanche L1 EVM.
updated: 2024-05-31
authors: [ashucoder9]
icon: Book
---

When building the MD5 and Calculator precompiles, we emphasized their behavior. We focused on building precompiles that developers could call in Solidity to perform some algorithm and then simply return a result.

However, one aspect that we have yet to explore is the statefulness of precompiles. Simply put, precompiles can store data which is persistent. To understand how this is possible, recall the interface that our precompile needed to implement:

```go
// StatefulPrecompiledContract is the interface for executing a precompiled contract
type StatefulPrecompiledContract interface {
    // Run executes the precompiled contract.
    Run(accessibleState AccessibleState, 
        caller common.Address, 
        addr common.Address, 
        input []byte, 
        suppliedGas uint64, 
        readOnly bool) 
        (ret []byte, remainingGas uint64, err error)
}
```

We also examined all parameters except for the `AccessibleState` parameter. As the name suggests, this parameter lets us access the blockchain's state. Looking at the interface of `AccessibleState`, we have the following:

```go
// AccessibleState defines the interface exposed to stateful precompile contracts
type AccessibleState interface {
    GetStateDB() StateDB
    GetBlockContext() BlockContext
    GetSnowContext() *snow.Context
}
```

Looking closer, we see that `AccessibleState` gives us access to **StateDB**, which is used to store the state of the EVM. However, as we will see throughout this section, `AccessibleState` also gives us access to other useful parameters, such as `BlockContext` and `snow.Context`.

## StateDB

The parameter we will use the most when it comes to stateful precompiles, StateDB, is a key-value mapping that maps:

- **Key**: a tuple consisting of an address and the storage key of the type Hash
- **Value**: any data encoded in a Hash, also called a word in the EVM

A Hash in go-ethereum is a 32-byte array. In this context, we do not refer to hashing in the cryptographic sense. Rather, "hashing a value" means encoding it to a hash, a 32-byte array usually represented in hexadecimal digits in Ethereum.

```go
const (
    // HashLength is the expected length of the hash
    HashLength = 32
)

// Hash represents the 32 byte of arbitrary data.
type Hash [HashLength]byte

// Example of a data encoded in a Hash: 
// 0x00000000000000000000000000000000000000000048656c6c6f20576f726c64
Below is the interface of StateDB:
// StateDB is the interface for accessing EVM state
type StateDB interface {
    GetState(common.Address, common.Hash) common.Hash
    SetState(common.Address, common.Hash, common.Hash)

    SetNonce(common.Address, uint64)
    GetNonce(common.Address) uint64

    GetBalance(common.Address) *big.Int
    AddBalance(common.Address, *big.Int)

    CreateAccount(common.Address)
    Exist(common.Address) bool

    AddLog(addr common.Address, topics []common.Hash, data []byte, blockNumber uint64)
    GetPredicateStorageSlots(address common.Address) ([]byte, bool)

    Suicide(common.Address) bool
    Finalise(deleteEmptyObjects bool)

    Snapshot() int
    RevertToSnapshot(int)
}
```

As you can see in the interface of the **StateDB**, the two functions for writing to and reading from the EVM state all work with the Hash type.

1. The function **GetState** takes an address and a Hash (the storage key) as inputs and returns the Hash stored at that slot.
2. The function **SetState** takes an address, a Hash (the storage key), and another Hash (data to be stored) as inputs.

We can also see that the **StateDB** interface allows us to read and write account balances of the native token (via GetBalance/SetBalance), check whether an account exists (via Exist), and some other methods.

## BlockContext

`BlockContext` provides info about the current block. In particular, we can get the current block number and the current block timestamp. Below is the interface of `BlockContext`:

```go
// BlockContext defines an interface that provides information to a stateful precompile about the current block.
// The BlockContext may be provided during both precompile activation and execution.
type BlockContext interface {
    Number() *big.Int
    Timestamp() *big.Int
}
```

An example of how we could leverage `BlockContext` in precompiles: *building a voting precompile that only accepts votes within a certain time frame*.

## snow.Context

`snow.Context` gives us info regarding the environment of the precompile. In particular, `snow.Context` tells us about the state of the network the precompile is hosted on. Below is the interface of `snow.Context`:

```go
// Context is information about the current execution.
// [NetworkID] is the ID of the network this context exists within.
// [ChainID] is the ID of the chain this context exists within.
// [NodeID] is the ID of this node
type Context struct {
    NetworkID uint32
    Avalanche L1ID  ids.ID
    ChainID   ids.ID
    NodeID    ids.NodeID
    PublicKey *bls.PublicKey

    XChainID    ids.ID
    CChainID    ids.ID
    AVAXAssetID ids.ID

    Log          logging.Logger
    Lock         sync.RWMutex
    Keystore     keystore.BlockchainKeystore
    SharedMemory atomic.SharedMemory
    BCLookup     ids.AliaserReader
    Metrics      metrics.OptionalGatherer

    WarpSigner warp.Signer

    // snowman++ attributes
    ValidatorState validators.State // interface for P-Chain validators
    // Chain-specific directory where arbitrary data can be written
    ChainDataDir string
}
```

# Interacting with StringStore Precompile (/academy/customizing-evm/09-stateful-precompiles/01-interacting-with-precompile)

---
title: Interacting with StringStore Precompile
description: Learn how to interact with StringStore Stateful precompile.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

Rather than understanding the statefulness of precompiles only in theory, we can also play around with an example of a stateful precompile to learn how they work in practice.

In this section, we'll interact with the **StringStore** precompile, a precompiled smart contract that stores a string.

## Checking the Genesis JSON

As part of all Avalanche Academy branches, your Precompile-EVM should include the **StringStore/** folder along with all other relevant files for StringStore to be recognized by Precompile-EVM. This includes a genesis JSON for StringStore.

Go to `tests/precompile/genesis/` and double-check that you have a `StringStore.json` folder in said directory. This JSON files will instantiate both the **SHA256** precompile and **StringStore**.

```json title="StringStore.json"
{
    "config": {
      "chainId": 99999,
      // ...
      "stringStoreConfig" : {
        "blockTimestamp": 0,
        "defaultString": "Cornell"
     }
    },
    // ...
}
```

## Building the EVM with StringStore Precompile

The **avalanche-academy-start** branch already contains the StringStore and SHA256 precompile. If you are working from that branch, you can simply use the built binary from your latest exercise without making any changes.

To verify, check if the **stringstore** directory is in your workspace and if the precompile is noted in the `plugin/main.go` file. If not, switch to the **avalanche-academy-start** branch and build the VM there.

## Start the Avalanche Network

Use the Avalanche-CLI to start the server and the network. Use the provided genesis file `stringstore.json` mentioned above when you start the network.

If all goes well, you will have successfully deployed a blockchain containing both the StringStore and SHA256 precompile.

## Connecting Core

Similar to previous chapters, navigate to the **Add Network** section in the Core Wallet. You can find the RPC URL in the Avalanche-CLI logs or by executing the command: `avalanche blockchain list --deployed`

Note: Make sure the RPC URL ends with **/rpc**. The RPC URL should look something like this: http://127.0.0.1:9650/ext/bc/P9nKPGPoAfFGkdvD3Ac6YxZieaG8ahpbR9xZosrWNPbJCzByu/rpc

Once you have added the blockchain network, switch Core Wallet to your blockchain.

## Interact through Remix

We will now load in the Solidity interface letting us interact with the **StringStore** precompile. To do this, open the link below, which will open a Remix workspace containing the StringStore precompile: [Workspace](https://remix.ethereum.org/#url=https://github.com/ava-labs/precompile-evm/blob/avalanche-academy-start/contracts/contracts/interfaces/IStringStore.sol&lang=en&optimize=false&runs=200&evmVersion=null&version=soljson-v0.8.26+commit.8a97fa7a.js)

As usual, we will need to compile our Solidity interface.

1. Click the **Solidity** logo on the left sidebar.
2. In the new page, you will see a **Compile IStringStore.sol** button. After clicking the button, a green checkmark should appear next to the Solidity logo.
3. Next, go to the **Environment** tab and select the **Injected Provider** option. If successful, a text saying **Custom [99999] Network** will appear below. If not, change your network.
4. Enter the precompile address (find it in `precompile/stringstore/module.go`) and click **At Address**.

First, we will call the `getString` function. By default, `getString` will return whatever was specified in the genesis JSON. Since we set our StringStore precompile to store the string **Cornell**, it'll return this value.

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/customizing-evm/48-THf1urUZpFdGgScCm6ZhNWVQITtsiq.png)

As you might have noticed, we can also set the string that **StringStore** stores. For example, if we wanted to change the string to Avalanche, we would type Avalanche in the box next to `setString` method, press the `setString` button, and then you would see in the Remix terminal a message displaying the success of your transaction.

If we call `getString` again, you will see that the string has been changed to Avalanche.

Congrats, you've just interacted with the stateful **StringStore** precompile 🎉

<Callout type="info">In contrast to the precompiles we have built earlier, the StringStore precompile has access to the EVM state. This way we can utilize precompile not only to perform calculations, but also persist something to the EVM state. This allows us to move even larger portions of our dApp from the solidity smart contract layer to the precompile layer. </Callout>


# Creating Counter Precompile (/academy/customizing-evm/10-stateful-counter-precompile/00-intro)

---
title: Creating Counter Precompile
description: Learn how to create a Stateful Counter Precompiles in Avalanche L1 EVM.
updated: 2024-05-31
authors: [ashucoder9]
icon: Book
---

## What We Are Building

It's time to build our first stateful precompile. In particular, we'll build a counter that keeps track of an integer. Our Counter precompile will have the following logic:

- Users are able to get the current value of the counter
- Users are able to set a new value to the counter
- Users are able to increment the value of the counter

To help you understand, we've provided a reference stateful precompile: **StringStore**. As the name suggests, StringStore stores a string that users can change. This string is stored in the EVM state.

## Overview of Steps

Compared to the process before, we must also add tests for our precompile. Here's a quick overview of the steps we'll follow:

1. Create a Solidity interface for the precompile and generate the ABI
2. Generate the precompile Go boilerplate files
3. Write the precompile code in Go with access to the EVM state
4. Set the initial state in the configurator and register the precompile
5. Add and run tests
6. Build and run your customized EVM
7. Connect Remix to your customized EVM and interact with the counter

This tutorial will help you create more complex precompiles. Let's begin!


# Create Solidity Interface (/academy/customizing-evm/10-stateful-counter-precompile/01-create-solidity-interface)

---
title: Create Solidity Interface
description: Learn how to create a solidity interface for your counter precompile.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

Now, we'll create a Solidity interface for our Stateful Precompile.

## StringStore Solidity Interface

To start, let's look at the interface of the **StringStore** precompile:

```solidity title="contracts/contracts/interfaces/IStringStore.sol"
// SPDX-License-Identifier: MIT

pragma solidity >=0.8.0;

interface IStringStore {
    function getString() external view returns (string memory value);
    function setString(string memory value) external;
}
```

As seen above, we have the following two functions defined:

1. `getString`: retreives the string from the stateful precompile
2. `setString`: sets a string in the stateful precompile

## Create Solidity Interface for Counter

Create an interface for the counter in the same directory called `ICounter.sol`. Your interface should have the following three functions declared:

1. `getCounter`: returns the counter value from the stateful precompile
2. `incrementCounter`: when called, this function increments the current counter
3. `setCounter`: takes in a value, and sets it as the counter of the stateful precompile

For any argument/return value, make sure it is named as `value`.

<Accordions>
<Accordion title="Solution">

```solidity
// SPDX-License-Identifier: MIT

pragma solidity >=0.8.0;

interface ICounter {

    function getCounter() external view returns (uint value);
    function incrementCounter() external;
    function setCounter(uint value) external;

}
```

</Accordion>
</Accordions>

## Generate the ABI

Now that we have an interface of our precompile, let's create an ABI of our Solidity interface. Open the terminal (control + \`), change to the `/contracts` directory, and run the command to compile the solidity interface to ABI:

```bash
# Move to contracts directory
cd contracts

# Compile ICounter.sol to ABI
npx solc@latest --abi ./contracts/interfaces/ICounter.sol -o ./abis --base-path . --include-path ./node_modules

# Rename 
mv ./abis/contracts_interfaces_ICounter_sol_ICounter.abi ./abis/ICounter.abi
```


# Store Data in EVM State (/academy/customizing-evm/10-stateful-counter-precompile/02-store-data-in-evm)

---
title: Store Data in EVM State
description: Learn how to store data in the EVM state.
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

Like all stateful machines, the EVM provides us with a way to save data. In particular, the EVM exposes a key-value mapping we can leverage to create stateful precompiles. The specifics of this mapping are as follows:

- Key: a tuple consisting of an address and the storage key of the type Hash
- Value: any data encoded in a Hash, also called a word in the EVM

## Storage Slots

Each storage slot is uniquely identified by the combination of an address and a storage key. To keep things organized, smart contracts and precompiles use their own address and a storage key to store data related to them. 

Look at the reference implementation `StringStore`. The storage key is defined in the second variable group in `contract.go`:

```go
// Singleton StatefulPrecompiledContract and signatures.
var (

    // StringStoreRawABI contains the raw ABI of StringStore contract.
    //go:embed contract.abi
    StringStoreRawABI string

    StringStoreABI = contract.ParseABI(StringStoreRawABI)

    StringStorePrecompile = createStringStorePrecompile()

    // Key that defines where our string will be stored
    storageKeyHash = common.BytesToHash([]byte("storageKey"))
)
```

We can use any string as our storage key. Then we convert it to a byte array and convert it to the hex representation.

> The common.BytesToHash is not hashing the string, but converting it to a 32 byte array in hex representation.

If we store multiple variables in the EVM state, we will define multiple keys here. Since we only use a single storage slot in this example, we can just call it `storageKey`.

At this point, we are not restricted in what state we can access from the precompile. We have access to the entire `stateDB` and can modify the entire EVM state including data other precompiles saved to state or balances of accounts. **This is very powerful, but also potentially dangerous**.

## Converting the Value to Hash Type

Since the StateDB only stores data of the type *Hash*, we need to convert all values to the type *Hash* before passing it to the **stateDB**.

### Converting Numbers

To convert numbers of type `big.Int`, we can utilize a function from the common package:

```go
valueHash := common.BigToHash(value)
```

Since the `big.Int` data structure already is 32-bytes long, the conversion is straightforward.

```go
// BigToHash sets byte representation of b to hash.
// If b is larger than len(h), b will be cropped from the left.
func BigToHash(b *big.Int) Hash { return BytesToHash(b.Bytes()) }
```

### Converting Strings

Converting strings is more challenging, since they are variable in length. Let's see an example:

```go
input := "Hello World"
```

To start, let's convert input into type bytes:

```go
inputAsBytes := []byte(input) 
// [72 101 108 108 111 32 87 111 114 108 100]
```

This is how you would convert input to type bytes in Go. Notice that the comment in the code snippet is the byte-representation of input, where each integer represents a byte. Right now, inputAsBytes is of length 11. We want it to be of length 32. Therefore, we pad `inputAsBytes`, adding however many zeros to the front until `inputAsBytes` has 32 integers:

```go
inputPadded := common.LeftPadBytes(inputAsBytes, common.HashLength) 
// [0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 72 101 108 108 111 32 87 111 114 108 100]
```

In Go, we would do that using the function common.LeftPadBytes, which takes the byte array to be padded and the desired length. The desired length is supplied with the common.HashLength variable, which has the value 32. As seen in the comment, inputPadded is now of length 32. 

In the next step, we convert the bytes to a Hash with the function `common.BytesToHash`:

```go
inputHash := common.BytesToHash(inputPadded) 
// 0x00000000000000000000000000000000000000000048656c6c6f20576f726c64
```

## Helper Functions

To make the code reusable and keep the precompile function clean, it makes sense to create helper functions for converting and storing the data. The first one we'll see is StoreString:

```go
// StoreString sets the value of the storage key "storageKey" in the contract storage.
func StoreString(stateDB contract.StateDB, newValue string) {
    newValuePadded := common.LeftPadBytes([]byte(newValue), common.HashLength)
    newValueHash := common.BytesToHash(newValuePadded)
    stateDB.SetState(ContractAddress, storageKeyHash, newValueHash)
}
```

`StoreString` takes in the underlying key-value mapping, known as **StateDB**, and the new value, and updates the current string stored to be the new one. `StoreString` takes care of any type conversions and state management for us. Focusing now on `setString`, defining the logic is relatively easy. All we need to do is pass in **StateDB** and our string to `StoreString`.

Thus, we have the following:

```go
func setString(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {
    if remainingGas, err = contract.DeductGas(suppliedGas, SetStringGasCost); err != nil {
        return nil, 0, err
    }
    if readOnly {
        return nil, remainingGas, vmerrs.ErrWriteProtection
    }
    // attempts to unpack [input] into the arguments to the SetStringInput.
    // Assumes that [input] does not include selector
    // You can use unpacked [inputStruct] variable in your code
    inputStruct, err := UnpackSetStringInput(input)
    if err != nil {
        return nil, remainingGas, err
    }

    // CUSTOM CODE STARTS HERE
    // Get K-V Mapping
    currentState := accessibleState.GetStateDB()

    // Set the value
    StoreString(currentState, inputStruct)

    // this function does not return an output, leave this one as is
    packedOutput := []byte{}

    // Return the packed output and the remaining gas
    return packedOutput, remainingGas, nil
}
```


# Implementing setCounter (/academy/customizing-evm/10-stateful-counter-precompile/03-implement-set-counter)

---
title: Implementing setCounter
description: Learn how to implement the setCounter method.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

Having seen how strings are stored in `StringStore`, its time for us to store integers with Counter. The thought process for this section can be defined as follows:

- Define the storage hash for our counter
- Implement `StoreCounterValue`, a helper function which acts like `StoreString` in the previous
- Implement `setCounter`

<Accordions>
<Accordion title="Solution">

```go title="contract.go"
// storageKeyHash
storageKeyHash = common.BytesToHash([]byte("counterValue"))

// StoreGreeting sets the value of the storage key in the contract storage.
func StoreCounterValue(stateDB contract.StateDB, value *big.Int) {
	// Convert uint to left padded bytes
	inputPadded := common.LeftPadBytes(value.Bytes(), 32)
	inputHash := common.BytesToHash(inputPadded)

	stateDB.SetState(ContractAddress, storageKeyHash, inputHash)
}

//setCounter sets the counter value in the contract storage.
func setCounter(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {
	if remainingGas, err = contract.DeductGas(suppliedGas, SetCounterGasCost); err != nil {
		return nil, 0, err
	}
	if readOnly {
		return nil, remainingGas, vmerrs.ErrWriteProtection
	}
	// attempts to unpack [input] into the arguments to the SetCounterInput.
	// Assumes that [input] does not include selector
	// You can use unpacked [inputStruct] variable in your code
	inputStruct, err := UnpackSetCounterInput(input)
	if err != nil {
		return nil, remainingGas, err
	}

	// CUSTOM CODE STARTS HERE

	// Get the current state
	currentState := accessibleState.GetStateDB()

	// Set the value
	StoreCounterValue(currentState, inputStruct)

	// this function does not return an output, leave this one as is
	packedOutput := []byte{}

	// Return the packed output and the remaining gas
	return packedOutput, remainingGas, nil
}
```

</Accordion>
</Accordions>

# Read Data From EVM State (/academy/customizing-evm/10-stateful-counter-precompile/04-read-date-from-evm)

---
title: Read Data From EVM State
description: Learn how to read the data from EVM state.
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

In the section about storing data in the EVM, we learned about how to store our string in the EVM State. An equally important skill is how to read data from the EVM state.

In this section, we'll learn about how to retrieve our string from the EVM state.

## Defining Helper Function

Just like with setting the string in the EVM state, there are some conversions we'll have to perform to our string. In particular, we'll need to unhash the value stored in StateDB to get our original string. Thus, our helper function can be defined as follows:

```go
// GetString returns the value of the storage key "storageKey" in the contract storage,
// with leading zeroes trimmed.
func GetString(stateDB contract.StateDB) string {
    // Get the value set at recipient
    value := stateDB.GetState(ContractAddress, storageKeyHash)
    return string(common.TrimLeftZeroes(value.Bytes()))
}
```

With our helper function defined, we can implement the logic for `getString`. This will consists of retrieving the underlying key-value mapping and then passing it to `GetString`.

```go
func getString(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {
    if remainingGas, err = contract.DeductGas(suppliedGas, GetStringGasCost); err != nil {
        return nil, 0, err
    }
    // no input provided for this function

    // CUSTOM CODE STARTS HERE

    var output string // CUSTOM CODE FOR AN OUTPUT

    currentState := accessibleState.GetStateDB()
    output = GetString(currentState)

    packedOutput, err := PackGetStringOutput(output)
    if err != nil {
        return nil, remainingGas, err
    }

    // Return the packed output and the remaining gas
    return packedOutput, remainingGas, nil
}
```

# Implementing getCounter & increment (/academy/customizing-evm/10-stateful-counter-precompile/05-implement-getcounter-increment)

---
title: Implementing getCounter & increment
description: Learn how to implement getCounter and increment.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

Having seen how to retrieve strings from the EVM state with the StoreString precompile, we are now ready to implement `getCounter`. Also, now that we are familiar with reading and writing to the EVM state, we can implement increment, which requires both read and write operations.

## Implementing getCounter

For `getCounter`, the following thought process is helpful:

- Create a helper function `GetCounterValue`, which takes in the current StateDB and returns the integer stored at the `storageKeyHash`
- In `getCounter`, get the current StateDB and pass it to `GetCounterValue`

<Accordions>
<Accordion title="Solution">

```go
// GetCounterValue gets the value of the storage key in the contract storage.
func GetCounterValue(stateDB contract.StateDB) *big.Int {
	// Get the value
	value := stateDB.GetState(ContractAddress, storageKeyHash)

	// Convert bytes to uint
	return new(big.Int).SetBytes(value.Bytes())
}

func getCounter(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {
	if remainingGas, err = contract.DeductGas(suppliedGas, GetCounterGasCost); err != nil {
		return nil, 0, err
	}
	// no input provided for this function

	// Get the current state
	currentState := accessibleState.GetStateDB()
	// Get the value set at recipient
	value := GetCounterValue(currentState)

	packedOutput, err := PackGetCounterOutput(value)
	if err != nil {
		return nil, remainingGas, err
	}

	// Return the packed output and the remaining gas
	return packedOutput, remainingGas, nil
}
```

</Accordion>
</Accordions>

## Implementing increment

For increment, the following thought process is helpful:

- Get the current StateDB and pass it to GetCounterValue
- Once you have the current counter, increment it by one
- Store the new counter with StoreCounterValue

<Accordions>
<Accordion title="Solution">

```go
func incrementCounter(accessibleState contract.AccessibleState, caller common.Address, addr common.Address, input []byte, suppliedGas uint64, readOnly bool) (ret []byte, remainingGas uint64, err error) {
	if remainingGas, err = contract.DeductGas(suppliedGas, IncrementCounterGasCost); err != nil {
		return nil, 0, err
	}
	if readOnly {
		return nil, remainingGas, vmerrs.ErrWriteProtection
	}
	// no input provided for this function

	// CUSTOM CODE STARTS HERE
	// Get the current state
	currentState := accessibleState.GetStateDB()

	// Get the value of the counter
	value := GetCounterValue(currentState)

	// Set the value
	StoreCounterValue(currentState, value.Add(value, big.NewInt(1)))

	// this function does not return an output, leave this one as is
	packedOutput := []byte{}

	// Return the packed output and the remaining gas
	return packedOutput, remainingGas, nil
}
```

</Accordion>
</Accordions>

# Setting Base Gas Fees of Your Precompile (/academy/customizing-evm/10-stateful-counter-precompile/06-setting-base-gasfees)

---
title: Setting Base Gas Fees of Your Precompile
description: Learn how to set the base gas fees of your precompile.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

Gas is used for spam prevention. If our precompile is accessible to everyone on our Avalanche L1, it is important to set the gas cost in a way that lets users economically utilize it in their apps, yet prevents spammers from spamming our blockchain with calls to the precompile.

In this section, we'll modify the default values of the gas costs of our Calculator precompile. By default, all user-defined functions have a gas cost of 1. While this is good news for the average user, allowing users to call computationally expensive functions can leave our blockchain vulnerable to Denial-of-Service (DoS) attacks. 

We can find the default gas cost values for our functions in calculator/contract.go. Following the import statements, you should see:

```go title-"calculator/contract.go"
const (
    // Gas costs for each function. These are set to 1 by default.
    // You should set a gas cost for each function in your contract.
    // Generally, you should not set gas costs very low as this may cause your network to be vulnerable to DoS attacks.
    // There are some predefined gas costs in contract/utils.go that you can use.
    AddGasCost     uint64 = 1 /* SET A GAS COST HERE */
    NextTwoGasCost uint64 = 1 /* SET A GAS COST HERE */
    RepeatGasCost  uint64 = 1 /* SET A GAS COST HERE */
)
```

The variables `AddGasCost`, `NextTwoGasCost`, and `RepeatGasCost` are the gas costs of the `add`, `nextTwo`, and `repeat` functions, respectively. As you can see, they are currently set to 1.

However, changing the gas cost is as easy as changing the values themselves. As an example, change the gas costs to 7.


# Setting ConfigKey and ContractAddress (/academy/customizing-evm/10-stateful-counter-precompile/07-set-configkey-contractaddr)

---
title: Setting ConfigKey and ContractAddress
description: Learn how to set the ConfigKey and ContractAddress, and Register the Precompile.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

## ConfigKey

Just as with the MD5 precompile in the previous section, go to the `module.go` file and set a ConfigKey.

## Contract Address

In the same file, set a ContractAddress. Choose one that has not been used by other precompiles of earlier sections.

# Initial State (/academy/customizing-evm/10-stateful-counter-precompile/08-initial-state)

---
title: Initial State
description: Setting the Initial State.
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

Throughout this chapter, we've covered storing variables in the EVM state. However, all of this was through the use of StringStore/Counter Solidity interface. An important part of stateful precompiles is the ability to initialize values stored by our precompiled contracts.

In the next few chapters, we'll see how to initialize the values of our precompiled contracts by manually setting the values or allowing for the values to be defined in the `genesis.json` file.

# Defining Default Values via Golang (/academy/customizing-evm/10-stateful-counter-precompile/09-define-default-values-via-go)

---
title: Defining Default Values via Golang
description: Learn how to set the default values of precompiled contracts using Go.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

In this section, we'll cover defining default values of precompiled contracts using Go. We'll refer to StringStore for this section.

## Configure Function

To start, go to `StringStore/module.go` and scroll to the end of the file. There, you will find the Configure function:

```go
// Configure configures [state] with the given [cfg] precompileconfig.
// This function is called by the EVM once per precompile contract activation.
// You can use this function to set up your precompile contract's initial state,
// by using the [cfg] config and [state] stateDB.
func (*configurator) Configure(chainConfig precompileconfig.ChainConfig, cfg precompileconfig.Config, state contract.StateDB, blockContext contract.ConfigurationBlockContext) error {
    config, ok := cfg.(*Config)
    if !ok {
        return fmt.Errorf("incorrect config %T: %v", config, config)
    }
    // CUSTOM CODE STARTS HERE
    return nil
}
```

Configure handles the initialization of a precompiled contract. We want to use Configure to define the default value for the string we are storing. 

But how? Configure gives us access to the StateDB (as one of the function parameters) and also lets us call any functions defined in `contract.go`. For example, if we wanted the default string to be "EGS," then we would just have to write one line of code:

```go
// Configure configures [state] with the given [cfg] precompileconfig.
// This function is called by the EVM once per precompile contract activation.
// You can use this function to set up your precompile contract's initial state,
// by using the [cfg] config and [state] stateDB.
func (*configurator) Configure(chainConfig precompileconfig.ChainConfig, cfg precompileconfig.Config, state contract.StateDB, blockContext contract.ConfigurationBlockContext) error {
    config, ok := cfg.(*Config)
    if !ok {
        return fmt.Errorf("incorrect config %T: %v", config, config)
    }
    // CUSTOM CODE STARTS HERE
    StoreString(state, "EGS")

    return nil
}
```

We have just set a default value for our precompiled contract.

# Defining Default Values via Genesis (/academy/customizing-evm/10-stateful-counter-precompile/10-define-default-values-via-genesis)

---
title: Defining Default Values via Genesis
description: Learn how to set the default values of precompiled contracts using genesis JSON file.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

In the last section, we saw how to initialize the default values of our precompiled contracts via the Configure function. While straightforward, it would be ideal for us (and developers who don't write in Go) to initialize default values via the genesis JSON. Here's how to do just that.

## Modifying config.go

The first step is to extract the value from the JSON file. Go to `config.go` and look at the Config struct:

```go
// Config implements the precompileconfig.Config interface and
// adds specific configuration for StringStore.
type Config struct {
    precompileconfig.Upgrade
    // CUSTOM CODE STARTS HERE
    // Add your own custom fields for Config here
}
```

Within the Config struct, we can find another struct: the Upgrade struct. It is not necessary to look at the definition of this struct. However, it is useful to know that this struct allows for the `blockTimestamp` key to be parsed in our `genesis.json` file. 

```go
"stringStoreConfig" : {
    "blockTimestamp": 0,
}
```

To pass in default values via the genesis JSON, we must complete the following:

- Define a key-value in the genesis JSON
- Update our Config struct so it is able to parse our new key-value

In the case of StringStore, after defining blockTimestamp, we will add another key-pair for our default string:

```go
"stringStoreConfig" : {
    "blockTimestamp": 0,
    "defaultString": "EGS"
}
```

Next, we will want to update our Config struct:

```go
type Config struct {
    precompileconfig.Upgrade
    // CUSTOM CODE STARTS HERE
    // Add your own custom fields for Config here
    DefaultString string `json:"defaultString,omitempty"`
}
```

In the above snippet, we are defining a new field of type string named `DefaultString`. With respect to its initialization, the value of `DefaultString` is derived from the JSON key `defaultString` from our genesis JSON (the value `json:"defaultString,omitempty"` tells Go to ignore the JSON field if we do not define it in our genesis JSON).

At this point, we have defined our new key-value pair in the genesis JSON and incorporated the logic so that precompile-evm can parse the new key-value.

However, one step remains. Although precompile-evm can parse the new key-value, we are not actually utilizing it anywhere. Our last-step is to update `Configure` method in `module.go` so it can read our new key-value pair.

```go
func (*configurator) Configure(chainConfig contract.ChainConfig, cfg precompileconfig.Config, state contract.StateDB, _ contract.BlockContext) error {
    config, ok := cfg.(*Config)
    if !ok {
        return fmt.Errorf("incorrect config %T: %v", config, config)
    }
    // CUSTOM CODE STARTS HERE
    StoreString(state, config.DefaultString)

    return nil
}
```


# Testing Your Precompile (/academy/customizing-evm/10-stateful-counter-precompile/11-testing-precompile-hardhat)

---
title: Testing Your Precompile
description: Learn how to test your precompile using Hardhat.
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

Just like with the Calculator precompile, we want to test the functionality of our precompile to make sure it behaves as intended.

Although we can write tests in Go, this is not the only way we can test our precompile. We can leverage Hardhat, a popular smart contract testing framework, for testing.

In this section, we'll cover writing the smart contract component of our tests and setting up our testing environment so that precompile-evm can execute these tests for us.

## Structure of Testing with Hardhat

For `StringStore`, we'll need to complete the following tasks in order to leverage Hardhat:

1. Define the Genesis JSON file we want to use for testing
2. Tell precompile-evm what Hardhat script to use to test `StringStore` 
3. Write the smart contract that will hold the test cases for us
4. Write the actual script that will execute the Hardhat tests for us

## Defining the Genesis JSON

The easiest part of this tutorial, we will need to define the genesis state of our testing environment. For all intents and purposes, you can copy the genesis JSON that you used in the Defining Default Values section and paste it in `precompile-evm/tests/precompile/genesis`, naming it `StringStore.json` (it is important that you name the genesis file the name of your precompile).

## Telling Precompile-EVM What To Test

The next step is to modify `suites.go` and update the file so that precompile-evm can call the Hardhat tests for StringStore. Go to `precompile-evm/tests/precompile/solidity` and find `suites.go`. Currently, your file should look like the following:

```go title="suites.go"
// Copyright (C) 2019-2023, Ava Labs, Inc. All rights reserved.
// See the file LICENSE for licensing terms.
// Implements solidity tests.
package solidity

import (
    "context"
    "time"

    "github.com/ava-labs/subnet-evm/tests/utils"
    ginkgo "github.com/onsi/ginkgo/v2"
)

var _ = ginkgo.Describe("[Precompiles]", ginkgo.Ordered, func() {
    utils.RegisterPingTest()
    // Each ginkgo It node specifies the name of the genesis file (in ./tests/precompile/genesis/)
    // to use to launch the subnet and the name of the TS test file to run on the subnet (in ./contract-examples/tests/)

    // ADD YOUR PRECOMPILE HERE
    /*
        ginkgo.It("your precompile", ginkgo.Label("Precompile"), ginkgo.Label("YourPrecompile"), func() {
            ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
            defer cancel()
​
            // Specify the name shared by the genesis file in ./tests/precompile/genesis/{your_precompile}.json
            // and the test file in ./contracts/tests/{your_precompile}.ts
            // If you want to use a different test command and genesis path than the defaults, you can
            // use the utils.RunTestCMD. See utils.RunDefaultHardhatTests for an example.
            utils.RunDefaultHardhatTests(ctx, "your_precompile")
        })
    */
})
```

If you view the comments generated, you will already see a general structure for how we can declare our tests for precompiles. Let's take this template and use it to declare the tests for StringStore!

```go title="suites.go"
// Copyright (C) 2019-2023, Ava Labs, Inc. All rights reserved.
// See the file LICENSE for licensing terms.
// Implements solidity tests.
package solidity

import (
    "context"
    "time"

    "github.com/ava-labs/subnet-evm/tests/utils"
    ginkgo "github.com/onsi/ginkgo/v2"
)

var _ = ginkgo.Describe("[Precompiles]", ginkgo.Ordered, func() {
    utils.RegisterPingTest()
    // Each ginkgo It node specifies the name of the genesis file (in ./tests/precompile/genesis/)
    // to use to launch the subnet and the name of the TS test file to run on the subnet (in ./contract-examples/tests/)

    // ADD YOUR PRECOMPILE HERE
    /*
        ginkgo.It("your precompile", ginkgo.Label("Precompile"), ginkgo.Label("YourPrecompile"), func() {
            ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
            defer cancel()
​
            // Specify the name shared by the genesis file in ./tests/precompile/genesis/{your_precompile}.json
            // and the test file in ./contracts/tests/{your_precompile}.ts
            // If you want to use a different test command and genesis path than the defaults, you can
            // use the utils.RunTestCMD. See utils.RunDefaultHardhatTests for an example.
            utils.RunDefaultHardhatTests(ctx, "your_precompile")
        })
    */

    ginkgo.It("StringStore", ginkgo.Label("Precompile"), ginkgo.Label("StringStore"), func() {
        ctx, cancel := context.WithTimeout(context.Background(), time.Minute)
        defer cancel()

        utils.RunDefaultHardhatTests(ctx, "StringStore")
    })
})
```

Again, the naming conventions are important. We recommend you use the same name as your precompile whenever possible.

## Defining Test Contract

In contrast to using just Go, Hardhat allows us to test our precompiles using Solidity.

To start, create a new file called `StringStoreTest.sol` in `precompile-evm/contract/contracts`. We can start defining our file by including the following:

```solidity title="StringStoreTest.sol"
// SPDX-License-Identifier: MIT
pragma solidity >= 0.8.0;

import "ds-test/src/test.sol"; 
import {IStringStore} from "../contracts/interfaces/IStringStore.sol";
```

As of right now, there are two important things to note.

We are first importing `test.sol`, a testing file that includes a range of assertion functions to assert that our outputs are as expected. In particular, these assertion functions are methods of the DSTest contract.

Next, we are importing the interface of the StringStore precompile that we want to test.

With this in mind, let's fill in the rest of our test file:

```solidity title="StringStoreTest.sol"
contract StringStoreTest is DSTest {

    IStringStore stringStore = IStringStore(0x0300000000000000000000000000000000000005);

    function step_getString() public {
        assertEq(stringStore.getString(), "Cornell");
    }

    function step_getSet() public {
        string memory newStr = "Apple";
        stringStore.setString(newStr);
        assertEq(stringStore.getString(), newStr);
    }
}
```

In the contract `StringStoreTest`, we are inheriting the DSTest contract so that we can leverage the provided assertion functions. Afterward, we are declaring the variable stringStore so that we can directly call the StringStore precompile. Next, we have the two testing functions.

Briefly looking at the logic of each test function:

- `step_getString`: We are testing that the getString function returns the default string defined in the genesis JSON (in this example, the default string is set to "Cornell")
- `step_getSet`: We are assigning a new string to our precompile and making sure that setString does so correctly

We now want to note the following two details regarding Solidity test functions in Hardhat:

- Any test functions that you want to be called must start with the prefix "step"
- The assertion function you use to check your outputs is `assertEq`

With our Solidity test contract defined, let's write actual Hardhat script! 

## Writing Your Hardhat Script

To start, go to `precompile-evm/contracts/test` and create a new file called `StringStore.ts`. It is important to name your TypeScript file the same name as your precompile. Here are the steps to take when defining our Hardhat script:

1. Specify the address at which our precompile is located
2. Deploy our testing contract so that we can call the test functions
3. Tell Hardhat to execute said test functions

To make our lives even easier, Avalanche L1-EVM (a library that Precompile-EVM leverages) has helper functions to call our test functions simply by specifying the names of the test functions. You can find the helper functions here: https://github.com/ava-labs/subnet-evm/blob/master/contracts/test/utils.ts.

In the end, our testing file will look as follows:

```ts title="StringStore.ts"
// (c) 2019-2022, Ava Labs, Inc. All rights reserved.
// See the file LICENSE for licensing terms.

import { ethers } from "hardhat"
import { test } from "@avalabs/subnet-evm-contracts"
import { factory } from "typescript"

const STRINGSTORE_ADDRESS = "0x0300000000000000000000000000000000000005"

describe("StringStoreTest", function() {
    this.timeout("30s")

    beforeEach("Setup DS-Test", async function () {
        const stringStorePromise = ethers.getContractAt("IStringStore", STRINGSTORE_ADDRESS)

        return ethers.getContractFactory("StringStoreTest").then(factory => factory.deploy())
        .then(contract => {
          this.testContract = contract
          return contract.deployed().then(() => contract)
        })
    })

    test("Testing get function", "step_getString")

    test("Testing get and set function", "step_getSet")
})
```

## Running Your Hardhat Test

To run your HardHat tests, first change to the root directory of precompile-evm and run the following command:

```bash
./scripts/build.sh
```

Afterward, run the following command:

```bash
GINKGO_LABEL_FILTER=StringStore ./scripts/run_ginkgo.sh
```

The variable `GINKGO_LABEL_FILTER` simply tells precompile-evm which tests suite from `suites.go` to execute. Execute the `StringStore` test suite.

However, if you have multiple precompiles to test, set `GINKGO_LABEL_FILTER` equal to "Precompile." You should see something like the following:

```bash title="Combined output"
  StringStoreTest
    ✓ Testing get function (4126ms)
    ✓ Testing get and set function (4070ms)

  2 passing (12s)

  < Exit [It] StringStore - /Users/Rodrigo.Villar/go/src/github.com/ava-labs/precompile-evm/tests/precompile/solidity/suites.go:40 @ 07/19/23 15:37:03.574 (16.134s)
• [16.134 seconds]
------------------------------
[AfterSuite] 
/Users/Rodrigo.Villar/go/pkg/mod/github.com/ava-labs/subnet-evm@v0.5.2/tests/utils/command.go:85
  > Enter [AfterSuite] TOP-LEVEL - /Users/Rodrigo.Villar/go/pkg/mod/github.com/ava-labs/subnet-evm@v0.5.2/tests/utils/command.go:85 @ 07/19/23 15:37:03.575
  < Exit [AfterSuite] TOP-LEVEL - /Users/Rodrigo.Villar/go/pkg/mod/github.com/ava-labs/subnet-evm@v0.5.2/tests/utils/command.go:85 @ 07/19/23 15:37:03.575 (0s)
[AfterSuite] PASSED [0.000 seconds]
------------------------------

Ran 2 of 3 Specs in 50.822 seconds
SUCCESS! -- 2 Passed | 0 Failed | 0 Pending | 1 Skipped
PASS
```

Congrats, you can now write Hardhat tests for your stateful precompiles!


# Build Your Precompile (/academy/customizing-evm/10-stateful-counter-precompile/12-build-your-precompile)

---
title: Build Your Precompile
description: Learn how to build and run your precompile as a custom EVM blockchain.
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

## Build Your Custom VM

There's a simple build script in the Precompile-EVM we can utilize to build. First, make sure you are in the root folder of you Precompile-EVM:

```bash
cd $GOPATH/src/github.com/ava-labs/precompile-evm
```

Then run the command to initiate the build script:

```bash
./scripts/build.sh
```

If you do not see any error, the build was successful.

## Run a Local Network with Your Custom VM

You can run you customized Precompile-EVM by using the Avalanche CLI.

First, create the configuration for your blockchain with custom VM.

```bash
avalanche blockchain create myblockchain --custom --vm $AVALANCHEGO_PLUGIN_PATH/srEXiWaHuhNyGwPUi444Tu47ZEDwxTWrbQiuD7FmgSAQ6X7Dy --genesis ./.devcontainer/genesis-example.json
```

<Callout type="info">
Make sure you replace the binary name with the actual binary name of your Precompile-EVM, and genesis file with the actual path to your genesis file.
</Callout>

Next, launch the Avalanche L1 with your custom VM:

```bash
avalanche blockchain deploy myblockchain
```

After around 1 minute the blockchain should have been created and some more output should appear in the terminal. You'll also see the RPC URL of your blockchain in the terminal.

# Standards (/academy/encrypted-erc/01-what-is-a-digital-asset/01-digital-assets-overview)

---
title: Standards
description: Learn about ERC-20, ERC-721, and ERC-1155 in the Avalanche ecosystem, starting from the concept of digital assets.
updated: 2025-09-02
authors: [alejandro99so]
icon: Coins
---

A **digital asset** is any representation of value, rights, or property stored and transacted on a blockchain. These can range from cryptocurrencies and stablecoins to in-game items, tokenized real estate, and certificates.  

On Avalanche, most digital assets are created and managed on the **C-Chain**, which is fully compatible with the **EVM (Ethereum Virtual Machine)**. This compatibility allows Avalanche to use the same token standards as the broader EVM ecosystem while adding **high throughput, sub-second finality, and low fees**.  

Because of this, developers building on Avalanche, whether deploying to **C-Chain** for **mainnet** or **Fuji** (testnet), use **standards** to ensure their tokens are interoperable with wallets, marketplaces, and decentralized applications. These standards define the rules for how tokens behave, how they are transferred, and how they are recognized across different platforms.

The three most widely used token standards in the EVM ecosystem, and therefore in Avalanche, are:

---

## ERC-20: Fungible Token Standard
The ERC-20 standard defines fungible tokens where each unit is identical.

**Key Characteristics**
- Fungible: Each token has the same value as any other token of the same contract.
- Divisible: Commonly 18 decimal places for microtransactions.
- Highly interoperable with all EVM-compatible tools and dApps.
- Extremely low-cost transfers on Avalanche due to low gas fees.

**Common Functions**
- `transfer(address to, uint amount)`
- `approve(address spender, uint amount)`
- `transferFrom(address from, address to, uint amount)`
- `balanceOf(address account)`

---

## ERC-721: Non-Fungible Token Standard
The ERC-721 standard defines unique, non-fungible tokens (NFTs).

**Key Characteristics**
- Each token has a unique `tokenId`.
- Supports metadata for traits, images, descriptions.
- Provides immutable proof of ownership.

**Common Functions**
- `ownerOf(uint256 tokenId)`
- `safeTransferFrom(address from, address to, uint256 tokenId)`
- `tokenURI(uint256 tokenId)`

---

## ERC-1155: Multi-Token Standard
The ERC-1155 standard supports multiple token types (fungible, non-fungible, and semi-fungible) in one contract.

**Key Characteristics**
- Can store and manage different asset types in a single contract.
- Supports batch operations to save gas.
- Flexible for gaming and metaverse applications.

**Common Functions**
- `safeTransferFrom(address from, address to, uint256 id, uint256 amount, bytes data)`
- `safeBatchTransferFrom(address from, address to, uint256[] ids, uint256[] amounts, bytes data)`
- `balanceOf(address account, uint256 id)`

---

## Standards Comparison Table (Avalanche Context)

| Feature | ERC-20 | ERC-721 | ERC-1155 |
|---------|--------|---------|----------|
| Token Type | Fungible | Non-fungible | Fungible + Non-fungible |
| Uniqueness | No | Yes | Optional per token ID |
| Metadata | No | Yes (`tokenURI`) | Yes |
| Batch Transfers | No | No | Yes |
| Typical Use Cases on Avalanche | Stablecoins, governance, utilities | NFTs, in-game items, certificates | Gaming, collectibles, asset baskets |
| Gas Efficiency on Avalanche | High | Moderate | High (batch) |
| Privacy | None | None | None |
| Interoperability | Very high | High | Medium–High |

---

These standards are the foundation for asset creation and interaction in Avalanche’s C-Chain Mainnet and Fuji (Testnet). They allow developers to build interoperable applications and ensure that tokens can be used across different wallets, marketplaces, and decentralized protocols.  

In the **next section**, we will explore the **current uses of these standards in blockchain**, with real examples from Avalanche’s ecosystem, including DeFi platforms, NFT marketplaces, gaming L1, and tokenized real-world assets.


# Current Uses in Blockchain (/academy/encrypted-erc/01-what-is-a-digital-asset/02-current-uses)

---
title: Current Uses in Blockchain
description: Explore how ERC-20, ERC-721, and ERC-1155 standards are applied in the Avalanche ecosystem.
updated: 2025-09-02
authors: [alejandro99so]
icon: Activity
---

In the previous section, we covered the main **token standards** used on Avalanche: ERC-20, ERC-721, and ERC-1155. Now, let’s explore **how these standards are applied today** in the Avalanche ecosystem across the C-Chain **Mainnet**, **Fuji (Testnet)**, and **custom L1s**.

---

## ERC-20: Fungible Token Use Cases

**On Avalanche C-Chain Mainnet**
- **Stablecoins**:  
  USDT: Widely used for DeFi protocols, payments, and trading pairs.  
  USDC: Popular for lending, liquidity provision, and cross-chain settlements.  
- **Native Avalanche Tokens**:  
  WAVAX: Wrapped AVAX used for liquidity pools, lending markets, and DEX operations.  
- **Governance Tokens**:  
  JOE: Token powering governance and incentives in Trader Joe.  
  QI: Governance token for Benqi lending and liquid staking platform.

**On L1 Deployments**
- **Custom Ecosystem Tokens**: L1 projects can issue ERC-20 tokens for payments, in-game economies, or DeFi services, with full control over tokenomics.

**On Avalanche C-Chain Fuji (Testnet)**
- Developers test token logic, minting, and burning before deploying to C-Chain or an L1, avoiding the cost of mainnet errors.

---

## ERC-721: Non-Fungible Token Use Cases

**On Avalanche C-Chain Mainnet**
- **NFT Marketplaces**:  
  Kalao: Marketplace for art, gaming, and utility NFTs.  
  NFTrade: Cross-chain NFT marketplace supporting Avalanche.  
- **In-Game Unique Assets**:  
  Gaming NFTs: Rare weapons, characters, and skins in Avalanche C-Chain-native games.

**On L1 Deployments**
- **Project-Specific Collections**: L1s can issue NFTs for branding, game achievements, or membership systems, keeping transactions isolated from C-Chain congestion.
- **Sports & Entertainment**: FIFA+ Collect: Official FIFA digital collectibles platform on L1 Avalanche, featuring historic moments, iconic goals, and tournament highlights.  

**On Avalanche C-Chain Fuji (Testnet)**
- Used to test metadata integration, marketplace listings, and batch minting.

---

## ERC-1155: Multi-Token Standard Use Cases

**On Avalanche C-Chain Mainnet**
- **Gaming Projects**:  
  Crabada: Combines fungible resources (minerals, tokens) with unique NFT characters in one contract.  
- **Collectible Platforms**:  
  Multi-series collections: Managed without deploying new contracts for each.

**On L1 Deployments**
- **Metaverse Economies**: L1s can host both in-game currencies and unique items in one ERC-1155 contract, benefiting from low latency and high scalability.

**On Avalanche C-Chain Fuji (Testnet)**
- Testing batch transfers, multi-asset minting, and marketplace integrations before L1 or C-Chain Mainnet launch.

---

## Observations from Avalanche’s Current Uses

- **Low Fees Enable Microtransactions**: The cost-efficiency of Avalanche makes even small-value ERC-20 and ERC-1155 transfers practical.  
- **L1s Enable Asset Isolation**: Projects with heavy transaction loads can launch their own L1 to keep asset operations unaffected by C-Chain activity.  
- **Fuji Testnet is a Critical Step**: Almost every major Avalanche project tests token standards on Fuji before going live.  
- **Bridging Expands Liquidity**: Avalanche supports assets from other EVM networks, extending utility and user reach.

---

In the **next section**, we will analyze **the limits companies face when using these standards**, focusing on challenges like **privacy, compliance, and scalability** and set the stage for introducing **privacy-focused solutions like eERC**.


# Limitations of Current Standards (/academy/encrypted-erc/01-what-is-a-digital-asset/03-limitations)

---
title: Limitations of Current Standards
description: Challenges companies face when using ERC-20, ERC-721, and ERC-1155 on Avalanche.
updated: 2025-09-02
authors: [alejandro99so]
icon: Book
---

The ERC-20, ERC-721, and ERC-1155 standards have become the backbone of asset creation and exchange on Avalanche’s C-Chain, Fuji Testnet, and custom L1s. However, while they ensure interoperability and simplicity, they also present **important limitations** that companies and developers must address when building real-world solutions.

---

## 1. Privacy Limitations

All three standards: ERC-20, ERC-721, and ERC-1155, operate on **transparent ledgers**.  
- **Balances are public**: Anyone can view wallet holdings.  
- **Transactions are public**: Every transfer amount and counterparty is visible.  
- **Asset ownership is public**: For ERC-721 and ERC-1155, ownership history and metadata are fully transparent.  

This transparency is useful for auditability but problematic for:  
- Regulated financial institutions.  
- Enterprises managing sensitive transactions.  
- Use cases requiring trade secrecy or personal data protection.  

---

## 2. Compliance Challenges

Avalanche provides speed and low costs, but these standards **do not include compliance tools by default**.  
- No built-in **selective disclosure** for regulators or auditors.  
- No native mechanism to **restrict transactions** based on jurisdiction.  
- Compliance features must be built as **custom layers**, increasing development cost and complexity.

---

## 3. Scalability Concerns

While Avalanche’s architecture solves many scaling issues, token standards still introduce some constraints:  
- **ERC-20 and ERC-721**: Each transfer is a separate transaction, which can be inefficient for high-volume operations.  
- **ERC-721**: One contract per collection increases deployment and maintenance overhead.  
- **ERC-1155**: More efficient, but not all dApps and marketplaces fully support it yet.

---

## 4. Asset Management Limitations

- **Single-purpose contracts**: ERC-20 can only handle one fungible token per contract.  
- **No native multi-asset governance**: ERC-721 collections and ERC-20 tokens require separate governance or management systems.  
- **Limited metadata security**: Metadata for NFTs is often stored off-chain and can be altered unless proper safeguards are in place.

---

## Summary Table — Key Limitations on EVM Blockchains

| Standard | Privacy | Compliance | Scalability | Asset Management |
|----------|---------|------------|-------------|------------------|
| ERC-20   | No privacy, public balances & transfers | No built-in compliance | One transfer per transaction | Single token per contract |
| ERC-721  | No privacy, public ownership & metadata | No built-in compliance | One contract per collection | Separate governance per collection |
| ERC-1155 | No privacy, public ownership & metadata | No built-in compliance | Batch transfers supported, but partial ecosystem support | Multi-asset capable but complex |

---

These limitations do not prevent successful deployments, but they **create barriers for industries that require privacy, compliance-readiness, and advanced asset control**.

In the **next section**, we will explore **Real Privacy**: how much privacy blockchain truly offers, why compliance is critical, and how privacy-focused standards like **eERC** can address these challenges in the Avalanche ecosystem.


# How Private is the Blockchain? (/academy/encrypted-erc/02-real-privacy/01-how-private-is-the-blockchain)

---
title: How Private is the Blockchain?
description: Understanding the level of privacy in Avalanche and the difference between transparency and confidentiality.
updated: 2025-09-02
authors: [alejandro99so]
icon: Eye
---

One of the most common misconceptions about blockchain is that it is **private**.  
In reality, on Avalanche, whether you operate on the C-Chain **Mainnet**, **Fuji (Testnet)**, or a custom L1, the blockchain is **transparent by design**. Every transaction is recorded in a public ledger and can be inspected by anyone with the right tools.

---

## Transparency in Avalanche

- **Every transaction is public**: Transfers, mints, burns, and contract interactions are visible in block explorers like [SnowTrace](https://snowtrace.io).  
- **Balances are public**: Anyone can check the token holdings of any address by querying the blockchain.  
- **Ownership history is public**: For NFTs (ERC-721 and ERC-1155), all past owners are permanently recorded.  

This transparency is valuable for:
- **Auditability**: Anyone can verify that a transaction took place and check the exact amounts.  
- **Trustless systems**: No need for a central authority to confirm balances or transaction histories.  
- **Security monitoring**: Easier to detect suspicious activity or exploits in real time.

---

## Pseudonymity vs Anonymity

Avalanche, like other EVM-compatible blockchains, is **pseudonymous**, not truly anonymous.  
- **Pseudonymity**: Users are identified by their public address (e.g., `0x1234...abcd`), but not by their real name.  
- **Linkability**: Once an address is tied to an identity (via KYC, exchange deposits, or off-chain information), all past and future activity from that address can be analyzed.  
- **Behavioral profiling**: Patterns in interactions (like dApps used, tokens traded, or NFTs purchased) can reveal insights about the owner.

---

## Confidentiality Limitations

While transparency is useful for verification, it creates significant limitations for certain use cases:
- **Business transactions**: Competitors can see volumes, counterparties, and frequency of payments.  
- **Personal privacy**: Anyone can track your activity and build a profile of your blockchain behavior.  
- **Regulated industries**: Some sectors require confidentiality for compliance (e.g., healthcare, finance).

---

## Example on Avalanche C-Chain

If a company pays 50 employees using an ERC-20 token on Avalanche C-Chain:
- The **amount**, **date**, and **recipient address** of each payment will be public.  
- A competitor or third party could track salary patterns, hiring trends, or even link addresses to individuals.

---

Avalanche’s transparent design ensures trust and auditability, but **it does not provide native confidentiality** for balances, transaction amounts, or metadata.  
In the **next section**, we will explore **Compliance**, why privacy alone is not enough, and how companies must align with regulatory requirements when designing blockchain solutions.


# Compliance (/academy/encrypted-erc/02-real-privacy/02-compliance)

---
title: Compliance
description: Why regulatory alignment matters for privacy tokens on Avalanche.
updated: 2025-09-02
authors: [alejandro99so]
icon: Scale
---

Privacy is not the only requirement for enterprise-grade blockchain solutions, **compliance** is equally critical.  
On Avalanche, whether you deploy to C-Chain **Mainnet**, **Fuji (Testnet)**, or a custom L1, tokens must often meet **regulatory obligations** to operate legally in certain jurisdictions or industries.

---

## Why Compliance Matters

In finance, healthcare, gaming, and government, compliance is not optional, it is enforced through regulations like:
- **KYC/AML** (Know Your Customer / Anti-Money Laundering): Identifying and verifying participants to prevent illegal activity.
- **Jurisdictional restrictions**: Blocking access from certain regions due to sanctions or laws.
- **Data protection laws**: GDPR (EU), HIPAA (US), and other frameworks require handling sensitive data in specific ways.

---

## Challenges with Current Token Standards

Standard ERC-20, ERC-721, and ERC-1155 implementations on Avalanche offer **no built-in compliance tools**:
- No **whitelisting** or **blacklisting** capabilities at the protocol level.
- No **selective disclosure**: you cannot show transaction details only to authorized parties while hiding them from the public.
- No **transaction-level restrictions** to enforce rules automatically.

As a result, compliance must be built as a **custom layer**, which:
- Increases development and auditing costs.
- Introduces potential security risks if not implemented correctly.
- Creates inconsistency between projects, making interoperability harder.

---

## The Compliance–Privacy Balance

True privacy on Avalanche must still allow **authorized oversight**:
- **Auditor access**: Regulators, tax authorities, or compliance officers should be able to review specific transactions without making them public.
- **Selective decryption**: Only authorized entities can view transaction amounts and counterparties.
- **Revocable permissions**: The ability to update who has access without redeploying the entire token contract.

---

## Example in the Avalanche Ecosystem

Imagine an **L1** created for a private lending network:
- Loans are issued in a **privacy-enabled token** to protect borrower data.
- Regulators need to verify the amounts, interest rates, and repayment schedules.
- Without compliance features, the project must either make all data public (losing privacy) or create a parallel off-chain audit system (increasing complexity).

---

In the **next section**, we will explore **Necessities Solved with Privacy**, real-world scenarios where privacy is not just a “nice to have,” but a **critical requirement** for operations, security, and compliance.


# Necessities Solved with Privacy (/academy/encrypted-erc/02-real-privacy/03-necessities-solved-with-privacy)

---
title: Necessities Solved with Privacy
description: Real-world scenarios where privacy on Avalanche is essential.
updated: 2025-09-02
authors: [alejandro99so]
icon: Lock
---

Privacy on Avalanche is not only about hiding information, it’s about **unlocking use cases that would otherwise be impossible** in a fully transparent blockchain environment.  
By combining confidentiality with auditability, privacy-enabled tokens can meet both **business** and **regulatory** requirements.

---

## 1. Sensitive Transactions

Certain payments and transfers must remain confidential to protect business interests and personal security:
- **Enterprise payments**: Salaries, supplier payments, and investment deals that should not be visible to competitors.
- **Strategic asset moves**: Acquisitions, treasury management, or cross-company settlements.
- **Personal financial data**: Protecting individuals from profiling or targeted attacks based on on-chain activity.

---

## 2. Enterprise Use

Organizations building on Avalanche, whether on **C-Chain** or a dedicated **L1**, may require privacy for:
- **Internal token economies**: Reward points, access tokens, or employee incentives where transaction history should remain private.
- **Corporate NFT strategies**: Membership passes, certifications, or asset ownership records that could reveal strategic information.
- **Supply chain confidentiality**: Tracking goods on-chain without exposing trade volumes and partner relationships.

---

## 3. Regulated Financial Products

Financial institutions can benefit from privacy without sacrificing compliance:
- **Tokenized securities or bonds**: Keeping investor details and trade sizes private while allowing regulator access.
- **Private lending protocols**: Concealing borrower data while enabling repayment verification.
- **Confidential DeFi**: Yield farming or liquidity provision without revealing exact positions to the public.

---

## Why Privacy is a Business Enabler

Without privacy, many organizations avoid blockchain entirely due to:
- **Risk of data exposure**: Competitors analyzing public activity to gain market advantage.
- **Regulatory conflicts**: Inability to comply with privacy laws while using transparent ledgers.
- **Security concerns**: Public transaction data can make users targets for scams or hacks.

By enabling **selective transparency** — where only authorized entities can see sensitive details, Avalanche projects can:
- Attract enterprise and institutional adoption.
- Expand into regulated markets.
- Create safer, more competitive ecosystems.

---

In the **next section**, we will introduce **Encrypted Tokens**, starting with **eERC (Encrypted ERC)** — Avalanche’s privacy-focused token standard that brings **encrypted balances, private transfers, and compliance-ready auditability** to the EVM ecosystem.


# What Kind of Privacy Does eERC Provide? (/academy/encrypted-erc/03-encrypted-tokens/01-privacity-eerc)

---
title: What Kind of Privacy Does eERC Provide?
description: Understanding the privacy features of eERC in the Avalanche ecosystem.
updated: 2025-09-02
authors: [alejandro99so]
icon: Key
---

In the previous section, we explored why privacy is a critical enabler for blockchain adoption in industries like finance, enterprise, and gaming.  
Now we will focus on **eERC (Encrypted ERC)**, Avalanche’s encrypted token standard and see the exact kind of privacy it delivers on C-Chain **Mainnet**, **Fuji(Testnet)**, and **custom L1 deployments**.

---

## Encrypted Balances
- Balances are **fully encrypted** on-chain.  
- Only the token holder (and authorized auditor) can see the actual balance.  
- Prevents competitors, analysts, or malicious actors from tracking your holdings.

---

## Private Transaction Amounts
- Transfer amounts are encrypted and not visible on public explorers like SnowTrace.  
- Observers can see that a transfer occurred but not **how much** was sent.  
- Uses **zero-knowledge proofs** to validate transactions without revealing amounts.

---

## Auditor-Ready Privacy
- Built-in **Auditability Module** allows authorized parties to decrypt specific transactions.  
- Access can be **revoked or rotated** without redeploying the contract.  
- Enables compliance with financial regulations while maintaining user privacy.

---

## EVM Compatibility
- Works seamlessly on Avalanche C-Chain Mainnet, Fuji (Testnet), and custom L1s without protocol changes.  
- Fully compatible with existing EVM smart contract tooling.  
- Developers can integrate using the **EncryptedERC Repository**.

---

## Flexible Deployment Modes
- **Standalone Mode**: Fully private token from creation, with optional hidden total supply.  
- **Converter Mode**: Wraps an existing ERC-20 into an encrypted token, enabling private transfers while preserving the ability to unwrap it back to ERC-20.

---

## Example Use Cases

**Confidential DeFi**  
- Private yield farming, liquidity provision, and staking allocations.

**Enterprise Payments**  
- Payroll systems where salaries are encrypted but verifiable to auditors.  
- Supplier payments that conceal exact deal sizes.

**Private Asset Management**  
- Managing tokenized real-world assets without revealing portfolio composition.  
- In-game transactions in private gaming economies.

---

In the **next section**, we will compare **ERC-20 vs eERC** to see exactly how these standards differ in privacy, compliance, and deployment options.


# ERC-20 vs eERC (/academy/encrypted-erc/03-encrypted-tokens/02-comparison)

---
title: ERC-20 vs eERC
description: Comparing traditional ERC-20 tokens with eERC in the Avalanche ecosystem.
updated: 2025-09-02
authors: [alejandro99so]
icon: Table
---

In the previous section, we learned what kind of privacy **eERC** offers on Avalanche.  
Now, let’s compare it directly to **ERC-20**, the most widely used fungible token standard in the EVM ecosystem.

---

## Key Differences

| Feature | ERC-20 | eERC (Encrypted ERC) |
|---------|--------|----------------------|
| **Balance Visibility** | Public: anyone can see wallet balances on-chain. | Private: balances are encrypted, visible only to the holder and authorized auditors. |
| **Transaction Amount Visibility** | Public: amounts are visible in every transfer. | Private: transfer amounts are encrypted and hidden from the public. |
| **Privacy Technology** | None: all data is transparent. | Zero-knowledge proofs (zk-SNARKs) + homomorphic encryption. |
| **Compliance Options** | Requires custom solutions for compliance and auditability. | Built-in Auditability Module allows selective decryption for authorized auditors. |
| **Blockchain Compatibility** | Works on any EVM-compatible chain. | Works on any EVM-compatible chain, including Avalanche C-Chain Mainnet, Fuji (Testnet), and custom L1s. |
| **Gas Efficiency** | Very efficient for transfers and approvals. | Slightly higher cost due to encryption and proof verification, but optimized for Avalanche’s low fees. |
| **Modes Available** | Single implementation. | Standalone Mode and Converter Mode for different privacy needs. |
| **Total Supply Visibility** | Public by default. | Concealed in Standalone Mode (optional in Converter Mode). |
| **Use Cases** | Public tokens, open DeFi, governance tokens. | Confidential DeFi, enterprise payments, private RWA, regulated financial use. |

---

## Summary

While **ERC-20** remains the foundation for most tokens in the EVM ecosystem, it offers no privacy features.  
**eERC**, on the other hand, is designed for scenarios where confidentiality, compliance, and selective transparency are required, making it ideal for enterprise, regulated markets, and advanced DeFi protocols on Avalanche.

---

In the **next section**, we will explore the **Technology Behind eERC**, understanding the cryptographic tools, on-chain components, and modes of operation that make this privacy possible.


# Technology Behind eERC (/academy/encrypted-erc/03-encrypted-tokens/03-technology-behind)

---
title: Technology Behind eERC
description: Understanding the cryptographic tools and architecture that power eERC on Avalanche.
updated: 2025-09-02
authors: [alejandro99so]
icon: Cpu
---

The **eERC (Encrypted ERC)** standard combines modern cryptography with Avalanche’s high-performance infrastructure to deliver **confidential transactions** while remaining compatible with the EVM ecosystem.  
In this section, we will break down the key technologies and architecture that make this possible.

---

## Core Privacy Technologies

### 1. Zero-Knowledge Proofs (zk-SNARKs)
- Used to **prove** that a transaction is valid without revealing its details.
- Ensures the sender has enough balance and the transaction respects the rules, without disclosing amounts or balances.
- Highly gas-efficient when deployed on Avalanche due to its low base fees.

### 2. Homomorphic Encryption
- Allows operations on encrypted values **without decrypting them**.
- Enables balance updates and validations while keeping amounts hidden.
- Balances remain encrypted on-chain at all times.

### 3. BabyJubJub Elliptic Curve
- A **twisted Edwards elliptic curve** optimized for zk-SNARKs.
- Offers fast signature verification inside zero-knowledge circuits.
- Used in eERC for **efficient key generation and proof validation**.

### 4. ElGamal Encryption
- Public-key encryption scheme adapted for elliptic curve cryptography.
- Used to encrypt token balances and transfer amounts on BabyJubJub.
- Supports **homomorphic addition** so encrypted balances can be updated without decryption.

### 5. Poseidon Ciphertext Hashing
- **Poseidon hash** is a ZK-friendly hashing algorithm designed for use inside proof circuits.
- Optimized for minimal gas cost and high efficiency in zk-SNARK verification.
- In eERC, used for commitments and ciphertext integrity checks.

---

## Auditability Module
- Built directly into the eERC architecture.
- Enables **selective decryption** of transactions for authorized auditors or regulators.
- Permissions can be **rotated or revoked** without redeploying the contract.
- Maintains **compliance-readiness** without compromising user privacy.

---

## On-Chain Components

1. **Registrar Contract**  
   - Manages the list of authorized auditors.
   - Handles public keys for encryption and decryption permissions.

2. **EncryptedUserBalances Contract**  
   - Stores all encrypted balances for token holders.
   - Updates balances through zk-SNARK validated operations.

3. **AuditorManager Contract**  
   - Controls access and permissions for auditors.
   - Integrates with the Auditability Module.

4. **Proof Verification Circuits**  
   - Specialized zk circuits that verify transactions meet the protocol’s rules.
   - Operates without revealing transaction details.
   - Optimized for BabyJubJub, Poseidon hashing, and ElGamal operations.

---

## Modes of Operation

### Standalone Mode
- Token is **fully private** from the moment it is created.
- Total supply can be hidden from the public.
- Ideal for enterprise deployments or regulated private markets.

### Converter Mode
- Wraps an existing ERC-20 token into eERC form for private transfers.
- Allows unwrapping back into the original ERC-20 token.
- Perfect for projects that want optional privacy without changing their base asset.

---

## Developer Integration

- Contracts, circuits and scripts to be used.
- Compatible with Avalanche C-Chain Mainnet, Fuji (Testnet), and custom L1s.
- Does not require modifying the underlying blockchain protocol.

---

In the **next section**, we will cover **Usability of eERC**, focusing on Standalone vs Converter modes, real-world use cases, and how developers and users interact with encrypted tokens on Avalanche.


# Deployment Modes of eERC (/academy/encrypted-erc/04-usability-eerc/01-deployments-mode)

---
title: Deployment Modes of eERC
description: Understanding Standalone and Converter deployment modes of eERC in the Avalanche ecosystem.
updated: 2025-09-02
authors: [alejandro99so]
icon: Split
---

The **eERC** standard offers two deployment modes to fit different project needs: **Standalone Mode** and **Converter Mode**.  
Both deliver encrypted balances and private transfers, but they differ in how the token is created and used.

---

## Standalone Mode
- Token is **private from creation**, all balances and amounts are encrypted from the first mint.
- Uses **ElGamal encryption** over the **BabyJubJub** curve for privacy.
- Transaction proofs use **Poseidon hashing** for efficiency in zk-SNARKs.
- **Optional hidden total supply** to prevent public insight into circulation.
- Best suited for:
  - Enterprise payment systems.
  - Regulated financial assets with selective auditor access.
  - Private gaming economies on Avalanche L1s.

---

## Converter Mode
- Wraps an **existing ERC-20 token** into an encrypted form.
- Allows private transfers using the eERC format while preserving the option to unwrap back to the public ERC-20.
- Uses the same encryption and proof flow as Standalone Mode.
- Best suited for:
  - Adding privacy to an already deployed public token.
  - Hybrid systems where some transactions are public and others private.
  - Bridging between public liquidity pools and private markets.

---

In the **next section**, we will explore **Use Cases of eERC**, including examples from Avalanche C-Chain Mainnet, Fuji (Testnet), and custom L1 deployments, along with a step-by-step view of a private transfer flow.


# Use Cases of eERC (/academy/encrypted-erc/04-usability-eerc/02-use-cases)

---
title: Use Cases of eERC
description: Real-world applications of eERC on Avalanche and the flow of a private transfer.
updated: 2025-09-02
authors: [alejandro99so]
icon: Rocket
---

The **eERC** standard can be deployed across Avalanche C-Chain **Mainnet**, **Fuji (Testnet)**, and **custom L1s**, enabling privacy in a variety of scenarios.

---

## Avalanche C-Chain
- **Private DeFi operations**: Farming, lending, and trading without exposing transaction sizes.
- **Confidential payments**: Salaries and supplier payments visible only to participants and authorized auditors.

---

## Custom L1 Deployments
- **Tokenized real-world assets (RWA)**: Privacy-enabled trading with compliance auditability.
- **Private gaming economies**: Fungible and non-fungible in-game assets with encrypted transfers.

---

## Step-by-Step: Private Transfer Flow (Standalone Mode)

1. **Transaction Creation**  
   - Wallet integrates.  
   - Amount is encrypted using **ElGamal** over **BabyJubJub**.  
   - A **Poseidon hash** of the ciphertext is generated for proof validation.

2. **Proof Generation**  
   - User creates a **zk-SNARK** proving the transaction’s validity without revealing details.

3. **On-Chain Verification**  
   - Smart contract verifies the proof in a zk-friendly circuit optimized for BabyJubJub and Poseidon.  
   - Encrypted balances in the `EncryptedUserBalances` contract are updated.

4. **Auditor Access (Optional)**  
   - Authorized auditors can decrypt specific transactions if enabled in the **Registrar Contract**.

5. **Finalization**  
   - Transaction is recorded on Avalanche with encrypted values only.  
   - Explorers show the transfer occurred, but not the amount or updated balances.

---

In the **next section**, we will examine the **eERC Contracts Flow**, covering how to create an eERC, configure auditor access, choose zk-proof types, and interact with it as a user.


# eERC Contracts Flow (/academy/encrypted-erc/05-eerc-contracts-flow/01-step-by-step)

---
title: eERC Contracts Flow
description: Step-by-step process to create, configure, and use eERC on Avalanche.
updated: 2025-09-02
authors: [alejandro99so]
icon: GitBranch
---

The **eERC (Encrypted ERC)** standard on Avalanche provides privacy-preserving tokens while remaining EVM-compatible.  
This section walks through the full lifecycle of an eERC, from deployment to interaction, including key considerations for developers.

---

## 1. Creating Your eERC

### Step 1: Select Deployment Mode
- **Standalone Mode**: Fully private token from creation, optional hidden total supply.
- **Converter Mode**: Wrap an existing ERC-20 into an encrypted format using a TokenTracker.

### Step 2: Deploy the Core Contracts
- **encryptedERC**: Stores encrypted balances.
- **Registrar Contract**: Manages auditor keys and permissions.
- **Proof Verifier**: Validates zk-SNARK proofs for transfers.

### Step 3: Configure Auditor Access (Optional)
- Register auditors in the **Registrar Contract**.
- Provide them with decryption permissions for compliance scenarios.

---

## 2. About the zk-Proof Type

In the current **EncryptedERC** implementation, the proving system is **not chosen by the end-user**.  
By default, the official Avalanche eERC contracts use **Groth16** for proof generation and verification.

If a developer wants to change the proving system (e.g., to PLONK or Halo2), they must:
1. Modify the Circom circuits.
2. Regenerate the zk verifiers.
3. Deploy new contract versions using those verifiers.

| Proof System | Why it Matters | Current Status in eERC |
|--------------|---------------|------------------------|
| **Groth16** | Fast verification, small proof size, low gas cost | ✅ Default in official repo |
| **PLONK** | Universal setup, flexibility for new circuits | ❌ Requires custom build |
| **Halo2** | No trusted setup, recursion support | ❌ Requires major changes |

> **Avalanche Tip:** Groth16 is optimal for most L1 and C-Chain deployments due to its low gas cost and existing integration in the eERC stack.

---

## 3. Encryption & Hashing Details
- **Curve**: BabyJubJub for zk-friendliness.
- **ElGamal**: ElGamal for balance and transfer amounts.
- **Poseidon**: Poseidon Cipher Text for proof inputs and Merkle trees.

---

## 4. Backend Deployment Flow

### Step 1: Set Up Environment
```bash
git clone https://github.com/alejandro99so/eerc-backend-converter.git
cd eerc-backend-converter
```

### Step 2: Configure `.env` variables in Hardhat

- This step is VERY important because you need those private keys to run `zkit` files.

- Create `.env` file:
- Add to `.env` file: RPC_URL = YOUR_RPC_URL // If you are using Fuji C-Chain (https://api.avax-test.network/ext/bc/C/rpc)
- Add to `.env` file: PRIVATE_KEY = PRIVATE_KEY_1
- Add to `.env` file: PRIVATE_KEY_2 = PRIVATE_KEY_2

### Step 3: Install dependencies and create `zkit` files

```bash
npm install
```

### Step 4: Choose your way (Converter way) and deploy main contracts

```bash
npm run converter:init
npm run converter:core
```

### Step 5: Register Users

```bash
npm run converter:register
```
 
- Change `WALLET_NUMBER = 1;` to `WALLET_NUMBER = 2;` to register PRIVATE_KEY_2 in the `scripts/converter/03_register-user.ts` file

```bash
npm run converter:register
```

### Step 6: Set auditor

```bash
npm run converter:auditor
```

### Step 7: Get faucet tokens for PRIVATE_KEY_2

- Let's check our first balance (PRIVATE_KEY_2)
```bash
npm run converter:balance
```

- Let's get faucet tokens for PRIVATE_KEY_2
```bash
npm run converter:faucet
```

### Step 8: Deposit tokens

#### To PRIVATE_KEY_1 

- Change `WALLET_NUMBER = 2;` to `WALLET_NUMBER = 1;` to get token balance from PRIVATE_KEY_1 in `scripts/converter/08_check_balance.ts` file
- Let's check our first balance
```bash
npm run converter:balance
```
- Let's deposit some ERC20 tokens to get eERC20 tokens
```bash
npm run converter:deposit
```
- Let's check our new balance
```bash
npm run converter:balance
```

#### To PRIVATE_KEY_2

- Change `WALLET_NUMBER = 1;` to `WALLET_NUMBER = 2;` to get token balance from PRIVATE_KEY_2 in `scripts/converter/08_check_balance.ts` file
- Let's check our first balance
```bash
npm run converter:balance
```
- Change `WALLET_NUMBER = 1;` to `WALLET_NUMBER = 2;` to deposit tokens from PRIVATE_KEY_2 in the `scripts/converter/06_deposittx.ts` file
- Let's deposit some ERC20 tokens to get eERC20 tokens
```bash
npm run converter:deposit
```
- Let's check our new balance
```bash
npm run converter:balance
```

### Step 9: Transfer tokens
- Let's transfer encrypted tokens from PRIVATE_KEY_1 to PRIVATE_KEY_2
```bash
npm run converter:transfer
```

### Step 10: Withdraw tokens from `PRIVATE_KEY_2`

#### To PRIVATE_KEY_1

- Let's transfer encrypted tokens from PRIVATE_KEY_1 to PRIVATE_KEY_2
```bash
npm run converter:transfer
```
- Change `WALLET_NUMBER = 2;` to `WALLET_NUMBER = 1;` to get token balance from PRIVATE_KEY_1 in `scripts/converter/08_check_balance.ts` file
- Let's check our new balance after transferring tokens
```bash
npm run converter:balance
```

#### To PRIVATE_KEY_2

- Let's withdraw encrypted tokens (eERC20) from PRIVATE_KEY_2 to get tokens (ERC20)
```bash
npm run converter:withdraw
```
- Change `WALLET_NUMBER = 1;` to `WALLET_NUMBER = 2;` to get token balance from PRIVATE_KEY_2 in `scripts/converter/08_check_balance.ts` file
- Let's check our new balance for `PRIVATE_KEY_2` after transferring tokens
```bash
npm run converter:balance
```

### Step 11:  Choose your way (Standalone way)

- Follow the flow by yourself and reach out to us at https://t.me/avalancheacademy

## 6. Considerations for Production

- **Gas Costs**: Proof verification adds overhead; optimize circuits.  
- **Auditor Key Rotation**: Plan for secure revocation and re-assignment.  
- **Compliance**: Align privacy settings with jurisdictional requirements.


# Introduction (/academy/icm-chainlink/01-access-chainlink-vrf-services/01-introduction)

---
title: Introduction
description: Learn how to use ICM to access Chainlink VRF services on L1 networks that do not have direct Chainlink support.
updated: 2024-10-21
authors: [0xstt]
icon: Book
---

As decentralized applications (dApps) expand across multiple blockchains, some Layer 1 (L1) networks lack direct support from essential services like **Chainlink VRF (Verifiable Random Functions)**. This presents a significant challenge for developers who rely on verifiable randomness for use cases such as gaming, lotteries, NFT minting, and other decentralized functions that require unbiased, unpredictable random numbers.

The challenge arises because not every L1 network has integrated with Chainlink, meaning developers on those chains are left without native access to VRF services. Without verifiable randomness, critical aspects of dApps, such as fairness and security, can be compromised.

### Why ICM is Necessary

To address this gap, **Interchain Messaging (ICM)** provides a solution by allowing L1 networks that don’t have direct Chainlink support to still access these services. Through ICM, any blockchain can request VRF outputs from a Chainlink-supported network (e.g., Fuji) and receive the results securely on their own L1. 

This cross-chain solution unlocks the ability to use Chainlink VRF on unsupported networks, bypassing the need for native integration and ensuring that dApp developers can continue building secure and fair decentralized applications.

In the following sections, we will explore how to use ICM to access Chainlink VRF services across different chains by deploying two key smart contracts: one on the Chainlink-supported network and another on the target L1.

# Understanding the Flow (/academy/icm-chainlink/01-access-chainlink-vrf-services/02-understanding-the-flow)

---
title: Understanding the Flow
description: Learn how requests for random words flow across chains using ICM.
updated: 2024-10-21
authors: [0xstt]
icon: BookOpen
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

This section explains how random words are requested and fulfilled using Chainlink VRF across two different blockchains through **Interchain Messaging (ICM)**. The entire process involves several key components: the decentralized application (DApp), `CrossChainVRFConsumer`, `CrossChainVRFWrapper`, and `TeleporterMessenger`.

Let’s walk through the flow step by step:

<Steps>
<Step>

### DApp Submits Request for Random Words

The DApp, running on an L1 without direct Chainlink support, initiates a request for verifiable randomness by interacting with the `CrossChainVRFConsumer` contract deployed on its chain.

</Step>
<Step>

### `CrossChainVRFConsumer` Sends Cross-Chain Message

Once the DApp submits the request, the `CrossChainVRFConsumer` prepares a message containing the necessary VRF request parameters (such as `keyHash`, `request confirmations`, `gas limit`, etc.). This message is sent across chains via the `TeleporterMessenger` to the `CrossChainVRFWrapper` on the Chainlink-supported network (e.g., Fuji).

</Step>
<Step>

### `TeleporterMessenger` Receives Message & Calls `CrossChainVRFWrapper`
1. On the Chainlink-supported network, the `TeleporterMessenger` receives the cross-chain message sent by the `CrossChainVRFConsumer`. It passes the message to the `CrossChainVRFWrapper`, which is authorized to handle VRF requests.
2. The `CrossChainVRFWrapper` contract, deployed on the supported network, sends the request to **Chainlink VRF** for random words, using the parameters received in the message (e.g., `subscription ID`, `callback gas limit`, etc.).

</Step>

<Step>

### Chainlink VRF Fulfills Random Words Request

1. The **Chainlink VRF** fulfills the request and returns the random words to the `CrossChainVRFWrapper` contract by invoking its callback function.
2. Once the random words are received, the `CrossChainVRFWrapper` encodes the fulfilled random words and sends them back as a cross-chain message to the `CrossChainVRFConsumer` on the original L1.

</Step>

<Step>

### `TeleporterMessenger` Returns Random Words to `CrossChainVRFConsumer`
   
The `TeleporterMessenger` on the original L1 receives the message containing the random words and passes it to the `CrossChainVRFConsumer`.

</Step>

<Step>

### `CrossChainVRFConsumer` Returns Random Words to the DApp

Finally, the `CrossChainVRFConsumer` processes the random words and sends them to the DApp that originally requested them, completing the flow.

</Step>

</Steps>

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/interchain-messaging/cross-chain-vrf-NiG2EHgc4ulWBUx9Ekx0DZxTGdoHXk.png)

This end-to-end process demonstrates how decentralized applications on unsupported L1 networks can request verifiable randomness from Chainlink VRF, leveraging **ICM** to handle cross-chain communication.



# Orchestrating VRF Requests Over Multiple Chains (Wrapper) (/academy/icm-chainlink/01-access-chainlink-vrf-services/03-orchestrating-vrf-requests)

---
title: Orchestrating VRF Requests Over Multiple Chains (Wrapper)
description: Learn how the CrossChainVRFWrapper contract on a Chainlink-supported L1 handles cross-chain requests for VRF.
updated: 2024-10-21
authors: [0xstt]
icon: BookOpen
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

The `CrossChainVRFWrapper` contract plays a critical role in handling requests for randomness from an unsupported L1. It is deployed on a **Chainlink-supported network** (like Avalanche Fuji) and serves as the intermediary that interacts with Chainlink VRF to request random words.

Here’s how it functions as the provider for VRF services:

## Receives Cross-Chain Messages

<Steps>
<Step>

When the `CrossChainVRFConsumer` on the unsupported L1 initiates a request for randomness, it sends a cross-chain message via the `TeleporterMessenger` to the `CrossChainVRFWrapper` on the supported network.

</Step>
<Step>

The `CrossChainVRFWrapper` verifies that the request came from an authorized address. This is essential to ensure that only verified consumers can request randomness.

</Step>
<Step>

Upon receiving a valid request, the **VRFWrapper** calls **Chainlink VRF** and sends the request with the required parameters, such as the number of random words, request confirmations, and gas limits.

</Step>
<Step>

The `CrossChainVRFWrapper` keeps track of all pending requests using a mapping, associating each request ID with its destination (the L1 where the `CrossChainVRFConsumer` resides). This ensures that the random words are returned to the correct destination once fulfilled.

</Step>
</Steps>

<Accordions>
<Accordion title="Implementation">
```solidity
function receiveTeleporterMessage(
    bytes32 originChainID,
    address originSenderAddress,
    bytes calldata message
) external {
    require(msg.sender == address(teleporterMessenger), "Caller is not the TeleporterMessenger");
    // Verify that the origin sender address is authorized
    require(authorizedSubscriptions[originSenderAddress].isAuthorized, "Origin sender is not authorized");
    uint256 subscriptionId = authorizedSubscriptions[originSenderAddress].subscriptionId;
    // Verify that the subscription ID belongs to the correct owner
    (,,,, address[] memory consumers) = s_vrfCoordinator.getSubscription(subscriptionId);
    // Check wrapper contract is a consumer of the subscription
    bool isConsumer = false;
    for (uint256 i = 0; i < consumers.length; i++) {
        if (consumers[i] == address(this)) {
            isConsumer = true;
            break;
        }
    }
    require(isConsumer, "Contract is not a consumer of this subscription");
    // Decode message to get the VRF parameters
    CrossChainRequest memory vrfMessage = abi.decode(message, (CrossChainRequest));
    // Request random words
    VRFV2PlusClient.RandomWordsRequest memory req = VRFV2PlusClient.RandomWordsRequest({
        keyHash: vrfMessage.keyHash,
        subId: subscriptionId,
        requestConfirmations: vrfMessage.requestConfirmations,
        callbackGasLimit: vrfMessage.callbackGasLimit,
        numWords: vrfMessage.numWords,
        extraArgs: VRFV2PlusClient._argsToBytes(VRFV2PlusClient.ExtraArgsV1({nativePayment: vrfMessage.nativePayment}))
    });
    uint256 requestId = s_vrfCoordinator.requestRandomWords(req);
    pendingRequests[requestId] = CrossChainReceiver({
        destinationBlockchainId: originChainID,
        destinationAddress: originSenderAddress
    });
}   
```
</Accordion>
</Accordions>

## Handles Callback from Chainlink VRF

<Steps>
<Step>

When **Chainlink VRF** fulfills the randomness request, the `CrossChainVRFWrapper` receives the random words through a callback function. This ensures that the request has been successfully processed.

</Step>
<Step>

After receiving the random words, the `CrossChainVRFWrapper` encodes the result and sends it back as a cross-chain message to the `CrossChainVRFConsumer` on the unsupported L1. This is done using the `TeleporterMessenger`.

</Step>
</Steps>

<Accordions>
<Accordion title="Implementation">
```solidity
function fulfillRandomWords(uint256 requestId, uint256[] calldata randomWords) internal override {
    require(pendingRequests[requestId].destinationAddress != address(0), "Invalid request ID");
    // Create CrossChainResponse struct
    CrossChainResponse memory crossChainResponse = CrossChainResponse({
        requestId: requestId,
        randomWords: randomWords
    });
    bytes memory encodedMessage = abi.encode(crossChainResponse);
    // Send cross chain message using ITeleporterMessenger interface
    TeleporterMessageInput memory messageInput = TeleporterMessageInput({
        destinationBlockchainID: pendingRequests[requestId].destinationBlockchainId,
        destinationAddress: pendingRequests[requestId].destinationAddress,
        feeInfo: TeleporterFeeInfo({ feeTokenAddress: address(0), amount: 0 }),
        requiredGasLimit: 100000,
        allowedRelayerAddresses: new address[](0),
        message: encodedMessage
    });
    teleporterMessenger.sendCrossChainMessage(messageInput);
    delete pendingRequests[requestId];
}
```
</Accordion>
</Accordions>

In summary, the `CrossChainVRFWrapper` contract acts as the **bridge** between the unsupported L1 and Chainlink’s VRF services, ensuring that random words are requested, fulfilled, and delivered back across chains efficiently.


# Bringing Chainlink VRF to Unsupported L1s (Consumer) (/academy/icm-chainlink/01-access-chainlink-vrf-services/04-bring-vrf-to-unsupported-l1)

---
title: Bringing Chainlink VRF to Unsupported L1s (Consumer)
description: Learn how to request VRF from an unsupported L1 using CrossChainVRFConsumer.
updated: 2024-10-21
authors: [0xstt]
icon: BookOpen
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

The `CrossChainVRFConsumer` contract enables DApps on an unsupported L1 to request random words from Chainlink VRF using a cross-chain communication mechanism. Since Chainlink does not natively support all blockchains, this setup allows developers to access Chainlink's VRF service even on networks that don’t have direct support.

<Steps>
<Step>

## Requesting Random Words

The `CrossChainVRFConsumer` contract sends a cross-chain message to the `CrossChainVRFWrapper` on a Chainlink-supported L1, requesting random words. This request is sent using `TeleporterMessenger`, which handles cross-chain communication.

<Accordions>
<Accordion title="Implementation">
```solidity
function requestRandomWords(
    bytes32 keyHash,
    uint16 requestConfirmations,
    uint32 callbackGasLimit,
    uint32 numWords,
    bool nativePayment,
    uint32 requiredGasLimit
) external {
    // Create CrossChainRequest struct
    CrossChainRequest memory crossChainRequest = CrossChainRequest({
        keyHash: keyHash,
        requestConfirmations: requestConfirmations,
        callbackGasLimit: callbackGasLimit,
        numWords: numWords,
        nativePayment: nativePayment
    });
    // Send Teleporter message
    bytes memory encodedMessage = abi.encode(crossChainRequest);
    TeleporterMessageInput memory messageInput = TeleporterMessageInput({
        destinationBlockchainID: DATASOURCE_BLOCKCHAIN_ID, 
        destinationAddress: vrfRequesterContract,
        feeInfo: TeleporterFeeInfo({ feeTokenAddress: address(0), amount: 0 }),
        requiredGasLimit: requiredGasLimit,
        allowedRelayerAddresses: new address[](0),
        message: encodedMessage
    });
    teleporterMessenger.sendCrossChainMessage(messageInput);
}
```
</Accordion>
</Accordions>

</Step>

<Step>

## Processing the Request
Once the request is received by the `CrossChainVRFWrapper`, it interacts with the Chainlink VRF Coordinator to request the random words on behalf of the consumer on the unsupported L1.

</Step>

<Step>

## Receiving Random Words

Once Chainlink fulfills the request, the `CrossChainVRFWrapper` sends the random words back to the `CrossChainVRFConsumer` via a cross-chain message, enabling the DApp on the unsupported L1 to use them.

<Accordions>
<Accordion title="Implementation">
```solidity
function receiveTeleporterMessage(
    bytes32 originChainID,
    address originSenderAddress,
    bytes calldata message
) external {
    require(originChainID == DATASOURCE_BLOCKCHAIN_ID, "Invalid originChainID");
    require(msg.sender == address(teleporterMessenger), "Caller is not the TeleporterMessenger");
    require(originSenderAddress == vrfRequesterContract, "Invalid sender");
    
    // Decode the message to get the request ID and random words
    CrossChainResponse memory response = abi.decode(message, (CrossChainResponse));
    
    // Fulfill the request by calling the internal function
    fulfillRandomWords(response.requestId, response.randomWords);
}

function fulfillRandomWords(uint256 requestId, uint256[] memory randomWords) internal {
    // Logic to handle the fulfillment of random words
    // Implement your custom logic here

    // Emit event for received random words
    emit RandomWordsReceived(requestId);
}
```
</Accordion>
</Accordions>

</Step>
</Steps>


# Deploy Wrapper (/academy/icm-chainlink/01-access-chainlink-vrf-services/05-deploy-vrf-wrapper)

---
title: Deploy Wrapper
description: Learn how to deploy the CrossChainVRFWrapper contract to handle cross-chain VRF requests.
updated: 2024-10-21
authors: [0xstt]
icon: Terminal
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

Once you have set up your Chainlink VRF subscription and have your LINK tokens ready, the next step is to deploy the **CrossChainVRFWrapper** contract. This contract will act as the bridge between your unsupported L1 and the Chainlink VRF network on a supported L1, enabling cross-chain requests for random words.

<Steps>
<Step>

## Prerequisites
Before deployment, make sure you have:
- A valid **Chainlink VRF Subscription ID** (see previous section for details).
- The `TeleporterMessenger` contract address on your supported L1 (e.g., Avalanche Fuji).
</Step>
<Step>

## Deploy the Contract
Using the `forge create` command, deploy the `CrossChainVRFWrapper` contract to the supported L1 (e.g., Avalanche Fuji).

```bash
forge create --rpc-url <RPC_URL> --private-key <PRIVATE_KEY> --broadcast --constructor-args <TELEPORTER_MESSENGER_ADDRESS> src/CrossChainVRFWrapper.sol:CrossChainVRFWrapper
```

Replace the following:

- `<RPC_URL>`: The RPC URL for the L1.
- `<PRIVATE_KEY>`: The private key for the account used to deploy the contract.
- `<TELEPORTER_MESSENGER_ADDRESS>`: The address of the deployed `TeleporterMessenger` contract.

After deployment, save the `Deployed to` address in an environment variable for future use.

```bash
export VRF_WRAPPER=<address>
```

</Step>
<Step>

## Verify the Deployment
After deploying the contract, verify that the `CrossChainVRFWrapper` has been successfully deployed by checking its address on a block explorer.

</Step>
<Step>

## Configure Authorized Subscriptions
Once deployed, the `CrossChainVRFWrapper` contract needs to be configured with authorized subscriptions to process requests for random words.

- Call the `addAuthorizedAddress` function to authorize a specific address with a given subscription ID.
- This ensures that only authorized addresses can request random words via the wrapper.

```bash
cast send --rpc-url <RPC_URL> --private-key <PRIVATE_KEY> $VRF_WRAPPER "addAuthorizedAddress(address caller, uint256 subscriptionId)" <CALLER_ADDRESS> <SUBSCRIPTION_ID>
```

Replace the following:

- `<CALLER_ADDRESS>`: The address that will be authorized to request random words.
- `<SUBSCRIPTION_ID>`: The ID of your Chainlink VRF subscription.
</Step>
</Steps>

# Deploy Consumer (/academy/icm-chainlink/01-access-chainlink-vrf-services/06-deploy-vrf-consumer)

---
title: Deploy Consumer
description: Learn how to deploy the CrossChainVRFConsumer contract on any L1 that does not support Chainlink VRF.
updated: 2024-10-21
authors: [0xstt]
icon: Terminal
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

Now that the `CrossChainVRFWrapper` is deployed on a Chainlink-supported L1, it’s time to deploy the `CrossChainVRFConsumer` contract on the L1 where Chainlink VRF is not supported. This contract will handle requests for random words and interact with the **TeleporterMessenger** to communicate with the supported L1.

<Steps>
<Step>
## Prerequisites
Make sure you have:
- The `TeleporterMessenger` contract address on the unsupported L1.
- The deployed `CrossChainVRFWrapper` on the supported L1. `($VRF_WRAPPER)`
</Step>
<Step>
## Deploy the Contract
Use the following command to deploy the `CrossChainVRFConsumer` contract on your unsupported L1.

```bash
forge create --rpc-url <RPC_URL> --private-key <PRIVATE_KEY> --broadcast --constructor-args <TELEPORTER_MESSENGER_ADDRESS> $VRF_WRAPPER src/CrossChainVRFConsumer.sol:CrossChainVRFConsumer
```

Replace the following:

- `<RPC_URL>`: The RPC URL for the L1.
- `<PRIVATE_KEY>`: The private key for the account used to deploy the contract.
- `<TELEPORTER_MESSENGER_ADDRESS>`: The address of the `TeleporterMessenger` contract on your unsupported L1.

After deployment, save the `Deployed to` address in an environment variable for future use.

```bash
export VRF_CONSUMER=<address>
```
</Step>
<Step>
## Verify the Deployment
Once the `CrossChainVRFConsumer` contract is deployed, verify the contract’s address and confirm that it has been successfully deployed on your L1 using a block explorer.
</Step>
</Steps>

# Create Chainlink VRF Subscription (/academy/icm-chainlink/01-access-chainlink-vrf-services/07-create-vrf-subscription)

---
title: Create Chainlink VRF Subscription
description: Learn how to create a Chainlink VRF subscription to enable cross-chain randomness requests.
updated: 2024-10-21
authors: [0xstt]
icon: BookOpen
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

Before you can request random words using Chainlink VRF, you need to set up a **Chainlink VRF subscription**. This subscription allows you to fund requests for randomness and manage the list of consumers that are authorized to use the VRF service.

<Steps>
<Step>

## Access Chainlink's VRF Subscription Manager

To create a subscription, go to the Chainlink VRF Subscription Manager on the network where you plan to request VRF (e.g., Avalanche Fuji). You can access the manager here: [VRF | Subscription Management for Fuji](https://vrf.chain.link/fuji).
![](/common-images/chainlink-vrf/visit-subscription-management.png)

</Step>
<Step>

## Create a New Subscription

Once on the subscription manager, create a new subscription. The subscription will have a unique ID, which you'll need to reference in your `CrossChainVRFWrapper` contract. This ID is used to track your random word requests and the balance associated with them.
![](/common-images/chainlink-vrf/create-subscription.png)

</Step>
<Step>

## Fund the Subscription

After creating the subscription, you need to fund it with LINK tokens. These tokens are used to pay for the randomness requests made through Chainlink VRF. Make sure your subscription has enough funds to cover your requests.
You can get testnet LINK tokens from the Fuji Faucet: [Chainlink Faucet for Fuji](https://faucets.chain.link/fuji)

![](/common-images/chainlink-vrf/faucet.png)

![](/common-images/chainlink-vrf/add-funds.png)

</Step>
<Step>

## Add Consumers

After funding your subscription, add the `CrossChainVRFWrapper` contract `($VRF_WRAPPER)` as a consumer. This step authorizes the contract to make randomness requests on behalf of your subscription. You can add other consumers, such as other contracts or addresses, depending on your use case.
![](/common-images/chainlink-vrf/add-consumer.png)

</Step>
<Step>

## Save Subscription ID

After completing these steps, save your subscription ID. You will need this ID when configuring the `CrossChainVRFWrapper` contract to request random words.

```bash
export VRF_SUBSCRIPTION_ID=<subscription_id>
```

</Step>
</Steps>

---


# Request Random Words (/academy/icm-chainlink/01-access-chainlink-vrf-services/08-request-random-words)

---
title: Request Random Words
description: Learn how to request random words using CrossChainVRFConsumer.
updated: 2024-10-21
authors: [0xstt]
icon: Terminal
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

In this section, you will learn how to request random words from Chainlink VRF using both the `CrossChainVRFConsumer` contracts.

<Steps>
<Step>

## Authorize an Address to Request Random Words

After deploying the `CrossChainVRFWrapper` contract, the first step is to authorize an address to make requests for random words. This ensures that only specific addresses linked to a subscription can request VRF.

- Use the `addAuthorizedAddress` function to authorize a specific address with a given subscription ID. This step allows the address to make random word requests through the wrapper.

```bash
cast send --rpc-url <RPC_URL> --private-key <PRIVATE_KEY> $VRF_WRAPPER "addAuthorizedAddress(address caller, uint256 subscriptionId)" $VRF_CONSUMER $VRF_SUBSCRIPTION_ID
```

</Step>
<Step>

## Request Random Words from `CrossChainVRFConsumer`

Once the address is authorized, the next step is to send a request for random words from the `CrossChainVRFConsumer` contract on the unsupported L1. This request is then sent to the `CrossChainVRFWrapper` via a cross-chain message.

```bash
cast send --rpc-url <RPC_URL> --private-key <PRIVATE_KEY> $VRF_CONSUMER "requestRandomWords(bytes32 keyHash, uint16 requestConfirmations, uint32 callbackGasLimit, uint32 numWords, bool nativePayment, uint32 requiredGasLimit)" <KEY_HASH> <CONFIRMATIONS> <GAS_LIMIT> <NUM_WORDS> <NATIVE_PAYMENT> <REQUIRED_GAS_LIMIT>
```

Replace the placeholders with:

- `<KEY_HASH>`: The VRF key hash used for random word generation.
- `<CONFIRMATIONS>`: Number of confirmations required for the request.
- `<GAS_LIMIT>`: The gas limit for the VRF callback function.
- `<NUM_WORDS>`: The number of random words requested.
- `<NATIVE_PAYMENT>`: Indicates whether the payment will be made in the native token.
- `<REQUIRED_GAS_LIMIT>`: The gas limit required for the cross-chain message to be processed.

</Step>
</Steps>

# Introduction (/academy/icm-chainlink/02-access-chainlink-functions/01-introduction)

---
title: Introduction
description: Learn how to use ICM to access Chainlink VRF services on L1 networks that do not have direct Chainlink support.
updated: 2024-10-21
authors: [Andrea]
icon: Book
---

TBD

# Introduction (/academy/icm-chainlink/03-access-chainlink-automation/01-introduction)

---
title: Introduction
description: Learn how to use ICM to access Chainlink VRF services on L1 networks that do not have direct Chainlink support.
updated: 2024-10-21
authors: [Andrea]
icon: Book
---

TBD

# Introduction (/academy/icm-chainlink/04-ccip-icm/01-introduction)

---
title: Introduction
description: Learn how to use ICM to access Chainlink VRF services on L1 networks that do not have direct Chainlink support.
updated: 2024-10-21
authors: [Andrea]
icon: Book
---

TBD

# Interoperability between blockchain (/academy/interchain-messaging/02-interoperability/01-interopability-between-blockchains)

---
title: Interoperability between blockchain
description: Learn about interoperability and it's importance in multichain systems
updated: 2024-05-31
authors: [martineckardt]
icon: Book
---

<YouTube id="eLHOElbSw1k" />

Interoperability between blockchains refers to the ability of different blockchain networks to communicate and interact with one another in a seamless and coordinated manner. It allows these separate blockchain systems to share data, assets, or functionalities, enabling them to work together as if they were part of a single unified network.

These interactions can take many forms, including:

- Asset Bridging (Tokens, NFTs, etc.)
- DAO Voting across Chains
- Cross-Chain Liquidity Pools

As you will see soon, these different interactions are based on the same fundamentals of blockchains
exchanging messages. You can learn about some of them in the recording of this panel:

<YouTube id="Ef90eCRY5z0" />

## What you will learn

In this section, you will explore the following topics:

- **Source, Message, and Destination:** What is a message and what are the roles of the source and destination blockchain in interoperability?
- **Multi-Chain Systems:** A quick recap of multi-chain systems
- **Interoperability in Multi-Chain Systems:** Learn about the importance of interoperability to multi-chain systems

# Source, Message and Destination (/academy/interchain-messaging/02-interoperability/02-source-message-destination)

---
title: Source, Message and Destination
description:  Learn about interoperability and it's importance in multichain systems.
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

Interoperability is achieved by enabling blockchains to pass messages to one another. Each message originates from a source chain and is sent to one or more destination chains. These messages encode arbitrary data that can attest some event on the source chains, such as the deposit of an asset or the result of a vote.

<div class="flex space-x-8">
    <div class="flex-1">
        ![](/common-images/teleporter/source.png)
        # Source
        - Origin of communication
        - Sender calls contract
    </div>
    <div class="flex-1">
        ![](/common-images/teleporter/message.png)
        # Message
        - Contains source, destination, and encoded data
        - Signature guarantees  authenticity
    </div>
    <div class="flex-1">
        ![](/common-images/teleporter/destination.png)
        # Destination
        - Submission of message as transaction
        - Verifies signatures
    </div>
</div>

## Source Chain

The source chain in a cross-blockchain communication system refers to the original blockchain where data, assets, or information originate before being communicated to another blockchain. It acts as the starting point for initiating cross-chain interactions. When a user intends to communicate with another blockchain, they utilize protocols or smart contracts to initiate the communication process from the source chain.

## Message

The message is the data structure that will be sent to to the destination chain. It contains some metadata, the encoded message, and a signature. The signature attests the authenticity of the message, meaning that whatever the message claims has actually happened on the source chain. 

## Destination Chain

Conversely, the destination chain is the recipient blockchain where the communicated data, assets, or instructions will be received and processed. Validators, nodes, or protocols associated with the cross-blockchain communication system on the destination chain receive and authenticate the information relayed from the source chain. Once validated, the destination chain processes the data or executes the specified instructions.

<Quiz quizId="301"/>


# Recap of Multi-Chain Networks (/academy/interchain-messaging/02-interoperability/03-multi-chain-networks)

---
title: Recap of Multi-Chain Networks
description:  Learn about interoperability and it's importance in multichain systems
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/l1s.png)

Avalanche is a multi-chain network, meaning the network has multiple chains being validated in parallel, while other networks, such as Bitcoin and Ethereum only have single chain.

This feature provides greater scalability, independence, and customizability. Each blockchain is optimized for specialized use cases, boosting the network's overall performance.

## Transactions per Second (TPS) and Time to Finality (TTF)

To measure the performance of a blockchain, we can use two primary metrics: Time to finality (measured in seconds) and throughput (measured in transactions per second, TPS). To illustrate, we can think of a highway an as analogy.

![](/common-images/consensus/tps-vs-ttf.png)

Having a short time to finality is a short highway, taking a direct route from origin (submitting a transaction) to destination (finalization of the transaction) without any unnecessary detours. A finalized transaction is irreversibly written to the ledger. Once a transaction is final, users can be sure it has executed.

Having high transaction throughput is like having many lanes on the highway, meaning many cars (transactions) can use it at the same time. When building blockchain systems, we want to achieve high throughput.

## Scaling For The Masses

Different blockchain networks use different scaling approaches, such as Layer 2s, including roll-ups. Networks aim to maximize the throughput. Multi-chain systems have a simple, but incredible effective way of scaling. By running independent chains in parallel, the overall network can reach a massive combined throughput.

![](/common-images/multi-chain-architecture/combined-throughput.png)

While roll-ups may enable a very high-throughput of a single chain, they can never outcompete the combined throughput of a multi-chain system. This is because there's no limit to the number of chains that can run in parallel.

<Quiz quizId="302"/>


# Interoperability in Multi-Chain Systems (/academy/interchain-messaging/02-interoperability/04-interoperability-in-multi-chain-systems)

---
title: Interoperability in Multi-Chain Systems
description:  Learn about interoperability and it's importance in multichain systems
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

Interoperability is crucial for multi-chain systems, as the price for easy scalability is fragmentation. However, this interoperability is equally important to all blockchain systems. Even though more dApps are based on the same chain in single-chain systems, many of them require interaction with other chains for liquidity or governance. Therefore, coming up with secure and efficient interoperability solutions is crucial for the entire blockchain space.

![](/common-images/multi-chain-architecture/vm-variety.png)

Avalanche, as a multi-chain system, provides flexibility on the execution and application layer but
also offers a standardized messaging protocol. The necessary cryptographic algorithms are
implemented in AvalancheGo, enabling cross-Avalanche L1 communication out of the box, even when the
application and execution layers of the chains may be completely different. The VMs can utilize
these modules to sign and verify messages, making interoperability between Avalanche L1s much easier
than between unrelated chains from different networks.

# Finality Importance in Interoperabile Systems (/academy/interchain-messaging/02-interoperability/05-finality-and-interoperability)

---
title: Finality Importance in Interoperabile Systems
description:  Learn about interoperability and it's importance in multichain systems
updated: 2024-06-10
authors: [andyvargtz]
icon: BookOpen
---

Finality is crucial for building cross-chain applications and interoperable systems because it ensures that transactions on the source chain are confirmed and immutable, therefore whatever action is triggered on the destination chain can securely be executed knowing the source chain won't revert the state induced by that cross chain message.


# Trusted Third Parties (/academy/interchain-messaging/02-interoperability/06-trusted-third-parties)

---
title: Trusted Third Parties
description: Learn about the challenges of cross-chain communication.
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

# "Cross-chain communication is impossible without a trusted third party, contrary to common beliefs in the blockchain community"
- A. Zamyatin et al. in [SoK: Communication Across Distributed Ledgers](https://eprint.iacr.org/2019/1128.pdf)

Signature Schemes give us the tool to ensure the authenticity of message, but who will send these messages? Can we build a cross-chain communication protocol that does not introduce additional trust assumption?

The paper [SoK: Communication Across Distributed Ledgers](https://eprint.iacr.org/2019/1128.pdf) looks into this question and states that a CCC protocol must have the following attributes:

- **Effectiveness:** all relevant transactions are posted on their respective chains at the desired time
- **Atomicity:** either all transactions were posted on their respective chains at the desired time, or no transactions were posted at all 
- **Timeliness:** all transactions will eventually be posted on their respective chains

It is possible to create a cross-chain communication protocol that adheres to the three attributes mentioned above? Can a correct CCC protocol that is trustless exist?

In SoK, the researchers come to the conclusion that such a trustless, correct CCC protocol is impossible. Using computational complexity theory, the trustless, correct CCC protocol problem can be reduced into the Fair Exchange problem, a problem that has been proven to have no solution.

We see this also in practice. Many bridges and cross-chain communications often rely on some centralized infrastructure that observes the source chain and then delivers the message to the destination chain. Their users need to trust this setup, often involving a set of third-party bridge validators.

However, there might be a smart trick we can use. We'll explore this in the next section about Avalanche Warp Messaging.

# Avalanche Starter Kit (/academy/interchain-messaging/03-avalanche-starter-kit/01-avalanche-starter-kit)

---
title: Avalanche Starter Kit
description: Environment Setup
updated: 2024-05-31
authors: [martineckardt]
icon: Book
---

The Avalanche Starter Kit provides a pre-configured GitHub Codespace environment with everything you need to develop cross-chain applications on Avalanche. This environment comes with:

- Foundry for smart contract development
- Docker support for running the ICM relayer
- Required VS Code extensions
- All necessary development tools

## What You Will Learn

In this section, you will:

- Launch your own GitHub Codespace
- Set up your Core wallet and get test tokens
- Configure your development environment
- Learn basic Foundry commands for contract interaction

By the end of this section, you'll have a fully configured environment ready for cross-chain development with Interchain Messaging

# Initial Setup (/academy/interchain-messaging/03-avalanche-starter-kit/02-set-up)

---
title: Initial Setup
description: Environment and Wallet Setup
updated: 2024-05-31
authors: [martineckardt]
icon: Terminal
---

import Link from 'next/link';
import { cn } from '@/utils/cn';
import { buttonVariants } from '@/components/ui/button.tsx'
import { Step, Steps } from 'fumadocs-ui/components/steps';

The Avalanche Starter Kit contains everything you need to get started quickly with Avalanche. The kit provides a self-contained environment with Foundry so you can follow the course without the need of installing anything else other than launching the environment.

In this course we will run the Avalanche Starter Kit in a hosted environment on Github. This is the quickest way to get started.

<Steps>
<Step>

### Create a Codespace

The quickest way to get started is using GitHub Codespaces, which provides a pre-configured development environment:

[![Open in GitHub Codespaces](https://github.com/codespaces/badge.svg)](https://github.com/codespaces/new?hide_repo_select=true&ref=interchain-messaging&repo=769886086&machine=standardLinux32gb)

Wait a few minutes for the environment to build. You must be logged into GitHub to use Codespaces.

Alternatively, you can clone the repository:

<Link
    href="https://github.com/ava-labs/avalanche-starter-kit/tree/interchain-messaging"
    className={cn(
    buttonVariants({ variant: 'default', className: 'mt-4' }),
    )}
    target='_blank'
>Open Avalanche Starter Kit</Link>

</Step>
<Step>

### Install Dependencies

Once your Codespace is ready, install the project dependencies:

```bash
forge install

# Optional: Mute Foundry nightly warning
export FOUNDRY_DISABLE_NIGHTLY_WARNING=1
```

</Step>
<Step>

### Set Up Core Wallet

1. Install Core wallet:
   - Visit [Core wallet website](https://core.app/download)
   - Download and install for your OS
   - Create a new wallet or import existing one

<Callout type="warn" title="If you created your wallet account with gmail or any other auth provider you will not have a private key" />

2. Get your [wallet credentials](https://support.avax.network/en/articles/8832783-core-extension-how-do-i-export-my-private-key):
   - Open Core wallet
   - Click your account name (top right)
   - Select "View Private Key"
   - Enter your password
   - Copy your:
     - Account address (0x...)
     - Private key (0x...)

<Callout type="warn" title="The private key is for testing only. Never use it in production or share it with anyone. Do not use a private key holding real funds on testnet, separate mainnet and testnet keys!" />

</Step>
<Step>

### Configure Environment

1. Create your environment file:
```bash
cp .env.example .env
```

2. Add your Core wallet credentials to `.env`:
```bash
# Your private key for signing transactions (for testing only, never use in production)
PK=your_private_key_here

# Your funded address (the address derived from your private key)
FUNDED_ADDRESS=your_funded_address_here

# Teleporter and chain configuration
# Fuji C-Chain, Dispatch & Echo have the same address, but this might no be the case for other L1s
TELEPORTER_REGISTRY_FUJI_DISPATCH=0xF86Cb19Ad8405AEFa7d09C778215D2Cb6eBfB228
TELEPORTER_REGISTRY_FUJI_C_CHAIN=0xF86Cb19Ad8405AEFa7d09C778215D2Cb6eBfB228

# Blockchain IDs pre-filled
FUJI_DISPATCH_BLOCKCHAIN_ID_HEX=0x9f3be606497285d0ffbb5ac9ba24aa60346a9b1812479ed66cb329f394a4b1c7
FUJI_C_CHAIN_BLOCKCHAIN_ID_HEX=0x31233cae135e3974afa396e90f465aa28027de5f97f729238c310d2ed2f71902

# Incentevize a Relayer
FEE_TOKEN_ADDRESS=your_example_erc20_address
```

3. Load the environment:
```bash
source .env
```

4. Verify your configuration:
```bash
# Should show your wallet address
echo $FUNDED_ADDRESS
```

<Callout type="warn" title="The private key is for testing only. Never use it in production or share it with anyone. Do not use a private key holding real funds on testnet, separate mainnet and testnet keys!" />

</Step>
</Steps>

# Close and Reopen Codespace (/academy/interchain-messaging/03-avalanche-starter-kit/03-close-and-reopen-codespace)

---
title: Close and Reopen Codespace
description: Environment Setup
updated: 2024-05-31
authors: [martineckardt]
icon: Terminal
---

import CloseAndReopen from "@/content/common/codespaces/close-and-reopen-codespace.mdx";

<CloseAndReopen />

# Getting Test Tokens (/academy/interchain-messaging/03-avalanche-starter-kit/04-networks)

---
title: Getting Test Tokens
description: Fund your wallet for development
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

Before you can deploy contracts or send transactions, you'll need test tokens on both the Fuji C-Chain and Dispatch networks.

## Getting Test Tokens

1. Open Core wallet and switch to Fuji Testnet:
   - Click the network selector (top of window)
   - Select "Fuji (C-Chain)"

2. Get test tokens:
   - **Recommended:** Create a [Builder Hub account](https://build.avax.network/login) and connect your wallet to receive tokens automatically on C-Chain and Dispatch
   - **Alternative:** Use external faucets:
     - Fuji C-Chain: [Faucet](https://core.app/tools/testnet-faucet/?subnet=c&token=c) with code **avalanche-academy**
     - Dispatch: [Faucet](https://core.app/tools/testnet-faucet/?subnet=dispatch&token=dispatch)

3. Verify your balances inside of the codespace, you should have **2 AVAX** and **2 DIS**:
```bash
# Check balance on Fuji C-Chain
cast balance $FUNDED_ADDRESS --rpc-url fuji-c

# Check balance on Dispatch
cast balance $FUNDED_ADDRESS --rpc-url fuji-dispatch
```

You can also check your balance from the core extension, don't forget to toggle **testnet mode** inside the advanced settings.

## Available Networks

For this course, we'll be using two testnet networks:

### Fuji C-Chain
- RPC URL: https://api.avax-test.network/ext/bc/C/rpc
- Chain ID: 43113
- Native Token: AVAX
- Teleporter Messenger: 0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf
- Teleporter Registry: 0xF86Cb19Ad8405AEFa7d09C778215D2Cb6eBfB228

### Dispatch Testnet
- RPC URL: https://subnets.avax.network/dispatch/testnet/rpc
- Chain ID: 779672
- Native Token: DISP
- Teleporter Messenger: 0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf
- Teleporter Registry: 0xF86Cb19Ad8405AEFa7d09C778215D2Cb6eBfB228

<Callout type="info">
Both networks are configured with the same Teleporter Messenger and Registry address for seamless cross-chain communication.
</Callout>

# Contract Development with Foundry (/academy/interchain-messaging/03-avalanche-starter-kit/05-foundry-quickstart)

---
title: Contract Development with Foundry
description: Deploy and interact with smart contracts
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

Now that your environment is set up and funded, let's understand the key Foundry commands we'll be using throughout this tutorial.

## Understanding Foundry Commands

### forge create
The `forge create` command is used for deploying smart contracts. Key aspects:
- Requires an RPC URL to specify which network to deploy to
- Needs a private key for transaction signing
- Can handle constructor arguments if your contract needs them
- Returns the deployed contract's address
- Supports contract verification on block explorers

### cast send
`cast send` is used for state-changing interactions with contracts. This includes:
- Sending transactions that modify contract state
- Calling functions that require gas
- Approving token transfers
- Executing contract functions with parameters
- Requires private key for transaction signing

### cast call
`cast call` is for read-only operations that don't modify state:
- Reading contract state variables
- Calling view/pure functions
- Doesn't require gas or transaction signing
- Returns function results immediately
- Useful for verifying contract state

## Development Best Practices

1. Always test with small transactions first
2. Save contract addresses in environment variables
3. Double-check network configurations and addresses
4. Monitor transactions in block explorers
5. Keep private keys secure and never commit them

## Learn More

For more detailed information:
- [Foundry Book](https://book.getfoundry.sh/)
- [Avalanche Documentation](https://docs.avax.network/)
- [Teleporter Documentation](https://docs.avax.network/build/cross-chain/teleporter/overview)

# ICM Basics (/academy/interchain-messaging/04-icm-basics/01-icm-basics)

---
title: ICM Basics
description: Learn about the Avalanche Interchain Messaging basics.
updated: 2024-05-31
authors: [martineckardt]
icon: Book
---

<YouTube id="7QZ7_qZfQOA" />

Teleporter enables you to send messages from one blockchain to another blockchain in the Avalanche network by simply calling the `sendCrossChainMessage` on the `TeleporterMessenger` contract. This invokes a smart contract on another Avalanche L1, where the called contract implements the `ITeleporterReceiver` interface to receive messages on the destination Avalanche L1. We will look at what happens under the hood in a later chapter.

![](/common-images/teleporter/teleporter-source-destination.png)

## What You Will Learn

In this section, you will go through the following topics:

- **Recap: Bytes, Encoding, and Decoding:** Understand how data is encoded and decoded in bytes
- **Sending messages:** Write your first simple sender contract
- **Receiving messages:** Write your first simple receiver contract

## Exercise
You will apply your learned knowledge by building your first Cross-Chain application! This application will be deployed on two chains: the Fuji testnet (C-Chain) and the Dispatch test L1.

Therefore, you will deploy two contracts:

- **Sender on Fuji C-Chain:** Send a message with a simple string
- **Receiver on Dispatch test L1:** Receives the message and saves the most recent string

At the end of the section, you will be adapting the example to build an 'Adder'. This application is similar to the example above, but the message will include a number. The receiving contract keeps track of the sum of all sent numbers. 


# Recap of Bytes, Encoding and Decoding (/academy/interchain-messaging/04-icm-basics/02-recap-bytes-encoding-decoding)

---
title: Recap of Bytes, Encoding and Decoding
description: Recap message encoding/decoding.
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

When we send an interchain message, we are just sending a single value of type bytes. This value can contain multiple values of various types (e.g. string, uint & address) using encoding and decoding. 

In this section we will recap these topics:

- **Bytes:** What is this data type and why are we using it? 
- **Encoding:** How do we turn values into bytes?
- **Decoding:** How can we turn the bytes back into the values?

We will use these concepts a lot going forward for our messages we send, so make sure you read this carefully.

## Bytes
In Solidity, the bytes data type serves as a versatile container for encoding multiple values of different types into a single unified value. You can think of it as a flexible box that can hold various forms of data, such as integers, text, images, or any binary information. The bytes data type allows you to mix and match these different types of data and put them all in one box.

This makes it a pragmatic choice for encapsulating diverse data and data type ensures that all the data is efficiently packaged into a single unit for transfer, and recipients can decode and extract the individual components as needed.

## Encoding & Decoding

In Solidity we can use the functions `abi.encode()` and `abi.decode()` for encoding and decoding. These are part of the solidity language, so we do not need to import anything to use them.

![Encoding and Decoding](/common-images/solidity/encoding-decoding.png)

### Encoding
When we encode data, we convert it into a byte array. This is useful when we want to send data from one contract to another. We can encode multiple values into a single byte array, which can then be decoded by the receiving contract.

```solidity
string memory someString = "test";
uint someNumber = 42;

bytes message = abi.encode(someString, someNumber);
```

This single value message here we can now use as a message for Teleporter.

### Decoding
When we decode data, we convert it from a byte array back into its original form. This is useful when we receive data from another contract. We can decode the byte array into its original values.

```solidity
( 
  string memory someString,
  uint someNumber
) = abi.decode(message, (string, uint));
```

This will give us back the original values that we encoded before. Note that we do need to know the types of the values and their order that we encoded to decode them correctly.

<Quiz quizId="303"/>

# Sending a Message (/academy/interchain-messaging/04-icm-basics/03-sending-a-message)

---
title: Sending a Message
description: Learn to send messages with Avalanche Interchain Messaging.
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

Sending a message is nothing more than a simple contract call to the Interchain Messaging messenger contract.

<img src="/common-images/teleporter/teleporter-source.png" width="400" class="mx-auto"/>

The dApp on the Source L1 has to call the `sendCrossChainMessage` function of the Interchain Messaging contract. The Interchain Messaging contract implements the `ITeleporterMessenger` interface below. Note that the dApp itself does not have to implement the interface.

```solidity title="/lib/icm-contracts/contracts/teleporter/ITeleporterMessenger.sol"
pragma solidity 0.8.18;

struct TeleporterMessageInput {
    bytes32 destinationBlockchainID;
    address destinationAddress;
    TeleporterFeeInfo feeInfo;
    uint256 requiredGasLimit;
    address[] allowedRelayerAddresses;
    bytes message;
}

struct TeleporterFeeInfo {
    address feeTokenAddress;
    uint256 amount;
}

/**
 * @dev Interface that describes functionalities for a cross chain messenger.
 */
interface ITeleporterMessenger {
    /**
     * @dev Emitted when sending a interchain message cross chain.
     */
 	event SendCrossChainMessage(
        uint256 indexed messageID,
        bytes32 indexed destinationBlockchainID,
        TeleporterMessage message,
        TeleporterFeeInfo feeInfo
    );

    /**
     * @dev Called by transactions to initiate the sending of a cross L1 message.
     */
	function sendCrossChainMessage(TeleporterMessageInput calldata messageInput)
        external
        returns (uint256);

}
```

The `sendCrossChainMessage` function takes `TeleporterMessageInput` struct as an input. In that multiple values are contained: This data will then be included in the payload of the Warp message:

- **`destinationChainID`:** The blockchainID in hex where the contract that should receive the message is deployed. This is not the EVM chain ID you may know from adding a network to a wallet, but the blockchain ID on the P-Chain. The P-Chain uses the transaction ID of the transaction that created those blockchain on the P-Chain for the chain ID, e.g.: 0xd7cdc6f08b167595d1577e24838113a88b1005b471a6c430d79c48b4c89cfc53
- **`destinationAddress`:** The address of the contract that should receive the message
- **`feeInfo`:** A struct consisting of a contract address of an ERC20 which the fee is paid in as well as the amount of tokens to be paid as an incentive for the relayer. We will look at this later in more detail.
- **`requiredGasLimit`:** The amount of gas the delivery of the message requires. If the relayer provides the required gas, the message will be considered delivered whether or not its execution succeeds, such that the relayer can claim their fee reward.
- **`allowedRelayerAddresses`:** An array of addresses of allowed relayers. An empty allowed relayers list means anyone is allowed to deliver the message. We will look at this later in more detail.
- **`message`:** The message to be sent as bytes. The message can contain multiple encoded values. DApps using Interchain Messaging are responsible for defining the exact format of this payload in a way that can be decoded on the receiving end. The message can hold multiple values that be encoded in a single bytes object. For example, applications may encode multiple method parameters on the sending side, then decode this data in the contract implementing the receiveTeleporterMessage function and call another contract with the parameters from there.

<Quiz quizId="304"/>

# Sender Contract (/academy/interchain-messaging/04-icm-basics/04-create-sender-contract)

---
title: Sender Contract
description: Create a contract to send messages with Teleporter.
updated: 2024-05-31
authors: [martineckardt]
icon: Terminal
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

Lets start by deploying our sender contract on C-Chain. It will be responsible for calling the the TeleporterMessenger contract, encoding our message and sending it to the destination chain. 

<Steps>
<Step>
### Read the Sender Contract

The following contract is located inside `contracts/interchain-messaging/send-receive` directory. Read through the contract below and and understand what is happening:

```solidity title="contracts/interchain-messaging/send-receive/senderOnCChain.sol"
// (c) 2023, Ava Labs, Inc. All rights reserved.
// See the file LICENSE for licensing terms.

// SPDX-License-Identifier: Ecosystem

pragma solidity ^0.8.18;

import "@teleporter/ITeleporterMessenger.sol"; // [!code highlight]

contract SenderOnCChain {
    ITeleporterMessenger public immutable messenger = ITeleporterMessenger(0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf); // [!code highlight]

    /**
     * @dev Sends a message to another chain.
     */
    function sendMessage(address destinationAddress, string calldata message) external {
        messenger.sendCrossChainMessage( // [!code highlight]
            TeleporterMessageInput({
                // BlockchainID of Dispatch L1
                destinationBlockchainID: 0x9f3be606497285d0ffbb5ac9ba24aa60346a9b1812479ed66cb329f394a4b1c7, // [!code highlight]
                destinationAddress: destinationAddress, 
                feeInfo: TeleporterFeeInfo({feeTokenAddress: address(0), amount: 0}),
                requiredGasLimit: 100000,
                allowedRelayerAddresses: new address[](0),
                message: abi.encode(message)
            })
        );
    }
}
```

The key things to understand:

- **Importing ITeleporterMessenger (Line 8):** We are importing the `ITeleporterMessenger` Interface we looked at in the previous activity.
- **Defining teleporterMessenger contract (Line 12):** We are defining a `teleporterMessenger` contract using the imported interface. It is important to note, that our cross-chain dApp is not implementing the interface itself, but initializes a contract using that interface.
- **Sending the message (Line 21):** We are sending the message by calling the function of our `teleporterMessenger`. As an input we are defining a `TeleporterMessageInput`. The `destinationChainId` should be set to the Dispatch test L1's blockchain ID. We will need to provide the address of the receiving contract on the Dispatch test L1 as a parameter to the function, since we have not deployed it yet and don't know the address at this time.   
- **No fees (Line 25):** In this exercise we are not providing any fees to the relayer for relaying the message. This is only possible since the relayer we are running here is configured to pick up any message even if it does not provide any rewards.
- **Encoding the Message (Line 31):** The `TeleporterMessageInput` defines a message as an array of bytes. For now we will just simply encode the string with `abi.encode()`. In the future activities, you will see how we can encode multiple values of any type in that message.
- **Hardcoded destinationBlockchainId:** For this course, we are using Dispatch, but normally you will have to replace the `destinationBlockchainID` with whatever chain you want to send a message to.

</Step>
<Step>

### Deploy Sender Contract

To deploy a contract using Foundry use the following command:

```bash
forge create --rpc-url fuji-c --private-key $PK --broadcast contracts/interchain-messaging/send-receive/senderOnCChain.sol:SenderOnCChain
```
```
[⠊] Compiling...
[⠒] Compiling 2 files with Solc 0.8.18
[⠢] Solc 0.8.18 finished in 81.53ms
Compiler run successful!
Deployer: 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC // [$FUNDED_ADDRESS]
Deployed to: 0x5DB9A7629912EBF95876228C24A848de0bfB43A9 // [$SENDER_ADDRESS]
Transaction hash: 0xcde7873e9e3c68fb00a2ad6644dceb64a01a41941da46de5a0f559d6d70a1638
```
</Step>
<Step>

### Save Sender Address

Then save the sender contract address in an environment variable:

```bash
export SENDER_ADDRESS={your-sender-address}
```

</Step>
</Steps>

# Receiving a Message (/academy/interchain-messaging/04-icm-basics/05-receiving-a-message)

---
title: Receiving a Message
description: Learn to receive messages with Avalanche Interchain Messaging.
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

To receive a message we need to enable our cross-L1 dApps to being called by the Interchain Messaging contract.

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/teleporter/teleporter-source-destination-with-relayer-SvUFYGP77XxLjoyWqf7IpC85Ssxmmo.png)

The Interchain Messaging does not know our contract and what functions it has. Therefore, our dApp on the destination L1 has to implement the ITeleporterReceiver interface. It is very straight forward and only requires a single method for receiving the message that then can be called by the Interchain Messaging contract:

```solidity
pragma solidity 0.8.18;

/**
 * @dev Interface that cross-chain applications must implement to receive messages from Teleporter.
 */
interface ITeleporterReceiver {
    /**
     * @dev Called by TeleporterMessenger on the receiving chain.
     *
     * @param originChainID is provided by the TeleporterMessenger contract.
     * @param originSenderAddress is provided by the TeleporterMessenger contract.
     * @param message is the TeleporterMessage payload set by the sender.
     */
    function receiveTeleporterMessage(
        bytes32 originChainID,
        address originSenderAddress,
        bytes calldata message
    ) external;
}
```

The function receiveTeleporterMessage has three parameters:

- **`originChainID`**: The chainID where the message originates from, meaning where the user or contract called the `sendCrossChainMessage` function of the Interchain Messaging contract
- **`originSenderAddress`**: The address of the user or contract that called the `sendCrossChainMessage` function of the Interchain Messaging contract on the origin L1
- **`message`**: The message encoded in bytes

An example for a contract being able to receive Interchain Messaging messages and storing these in a mapping could look like this:

```solidity
pragma solidity 0.8.18;

import "https://github.com/ava-labs/teleporter/blob/main/contracts/src/Teleporter/ITeleporterMessenger.sol";
import "https://github.com/ava-labs/teleporter/blob/main/contracts/src/Teleporter/ITeleporterReceiver.sol";

contract MessageReceiver is ITeleporterReceiver {
    // Messages sent to this contract.
    struct Message {
        address sender;
        string message;
    }
  
  	mapping(bytes32 => Message) private _messages;

    ITeleporterMessenger public immutable teleporterMessenger;

    // Errors
    error Unauthorized();

    constructor(address teleporterMessengerAddress) {
        teleporterMessenger = ITeleporterMessenger(teleporterMessengerAddress);
    }

    /**
     * @dev See {ITeleporterReceiver-receiveTeleporterMessage}.
     *
     * Receives a message from another chain.
     */
    function receiveTeleporterMessage(
        bytes32 originChainID,
        address originSenderAddress,
        bytes calldata message
    ) external {
      	// Only the Interchain Messaging receiver can deliver a message.
        if (msg.sender != address(teleporterMessenger)) {
            revert Unauthorized();
        }
      
        string memory messageString = abi.decode(message, (string));
        _messages[originChainID] = Message(originSenderAddress, messageString);
    }

}
```

This contract stores the last `Message` and it's sender of each chain it has received. When it is instantiated, the address of the Interchain Messaging contract is supplied to the constructor. The contract implements the `ITelepoterReceiver` interface and therefore we also implement the `receiveTeleporterMessage` function. 

<Quiz quizId="305"/>

# Receiver Contract (/academy/interchain-messaging/04-icm-basics/06-create-receiver-contract)

---
title: Receiver Contract
description: Create a contract to receive messages with Teleporter.
updated: 2024-05-31
authors: [martineckardt]
icon: Terminal
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

Now it's time to deploy our receiver contract to our L1. It will implement the callback for the `TeleporterMessenger` contract when the message is received, decoding our message and storing the last received string. 

<Steps>
<Step>

### Read the Receiver Contract

The following contract is located inside `contracts/interchain-messaging/send-receive` directory. Read through the contract below and and understand what is happening:

```solidity title="contracts/interchain-messaging/send-receive/receiverOnDispatch.sol"
// (c) 2023, Ava Labs, Inc. All rights reserved.
// See the file LICENSE for licensing terms.

// SPDX-License-Identifier: Ecosystem

pragma solidity ^0.8.18;

import "@teleporter/ITeleporterMessenger.sol";
import "@teleporter/ITeleporterReceiver.sol";

contract ReceiverOnDispatch is ITeleporterReceiver {
    ITeleporterMessenger public immutable messenger = ITeleporterMessenger(0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf);

    string public lastMessage;

    function receiveTeleporterMessage(bytes32, address, bytes calldata message) external {
        // Only the Interchain Messaging receiver can deliver a message.
        require(msg.sender == address(messenger), "ReceiverOnDispatch: unauthorized TeleporterMessenger");

        // Store the message.
        lastMessage = abi.decode(message, (string));
    }
}
```

**The key things to understand:**
- **Importing Interchain Messaging contracts (L8, L9):** We are importing the `ITeleporterMessenger` and `ITeleporterReceiver` interface we looked at in the previous activity.
- **Inheriting from ITeleporterReceiver (L11):** We are inheriting the interface that will require us to implement the `receiveTeleporterMessage()` function.
- **Defining the lastMessage variable (L14):** Setting the `lastMessage` variable as `public`, will make that variable readable from the outside without the need of a `getValue` function.
- **Implementing receiveTeleporterMessage (L16):** We implement the function that will be called when the message is received. Please note that we are not checking who calls that function for now. So anyone can pretend to deliver messages for now.
- **Decode message (L21):** We decode the message using `abi.decode(message, (string))`, which takes the bytes array as the first input and a tuple of the types of the encoded data in the message. Since our message only contains a single value, the tuple only has one value.

</Step>
<Step>

### Deploy Receiver Contract

To deploy a contract using Foundry use the following command:

```bash
forge create --rpc-url fuji-dispatch --private-key $PK contracts/interchain-messaging/send-receive/receiverOnDispatch.sol:ReceiverOnDispatch --broadcast
```
```
[⠊] Compiling...
[⠢] Compiling 2 files with Solc 0.8.18
[⠆] Solc 0.8.18 finished in 158.51ms
Compiler run successful!
Deployer: 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC // [$FUNDED_ADDRESS]
Deployed to: 0x52C84043CD9c865236f11d9Fc9F56aa003c1f922 // [$RECEIVER_ADDRESS]
Transaction hash: 0x48a1ffaa8aa8011f842147a908ff35a1ebfb75a5a07eb37ae96a4cc8d7feafd7
```

<Step>
</Step>

### Save Receiver Contract Address

Then save the receiver contract address in an environment variable:

```bash
export RECEIVER_ADDRESS={your-receiver-address}
```

</Step>
</Steps>

# Send a Message (/academy/interchain-messaging/04-icm-basics/07-send-a-message)

---
title: Send a Message
description: Send your first Cross-Chain message with Teleporter.
updated: 2024-05-31
authors: [martineckardt]
icon: Terminal
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

The final step, is to send the message between the two chains. Assuming everything went smooth so far, your local C-chain and your Avalanche L1 will have their corresponding parts of the sender/receiver deployed on them.

<Steps>
<Step>

### Send a Message

```bash
cast send --rpc-url fuji-c --private-key $PK $SENDER_ADDRESS "sendMessage(address,string)" $RECEIVER_ADDRESS "Hello"
```

A relayer will now take the message and deliver it to the destination.

</Step>
<Step>

### Verify Message was Received

Now let's check if the "Hello" string sent from our C-chain was actually stored properly on the `lastMessage` variable on our Avalanche L1. Run the following command replacing the receiver contract address.

```bash
cast call --rpc-url fuji-dispatch $RECEIVER_ADDRESS "lastMessage()(string)"
```

If the output says `Hello` then the message was successfully delivered and processed.

</Step>
</Steps>


Congratulations 🎉 You have just sent your first cross-chain message. This will be one of many to come!

# Adapt the contract (/academy/interchain-messaging/04-icm-basics/08-adapting-the-contract-exercise)

---
title: Adapt the contract
description: Assignment- Modify the Cross-Chain Messenger.
updated: 2024-05-31
authors: [martineckardt]
icon: Terminal
---

To create a deeper understanding of the concepts, now change the provided contracts. Instead of sending a string, now send a number and add up the numbers on the destination chain:

Once you finished with the assignment you can review the correct answer at `/contracts/interchain-messaging/send-receive-assignment-solution` in the [Avalanche-Starter-Kit](https://github.com/ava-labs/avalanche-starter-kit/tree/interchain-messaging/contracts/interchain-messaging/send-receive-assignment-solution)


# Two-Way Communication (/academy/interchain-messaging/05-two-way-communication/01-two-way-communication)

---
title: Two-Way Communication
description: Learn about roundtrip messages.
updated: 2024-05-31
authors: [martineckardt]
icon: Book
---

When we send messages with Interchain Messaging, we can check if a message has been delivered, but we do not get any feedback wether the message has been processed correctly or any return value. If we wanted to achieve this, we need to send a message back from the receiver to the original sender.

![](/common-images/teleporter/two-way-communication.png)

## What You Will Learn

In this section, you will go through the following topics:

- **Sender & Receiver:** Understand how we need to change the contracts to send a message back
- **Send & Track:** Send a roundtrip message and follow the logs
- **Adapt the example:** Take what you learned and adapt the example

## Exercises
You will apply your learned knowledge by building your first Cross-Chain application! This application will be deployed on two chains: the Fuji testnet (C-Chain) and the Dispatch test L1.

Therefore, you will deploy two contracts:

- **Sender on Fuji C-Chain:** Send a message with a simple string
- **Receiver on Dispatch test L1:** Receives the message, adds something to the string and send it back

At the end of the section, you will be adapting the example to build a cross-chain Avalanche L1 dApp that send a number to a contract on another Avalanche L1 then receives the result of a mathematical operation. This application is similar to the example above, but the message will include a number. The receiving contract will perform a mathematical operation. 

# Sender Contract (/academy/interchain-messaging/05-two-way-communication/02-sender-contract)

---
title: Sender Contract
description: Adapt the sender contract to also receive messages
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

The sender contract has now two tasks: 

- **Send a message to the receiver**: Same as in the last example
- **Receive a message back from the receiver**: Now our sender contract needs to be able to receive a message back from the receiver.

Therefore, we need to change the sender contract to be able to receive a message back. We will need to implement the same interface `ITeleporterReceiver` as the receiver contract and implement the `receiveTeleporterMessage` function. 

```solidity title="contracts/interchain-messaging/send-roundtrip/senderOnCChain.sol"
// (c) 2023, Ava Labs, Inc. All rights reserved.
// See the file LICENSE for licensing terms.

// SPDX-License-Identifier: Ecosystem

pragma solidity ^0.8.18;

import "@teleporter/ITeleporterMessenger.sol";
import "@teleporter/ITeleporterReceiver.sol"; // [!code highlight]

contract SenderOnCChain is ITeleporterReceiver { // [!code highlight]
    ITeleporterMessenger public immutable messenger = ITeleporterMessenger(0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf);

    string public roundtripMessage;

    /**
     * @dev Sends a message to another chain.
     */
    function sendMessage(address destinationAddress) external {
        messenger.sendCrossChainMessage(
            TeleporterMessageInput({
                // BlockchainID of Dispatch L1
                destinationBlockchainID: 0x9f3be606497285d0ffbb5ac9ba24aa60346a9b1812479ed66cb329f394a4b1c7,
                destinationAddress: destinationAddress,
                feeInfo: TeleporterFeeInfo({feeTokenAddress: address(0), amount: 0}),
                requiredGasLimit: 100000,
                allowedRelayerAddresses: new address[](0),
                message: abi.encode("Hello")
            })
        );
    }

    function receiveTeleporterMessage(bytes32, address, bytes calldata message) external { // [!code highlight:7]
        // Only the Interchain Messaging receiver can deliver a message.
        require(msg.sender == address(messenger), "SenderOnCChain: unauthorized TeleporterMessenger");

        // Store the message.
        roundtripMessage = abi.decode(message, (string));
    }
}
```

# Create the Sender Contract (/academy/interchain-messaging/05-two-way-communication/03-create-sender-contract)

---
title: Create the Sender Contract
description: Deploy roundtrip sender contract
updated: 2024-05-31
authors: [martineckardt]
icon: Terminal
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

Go ahead and deploy the sender contract on the C-Chain. 

<Steps>
<Step>

### Deploy the Sender Contract

```bash
forge create --rpc-url fuji-c --private-key $PK contracts/interchain-messaging/send-roundtrip/senderOnCChain.sol:SenderOnCChain --broadcast
```
```
[⠊] Compiling...
[⠢] Compiling 1 files with Solc 0.8.18
[⠆] Solc 0.8.18 finished in 165.79ms
Compiler run successful!
Deployer: 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC // [$FUNDED_ADDRESS]
Deployed to: 0xA4cD3b0Eb6E5Ab5d8CE4065BcCD70040ADAB1F00 // [$SENDER_ADDRESS]
Transaction hash: 0x4f41cf829fbc525b64d9773c41dc9fabb3b93dfd03bf6c1568dcc4a4c6bdeb1a
```
</Step>
<Step>

### Update the Sender Address

Overwrite the `SENDER_ADDRESS` environment variable with the new address:

```bash
export SENDER_ADDRESS={your-sender-address}
```
</Step>
</Steps>

# Receiver Contract (/academy/interchain-messaging/05-two-way-communication/04-receiver-contract)

---
title: Receiver Contract
description: Adapt the receiver contract to send messages back
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

The receiver contract now has two tasks: 

- **Receive a message from the sender**: Same as in the [last example](/academy/interchain-messaging/04-icm-basics/05-receiving-a-message)
- **Send a message back to the sender**: Now our receiver contract needs to be able to send a message back to the sender.

Therefore, we need to change the receiver contract to be able to send a message back. We will need to instantiate a `TeleporterMessenger` and call the `sendCrossChainMessage()` function. 

```solidity title="contracts/interchain-messaging/send-roundtrip/receiverOnDispatch.sol"
// (c) 2023, Ava Labs, Inc. All rights reserved.
// See the file LICENSE for licensing terms.

// SPDX-License-Identifier: Ecosystem

pragma solidity ^0.8.18;

import "@teleporter/ITeleporterMessenger.sol"; // [!code highlight]
import "@teleporter/ITeleporterReceiver.sol";

contract ReceiverOnDispatch is ITeleporterReceiver {
    ITeleporterMessenger public immutable messenger = ITeleporterMessenger(0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf); // [!code highlight]

    function receiveTeleporterMessage(bytes32 sourceBlockchainID, address originSenderAddress, bytes calldata message)
        external
    {
        // Only the Interchain Messaging receiver can deliver a message.
        require(msg.sender == address(messenger), "ReceiverOnDispatch: unauthorized TeleporterMessenger");

        // Send Roundtrip message back to sender
        string memory response = string.concat(abi.decode(message, (string)), " World!");

        messenger.sendCrossChainMessage( // [!code highlight:9]
            TeleporterMessageInput({
                // Blockchain ID of C-Chain
                destinationBlockchainID: sourceBlockchainID,
                destinationAddress: originSenderAddress,
                feeInfo: TeleporterFeeInfo({feeTokenAddress: address(0), amount: 0}),
                requiredGasLimit: 100000,
                allowedRelayerAddresses: new address[](0),
                message: abi.encode(response)
            })
        );
    }
}
```



# Create the Receiver Contract (/academy/interchain-messaging/05-two-way-communication/05-create-the-receiver-contract)

---
title: Create the Receiver Contract
description: Deploy roundtrip receiver contract
updated: 2024-05-31
authors: [martineckardt]
icon: Terminal
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

Go ahead and deploy the receiver contract:

<Steps>
<Step>

### Deploy the Receiver Contract

```bash
forge create --rpc-url fuji-dispatch --private-key $PK contracts/interchain-messaging/send-roundtrip/receiverOnDispatch.sol:ReceiverOnDispatch --broadcast
```
```
[⠊] Compiling...
[⠢] Compiling 1 files with Solc 0.8.18
[⠆] Solc 0.8.18 finished in 101.71ms
Compiler run successful!
Deployer: 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC // [$FUNDED_ADDRESS]
Deployed to: 0x17aB05351fC94a1a67Bf3f56DdbB941aE6c63E25 // [$RECEIVER_ADDRESS]
Transaction hash: 0x11df9e14bdae4af60a618a900faa955d75e0ce7dd0f2ccc1ea6a764c149ef805
```

</Step>
<Step>

### Update the Receiver Address

Update the `RECEIVER_ADDRESS` environment variable with the new address:
```bash
export RECEIVER_ADDRESS={your-receiver-address}
```

</Step>
</Steps> 

# Send a Roundtrip Message (/academy/interchain-messaging/05-two-way-communication/06-send-a-roundtrip-message)

---
title: Send a Roundtrip Message
description: Send roundtrip message
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

Alright, now let's send the message:

<Steps>
<Step>
### Send the Message:

```bash 
cast send --rpc-url fuji-c --private-key $PK $SENDER_ADDRESS "sendMessage(address)" $RECEIVER_ADDRESS
```

</Step>
<Step>

### Verify Message Receipt

To check whether the message has been received, we can call the `roundtripMessage()` function on the sender contract. 

```bash
cast call --rpc-url fuji-c $SENDER_ADDRESS "roundtripMessage()(string)"
```
If successful, you should see the following output:
```bash
"Hello World!"
```

</Step>
{/* TODO: Add instructions for setting up and running the relayer in Docker before this section
<Step>

### Check the Relayer Logs

To understand in more detail what happened, check out the relayer logs:

```bash
avalanche interchain relayer logs
```

</Step>
*/}
</Steps>


# Adapt the Contracts (/academy/interchain-messaging/05-two-way-communication/07-adapt-the-contracts)

---
title: Adapt the Contracts
description: Assignment - Modify the roundtrip messenger dApp
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

Taking what you've learned in the previous chapter, adapt the sender to send a number instead of a string. The receiver should now multiply the number by 2 and send it back to the sender. The sender saves the result in a public variable.

# Invoking Functions (/academy/interchain-messaging/06-invoking-functions/01-invoking-functions)

---
title: Invoking Functions
description: Learn how to invoke functions on destination.
updated: 2024-05-31
authors: [martineckardt]
icon: Book
---

<YouTube id="fl9bF7xzHXc" />

Well done, you successfully learned how to send simple data back and forth between blockchains. In this section we will look further and invoke a smart contract function on the destination chain. 

![](/common-images/teleporter/invoking-functions.png)

## What You Will Learn

In this section, you will go through the following topics:

- **Encoding:** Most smart contract functions have multiple parameters. So the first thing we will learn is how to encode multiple values in the message
- **Specify which function to call:** Most smart contracts have multiple functions. We will learn how to specify which function to call and encode different parameters depending on which function is been called

## Exercise

In this section you will apply the learned knowledge by building a cross-chain dApp where multiple functions are called on the destination chain.

- Build a Calculator that takes two parameters and adds them up
- Modify the Calculator to support more functions that can be called from the source Avalanche L1


# Encoding of multiple Values (/academy/interchain-messaging/06-invoking-functions/02-encoding-multiple-values)

---
title: Encoding of multiple Values
description: Learn how to encode multiple function parameters
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

In this section, we will learn how to pack multiple values into a single message.

![](/common-images/teleporter/message-multiple-parameters.png)

We can use `abi.encode()` to encode multiple values into a single byte array:

```solidity
bytes message = abi.encode(
      someString,
      someNumber,
      someAddress
  );
```

Here we can see how the function `abi.encode()` is used to turn multiple values `(someString, someNumber & someAddress)` of various types `(string, uint & address)` into a single value of the type bytes called `message`. This bytearray can then be sent to the destination chain using the Teleporter. 

```solidity
function sendMessage(address destinationAddress) external returns (uint256 messageID) {
  string someString = "test";
  uint someNumber = 43;
  address someAddress = address(0);

  bytes message = abi.encode( // [!code highlight:4]
      someString,
      someNumber,
      someAddress
  );

  return teleporterMessenger.sendCrossChainMessage(
      TeleporterMessageInput({
        destinationChainID: destinationChainID,
        destinationAddress: destinationAddress,
        feeInfo: TeleporterFeeInfo({
          feeTokenAddress: feeContractAddress,
          amount: adjustedFeeAmount
        }),
        requiredGasLimit: requiredGasLimit,
        allowedRelayerAddresses: new address[](0),
        message: message // [!code highlight]
      })
  );
}
```

The receiving contract can then decode the byte array back into its original values:

```solidity
function receiveTeleporterMessage(
  bytes32 originChainID,
  address originSenderAddress,
  bytes calldata message
) external {
  // Only the Interchain Messaging receiver can deliver a message.
  if (msg.sender != address(teleporterMessenger)) {
    revert Unauthorized();
  }

  // Decoding the function parameters // [!code highlight:6]
  (
    string someString,
    uint256 someNumber,
    address someAddress
  ) = abi.decode(message, (string, uint256, address));
  
  // Calling the internal function
  _someFunction(someString, someNumber, someAddress) // [!code highlight]
  
}

function _someFunction(string someString, uint256 someNumber, address someAddress) private {
  // Do something
}
```


Here we are using `abi.decode()` to unpack the three values `(someString, someNumber & someAddress)` from the parameter `message` of the type `bytes`. As you can see, we need to provide the message as well as the types of values encoded in the message. It is important to note the types must be the same order as parameters to `abi.decode()`. 

```solidity
(
  string memory someString,
  uint someNumber,
  address someAddress
) = abi.decode(message, (string, uint, address));  // [!code highlight]
``` 
<Quiz quizId="306"/>

# Create Simple Calculator Sender (/academy/interchain-messaging/06-invoking-functions/03-create-simple-calculator-sender)

---
title: Create Simple Calculator Sender
description: Create a contract that sends multiple parameters of a function
updated: 2024-05-31
authors: [martineckardt]
icon: Terminal
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

Now, our goal is to create a dApp that works as a cross-Avalanche L1 Calculator, receiving multiple parameters and using those for a calculation. For now our calculator will only have the `Sum` function.

<Steps>
<Step>

### Create Sender Contract

On the Fuji C-Chain, we need to create the sender part of our cross-chain calculator. This will send two numbers (uint) to the receiver contract on the Dispatch test L1. 

```solidity title="contracts/interchain-messaging/invoking-functions/SimpleCalculatorSenderOnCChain.sol"
pragma solidity ^0.8.18;

import "@teleporter/ITeleporterMessenger.sol";

contract SimpleCalculatorSenderOnCChain {
    ITeleporterMessenger public immutable teleporterMessenger =
        ITeleporterMessenger(0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf);

    function sendAddMessage(address destinationAddress, uint256 num1, uint256 num2) external {
        teleporterMessenger.sendCrossChainMessage(
            TeleporterMessageInput({
                // BlockchainID of Dispatch L1
                destinationBlockchainID: 0x9f3be606497285d0ffbb5ac9ba24aa60346a9b1812479ed66cb329f394a4b1c7,
                destinationAddress: destinationAddress,
                feeInfo: TeleporterFeeInfo({feeTokenAddress: address(0), amount: 0}),
                requiredGasLimit: 100000,
                allowedRelayerAddresses: new address[](0),
                message: encodeAddData(num1, num2)
            })
        );
    }

    //Encode helpers
    function encodeAddData(uint256 a, uint256 b) public pure returns (bytes memory) {
        bytes memory paramsData = abi.encode(a, b); // [!code highlight]
        return paramsData;
    }
}

```

To increase the readability of the code, we have created a helper function `encodeAddData` that encodes the two numbers into a single byte array.

</Step>
<Step>

### Deploy the Sender Contract

Deploy the sender contract on the Fuji C-Chain:

```bash
forge create --rpc-url fuji-c --private-key $PK contracts/interchain-messaging/invoking-functions/SimpleCalculatorSenderOnCChain.sol:SimpleCalculatorSenderOnCChain --broadcast
```
```
[⠊] Compiling...
[⠒] Compiling 1 files with Solc 0.8.18
[⠢] Solc 0.8.18 finished in 84.20ms
Compiler run successful!
Deployer: 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC // [$FUNDED_ADDRESS]
Deployed to: 0x789a5FDac2b37FCD290fb2924382297A6AE65860 // [$SENDER_ADDRESS]
Transaction hash: 0xd6cb47dd4ff38e4447711ebbec8b646b93f492f48e80b51719f860984cc25413
```
</Step>
<Step>

### Save the Sender Contract Address

Overwrite the `SENDER_ADDRESS` environment variable with the new address:

```bash
export SENDER_ADDRESS={your-sender-address}
```

</Step>
</Steps>

# Create Simple Calculator Receiver (/academy/interchain-messaging/06-invoking-functions/04-create-simple-calulcator-receiver)

---
title: Create Simple Calculator Receiver
description: Create a contract that receives multiple parameters and execute a function
updated: 2024-05-31
authors: [martineckardt]
icon: Terminal
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

On the Dispatch test L1, we need to create the receiver part of our cross-chain calculator. It will receive two numbers and store the result. 

<Steps>
<Step>

### Create Receiver Contract

```solidity title="contracts/interchain-messaging/invoking-functions/SimpleCalculatorReceiverOnDispatch.sol"
pragma solidity ^0.8.18;

import "@teleporter/ITeleporterMessenger.sol";
import "@teleporter/ITeleporterReceiver.sol";

contract SimpleCalculatorReceiverOnDispatch is ITeleporterReceiver {
    ITeleporterMessenger public immutable teleporterMessenger =
        ITeleporterMessenger(0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf);

    uint256 public result_num;

    function receiveTeleporterMessage(bytes32, address, bytes calldata message) external {
        // Only the Interchain Messaging receiver can deliver a message.
        require(
            msg.sender == address(teleporterMessenger), "CalculatorReceiverOnDispatch: unauthorized TeleporterMessenger"
        );

        (uint256 a, uint256 b) = abi.decode(message, (uint256, uint256)); // [!code highlight:2]
        _calculatorAdd(a, b);
    }

    function _calculatorAdd(uint256 _num1, uint256 _num2) internal {
        result_num = _num1 + _num2;
    }
}

```

</Step>
<Step>

### Deploy the Receiver Contract

Deploy the receiver contract on the Dispatch test L1:

```bash
forge create --rpc-url fuji-dispatch --private-key $PK contracts/interchain-messaging/invoking-functions/SimpleCalculatorReceiverOnDispatch.sol:SimpleCalculatorReceiverOnDispatch --broadcast
```

```
[⠊] Compiling...
[⠒] Compiling 1 files with Solc 0.8.18
[⠢] Solc 0.8.18 finished in 44.12ms
Compiler run successful!
Deployer: 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC // [$FUNDED_ADDRESS]
Deployed to: 0x5DB9A7629912EBF95876228C24A848de0bfB43A9 // [$RECEIVER_ADDRESS]
Transaction hash: 0x2d40c53b493556463a28c458e40bc455a248df69a10679bef84145974b7424f3
```

</Step>
<Step>

### Save the Receiver Contract Address

Overwrite the `RECEIVER_ADDRESS` environment variable with the new address:

```bash
export RECEIVER_ADDRESS={your-receiver-address}
```
</Step>
</Steps>


# Call simple Calculator (/academy/interchain-messaging/06-invoking-functions/05-call-simple-calculator)

---
title: Call simple Calculator
description: Execute a function in one chain from another chain
updated: 2024-05-31
authors: [martineckardt]
icon: Terminal
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

Alright, now let's call our Calculators:

<Steps>
<Step>

### Call the Sender Contract

```bash 
cast send --rpc-url fuji-c --private-key $PK $SENDER_ADDRESS "sendAddMessage(address, uint256, uint256)" $RECEIVER_ADDRESS 2 3
```

We need to call the `sendAddMessage` function on the sender contract with the address of the receiver contract and the two numbers we want to add. If you didn't export the sender and receiver address, you will get an executionr reverted error.

For this example we will add 2 + 3.

</Step>
<Step>

### Verify Message Receipt

To check wether the message has been received, we can call the `result_num()` function on the `Receiver` contract. 

```bash
cast call --rpc-url fuji-dispatch $RECEIVER_ADDRESS "result_num()(uint)"
```

```bash
5
```
2 + 3 = 5. Our cross-chain calculation was successful!
</Step>
</Steps>


# Encoding the Function Name (/academy/interchain-messaging/06-invoking-functions/06-encoding-function-name)

---
title: Encoding the Function Name
description: Work with multiple functions in a single Cross-Chain dApp
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

Great work. We can now pack multiple values into a message. In this section, we will learn how to encode the function name and, depending on it, its parameters in the message. Let's imagine a more advanced calculator that not only has a single `add` function but also a `concatenate` function, that lets you concatenate two strings. 

For the add function we need to encode two numbers. For the concatenate function we need to encode two strings. How can we go about this? The concept is easy: It's like packing an envelope into another envelope:

![](/common-images/teleporter/message-function-call.png)

## Ecoding the Function Name and Parameters

The first step is to create a `CalculatorAction` enum that specifies the different functions that can be called on the calculator. 

```solidity title="contracts/interchain-messaging/invoking-functions/CalculatorActions.sol"
pragma solidity ^0.8.18;

enum CalculatorAction {
    add,
    concatenate
}
```

In the next step we can add this to our `encode helpers` in the sender contract:

```solidity title="contracts/interchain-messaging/invoking-functions/CalculatorSenderOnCChain.sol"
pragma solidity ^0.8.18;

import "@teleporter/ITeleporterMessenger.sol";
import "./CalculatorActions.sol"; // [!code highlight]

contract CalculatorSenderOnCChain {
    ITeleporterMessenger public immutable teleporterMessenger =
        ITeleporterMessenger(0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf);

    function sendAddMessage(address destinationAddress, uint256 num1, uint256 num2) external {
        teleporterMessenger.sendCrossChainMessage(
            TeleporterMessageInput({
                // BlockchainID of Dispatch L1
                destinationBlockchainID: 0x9f3be606497285d0ffbb5ac9ba24aa60346a9b1812479ed66cb329f394a4b1c7,
                destinationAddress: destinationAddress,
                feeInfo: TeleporterFeeInfo({feeTokenAddress: address(0), amount: 0}),
                requiredGasLimit: 100000,
                allowedRelayerAddresses: new address[](0),
                message: encodeAddData(num1, num2) // [!code highlight]
            })
        );
    }

    function sendConcatenateMessage(address destinationAddress, string memory text1, string memory text2) external {
        teleporterMessenger.sendCrossChainMessage(
            TeleporterMessageInput({
                // BlockchainID of Dispatch L1
                destinationBlockchainID: 0x9f3be606497285d0ffbb5ac9ba24aa60346a9b1812479ed66cb329f394a4b1c7,
                destinationAddress: destinationAddress,
                feeInfo: TeleporterFeeInfo({feeTokenAddress: address(0), amount: 0}),
                requiredGasLimit: 100000,
                allowedRelayerAddresses: new address[](0),
                message: encodeConcatenateData(text1, text2) // [!code highlight]
            })
        );
    }

    // Encode helpers
    function encodeAddData(uint256 a, uint256 b) public pure returns (bytes memory) {
        bytes memory paramsData = abi.encode(a, b); // [!code highlight:2]
        return abi.encode(CalculatorAction.add, paramsData);
    }

    function encodeConcatenateData(string memory a, string memory b) public pure returns (bytes memory) {
        bytes memory paramsData = abi.encode(a, b); // [!code highlight:2]
        return abi.encode(CalculatorAction.concatenate, paramsData);
    }
}
```

As you can see here we are calling `abi.encode` twice in the encode helpers. The first time we encode the function parameters and the second time we encode the function name with the byte array containing parameters.

## Decode the Function Name and Parameters

Let's now look at the receiver:

```solidity title="contracts/interchain-messaging/invoking-functions/CalculatorReceiverOnDispatch.sol"
pragma solidity ^0.8.18;

import "@teleporter/ITeleporterMessenger.sol";
import "@teleporter/ITeleporterReceiver.sol";
import "./CalculatorActions.sol";

contract CalculatorReceiverOnDispatch is ITeleporterReceiver {
    ITeleporterMessenger public immutable teleporterMessenger =
        ITeleporterMessenger(0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf);
    uint256 public result_num;
    string public result_string;

    function receiveTeleporterMessage(bytes32, address, bytes calldata message) external {
        // Only the Interchain Messaging receiver can deliver a message.
        require(
            msg.sender == address(teleporterMessenger), "CalculatorReceiverOnDispatch: unauthorized TeleporterMessenger"
        );

        // Decoding the Action type: // [!code highlight:2]
        (CalculatorAction actionType, bytes memory paramsData) = abi.decode(message, (CalculatorAction, bytes)); 

        // Route to the appropriate function. // [!code highlight:10]
        if (actionType == CalculatorAction.add) {
            (uint256 a, uint256 b) = abi.decode(paramsData, (uint256, uint256));
            _calculatorAdd(a, b);
        } else if (actionType == ...) {
            (string memory text1, string memory text2) = abi.decode(paramsData, (string, string));
            _calculatorConcatenateStrings(text1, text2);
        } else {
            revert("CalculatorReceiverOnDispatch: invalid action");
        }
    }

    function _calculatorAdd(uint256 _num1, uint256 _num2) internal {
        result_num = _num1 + _num2;

    }

    function _calculatorConcatenateStrings(string memory str1, string memory str2) internal {
        bytes memory str1Bytes = bytes(str1);
        bytes memory str2Bytes = bytes(str2);

        bytes memory combined = new bytes(str1Bytes.length + str2Bytes.length + 1);

        for (uint256 i = 0; i < str1Bytes.length; i++) {
            combined[i] = str1Bytes[i];
        }
        combined[str1Bytes.length] = " ";
        for (uint256 i = 0; i < str2Bytes.length; i++) {
            combined[str1Bytes.length + i + 1] = str2Bytes[i];
        }

        result_string = string(combined);
    }
}
```

You can see that we first decode the `CalculatorAction` enum:

```solidity
// Decoding the Action type: 
(CalculatorAction actionType, bytes memory paramsData) = abi.decode(message, (CalculatorAction, bytes)); 
```

Then based on the function name we decide how to unpack the parameters

```solidity
// Route to the appropriate function. 
if (actionType == CalculatorAction.add) {
    (uint256 a, uint256 b) = abi.decode(paramsData, (uint256, uint256)); // [!code highlight]
    _calculatorAdd(a, b);
} else if (actionType == ...) {
    (string memory text1, string memory text2) = abi.decode(paramsData, (string, string)); // [!code highlight]
    _calculatorConcatenateStrings(text1, text2);
} else {
    revert("CalculatorReceiverOnDispatch: invalid action");
}
```

For the `add` function we decode two numbers and for the `concatenate` function we decode two strings. After the decoding we call the appropriate internal function.

## Try it Out

Deploy the sender and receiver contracts and try out the `add` and `concatenate` functions. 

<Steps>
<Step>

### Deploy the Sender Contract

```bash
forge create --rpc-url fuji-c --private-key $PK contracts/interchain-messaging/invoking-functions/CalculatorSenderOnCChain.sol:CalculatorSenderOnCChain --broadcast
```
```
[⠃] Compiling...
[⠆] Compiling 2 files with Solc 0.8.18
[⠰] Solc 0.8.18 finished in 240.23ms
Compiler run successful!
Deployer: 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC // [$FUNDED_ADDRESS]
Deployed to: 0x8B3BC4270BE2abbB25BC04717830bd1Cc493a461 // [$SENDER_ADDRESS]
Transaction hash: 0xf9cce28a714764bb265bba7522bfd10d620fa0cb0f5dae26de2ac773b0a878ee
```

</Step>
<Step>

### Save the Sender Address:

```bash
export SENDER_ADDRESS={your-sender-address}
```

</Step>
<Step>

### Deploy the Receiver Contract:

```bash
forge create --rpc-url fuji-dispatch --private-key $PK contracts/interchain-messaging/invoking-functions/CalculatorReceiverOnDispatch.sol:CalculatorReceiverOnDispatch --broadcast
```
```
[⠊] Compiling...
[⠢] Compiling 1 files with Solc 0.8.18
[⠆] Solc 0.8.18 finished in 148.40ms
Compiler run successful!
Deployer: 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC // [$FUNDED_ADDRESS]
Deployed to: 0x5DB9A7629912EBF95876228C24A848de0bfB43A9 // [$RECEIVER_ADDRESS]
Transaction hash: 0xa8efb88abfef486d2caba30cb4146b1dc56a0ee88c7fb4c46adccdf1414ae39e
```
</Step>
<Step>

### Save the Receiver address:

```bash
export RECEIVER_ADDRESS={your-receiver-address}
```

</Step>
<Step>

### Call the Functions

Now you can call the `sendAddMessage` and `sendConcatenateMessage` functions on the sender contract and see the results on the receiver contract. 

```bash
cast send --rpc-url fuji-c --private-key $PK $SENDER_ADDRESS "sendAddMessage(address, uint, uint)" $RECEIVER_ADDRESS 1 2
```

</Step>
<Step>

### Verify the Result:

```bash
cast call --rpc-url fuji-dispatch $RECEIVER_ADDRESS "result_num()(uint)"
```

</Step>
</Steps>

<Quiz quizId="307"/>


# Extend the Calculator (/academy/interchain-messaging/06-invoking-functions/07-extend-calculator)

---
title: Extend the Calculator
description: Assignment- Extend calculator functionality
updated: 2024-05-31
authors: [martineckardt]
icon: Terminal
---

Now let's add a third feature to the calculator: adding three numbers. We want you to practice handling different amounts of parameters depending on the action to perform, so your task will be to add a `tripleSum` function that sums up three values of the type uint. 

You will need to:

- Add the `trippleSum` action to the enum file
- Add a new encode helper and send function to the sender contract
- Add a new route to the receiver and implement the `tripleSum` function

Check out the solution under `contracts/interchain-messaging/invoking-functions` in the Avalanche-Starter-Kit on the **interchain-messaging** branch.


# Interchain Messaging Registry (/academy/interchain-messaging/07-icm-registry/01-icm-registry)

---
title: Interchain Messaging Registry
description: Learn about the Interchain Messaging Registry to manage multiple Interchain Messaging versions.
updated: 2024-05-31
authors: [martineckardt]
icon: Book
---

When sending a message from the source chain we are calling the Interchain Messaging contract:

<img src="/common-images/teleporter/teleporter-source.png" width="400" class="mx-auto"/>

The TeleporterMessenger contract is non-upgradable. Once a version of the contract is deployed it cannot be changed. This is with the intention of preventing any changes to the deployed contract that could potentially introduce bugs or vulnerabilities. However, there could still be new versions of TeleporterMessenger contracts needed to be deployed in the future.

So far we used a fixed address for the TeleporterMessenger in all of our contracts. It is hardcoded in our contract. This is not a good practice, as it makes the contract less flexible and harder to upgrade.

```solidity
contract SenderOnCChain {

    ITeleporterMessenger public immutable teleporterMessenger = ITeleporterMessenger(0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf); // [!code highlight]

    function sendMessage(
        address destinationAddress,
        string calldata message
    ) external {
        teleporterMessenger.sendCrossChainMessage(
            // ...
        );
    }
}
```

While we could manually update the address of the used TeleporterMessenger in our contract, TeleporterRegistry provides us an easy way to use the latest version of TeleporterMessenger.

## What you will learn

In this section, you will explore the following topics:

- How the Interchain Messaging Registry works
- How to retrieve the latest version of the TeleporterMessenger on a blockchain


# How the ICM Registry works (/academy/interchain-messaging/07-icm-registry/02-how-the-icm-registry-works)

---
title: How the ICM Registry works
description: Learn about the different functionality available in the Interchain Messaging Registry.
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

TeleporterRegistry keeps track of TeleporterMessenger contract versions. Cross-Avalanche L1 dApps can request the latest or a specific version of the TeleporterMessenger:

<img src="/common-images/teleporter/teleporter-registry.png" width="600" class="mx-auto"/>

Internally the TeleporterRegistry maintains a mapping of TeleporterMessenger contract versions to their addresses.

<img src="/common-images/teleporter/teleporter-registry-class-diagram.png" width="400" class="mx-auto"/>

Each registry's mapping of version to contract address is independent of registries on other blockchains, and chains can decide on their own registry mapping entries. So the contract of version 4 on one chain does not have to be equal to that version on another chain.

```solidity title="/lib/icm-contracts/contracts/teleporter/registry/TeleporterRegistry.sol"

contract TeleporterRegistry {
    // .... 
  
    // The latest protocol version. 0 means no protocol version has been added, and isn't a valid version.
    uint256 public latestVersion;

    // Mappings that keep track of the protocol version and corresponding contract address.
    mapping(uint256 version => address protocolAddress) private _versionToAddress;
    mapping(address protocolAddress => uint256 version) private _addressToVersion;
  
   // ...
}
```
In the `TeleporterRegistry` contract, the `latestVersion` state variable returns the highest version number that has been registered in the registry. The `getLatestTeleporter` function returns the `ITeleporterMessenger` that is registered with the corresponding version. Version zero is an invalid version, and is used to indicate that a `TeleporterMessenger` contract has not been registered yet.

```solidity title="/lib/icm-contracts/contracts/teleporter/registry/TeleporterRegistry.sol"
contract TeleporterRegistry {
    // .... 
  
  	// Mappings that keep track of the protocol version and corresponding contract address.
    mapping(uint256 version => address protocolAddress) private _versionToAddress;
  
    // The latest protocol version. 0 means no protocol version has been added, and isn't a valid version.
    uint256 public latestVersion;

    function getLatestTeleporter() external view returns (ITeleporterMessenger) {
        return ITeleporterMessenger(getAddressFromVersion(latestVersion));
    }

    function getAddressFromVersion(uint256 version) public view returns (address) {
        require(version != 0, "TeleporterRegistry: zero version");
        address protocolAddress = _versionToAddress[version];
        require(protocolAddress != address(0), "TeleporterRegistry: version not found");
        return protocolAddress;
    }
  
    // ...
}
```

If a cross-Avalanche L1 dApps prefers a specific version, it can also call directly the `getAddressFromVersion` function:

```solidity title="/lib/icm-contracts/contracts/teleporter/registry/TeleporterRegistry.sol"
contract TeleporterRegistry {
  	// Mappings that keep track of the protocol version and corresponding contract address.
    mapping(uint256 version => address protocolAddress) private _versionToAddress;
  
    // .... 
  
    function getAddressFromVersion(uint256 version) public view returns (address) {
        require(version != 0, "TeleporterRegistry: zero version");
        address protocolAddress = _versionToAddress[version];
        require(protocolAddress != address(0), "TeleporterRegistry: version not found");
        return protocolAddress;
    }
  
    // ...
}
```

If you are interested in the entire implementation, check it out [here](https://github.com/ava-labs/teleporter/blob/main/contracts/teleporter/registry/TeleporterRegistry.sol).

<Quiz quizId="308"/>

# Interact with the ICM Registry (/academy/interchain-messaging/07-icm-registry/03-interact-with-the-registry)

---
title: Interact with the ICM Registry
description: Retrieve latest Interchain Messaging version using the Registry.
updated: 2024-05-31
authors: [martineckardt]
icon: Terminal
---

The ICM Registry is already deployed on Fuji C-Chain, Dispatch, and Echo networks. You can use it to keep track of the latest ICM messenger version and its address.

### Retrieve Latest ICM Messenger Version

Let's interact with the Registry by getting the latest version of the Interchain Messaging Messenger deployed on Fuji C-Chain:

```bash
cast call --rpc-url fuji-c $TELEPORTER_REGISTRY_FUJI_C_CHAIN "latestVersion()(uint256)" 
```

The response should be something like this:

```bash
1
```

# Retrieving Interchain Messenger from the Registry (/academy/interchain-messaging/07-icm-registry/04-retrieving-icm-from-registry)

---
title: Retrieving Interchain Messenger from the Registry
description: Use Registry in a Cross-Chain dApp.
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

Let's now integrate the registry into a smart contract. Let's go back to the very simple string sending contract from the beginning:

```solidity title="contracts/interchain-messaging/registry/SenderOnCChainWithRegistry.sol"
pragma solidity ^0.8.18;

import "@teleporter/upgrades/TeleporterRegistry.sol"; // [!code highlight]
import "@teleporter/ITeleporterMessenger.sol";

contract SenderOnCChain {
    // The Interchain Messaging registry contract manages different Interchain Messaging contract versions. // [!code highlight:3]
    TeleporterRegistry public immutable teleporterRegistry = TeleporterRegistry(0xF86Cb19Ad8405AEFa7d09C778215D2Cb6eBfB228);

    /**
     * @dev Sends a message to another chain.
     */
    function sendMessage(address destinationAddress, string calldata message) external {
        ITeleporterMessenger messenger = teleporterRegistry.getLatestTeleporter();  // [!code highlight]

        messenger.sendCrossChainMessage(
            TeleporterMessageInput({
                // BlockchainID of Dispatch L1
                destinationBlockchainID: 0x9f3be606497285d0ffbb5ac9ba24aa60346a9b1812479ed66cb329f394a4b1c7,
                destinationAddress: destinationAddress,
                feeInfo: TeleporterFeeInfo({feeTokenAddress: address(0), amount: 0}),
                requiredGasLimit: 100000,
                allowedRelayerAddresses: new address[](0),
                message: abi.encode(message)
            })
        );
    }
}
```

The key things to understand:

- We are importing the `ITeleporterRegistry.sol` interface
- We have a variable for the registry address instead of the messenger address
- Before sending the message we get the latest version from the registry


# Verify if Sender is Interchain Messaging (/academy/interchain-messaging/07-icm-registry/05-verify-sender-is-icm)

---
title: Verify if Sender is Interchain Messaging
description: Safety verification of the message sender
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

We can also leverage the registry to check if `msg.sender` is a registered Interchain Messaging contract. Previously, we hardcoded this check in the contract:

```solidity
import "@teleporter/ITeleporterMessenger.sol";
import "@teleporter/ITeleporterReceiver.sol";

contract ReceiverOnDispatch is ITeleporterReceiver {
    ITeleporterMessenger public immutable messenger = ITeleporterMessenger(0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf);

    string public lastMessage;

    function receiveTeleporterMessage(bytes32, address, bytes calldata message) external {
        // Only the Interchain Messaging receiver can deliver a message. // [!code highlight:2]
        require(msg.sender == address(messenger), "ReceiverOnDispatch: unauthorized TeleporterMessenger");

        // Store the message.
        lastMessage = abi.decode(message, (string));
    }
}
```

If there was now a new Interchain Messaging contract version that would be used for sending messages, we would have to update the contract.

Instead, we can use the registry to check if the sender is a registered Interchain Messaging contract. 

```solidity
pragma solidity ^0.8.18;

import "@teleporter/upgrades/TeleporterRegistry.sol";
import "@teleporter/ITeleporterMessenger.sol";
import "@teleporter/ITeleporterReceiver.sol";

contract ReceiverOnDispatchWithRegistry is ITeleporterReceiver {
    // The Interchain Messaging registry contract manages different Interchain Messaging contract versions.
    TeleporterRegistry public immutable teleporterRegistry = // [!code highlight:2]
        TeleporterRegistry(0xF86Cb19Ad8405AEFa7d09C778215D2Cb6eBfB228); 

    string public lastMessage;

    function receiveTeleporterMessage(bytes32, address, bytes calldata message) external {
        // Only a Interchain Messaging Messenger registered in the registry can deliver a message. // [!code highlight:3]
        // Function throws an error if msg.sender is not registered.
        teleporterRegistry.getVersionFromAddress(msg.sender);

        // Store the message.
        lastMessage = abi.decode(message, (string));
    }
}

# Avalanche Warp Messaging (/academy/interchain-messaging/08-avalanche-warp-messaging/01-avalanche-warp-messaging)

---
title: Avalanche Warp Messaging
description: Learn about Avalanche Warp Messaging, the Cross-Chain communication primitives on Avalanche.
updated: 2024-05-31
authors: [martineckardt]
icon: Book
---

<YouTube id="95KB-JhQS2Y" />

Avalanche Warp Messaging (AWM) was developed to make all Avalanche blockchains natively interoperable. Ideally, this solution would introduce as few trust assumptions as possible, meaning the blockchains would not depend on a third-party or intermediary that could risk centralization or single-point failures. 

AWM allows Avalanche L1s to communicate with one another via authenticated messages by providing signing and verification primitives in AvalancheGo. These are used by the blockchain VMs to sign outgoing messages and verify incoming messages. Any Virtual Machine (VM) on Avalanche can integrate AWM to send and receive messages across Avalanche L1s. 

Therefore, AWM is not EVM specific, but rather a general cross-Avalanche L1 communication protocol.

## What you will learn

In this section, you will go through the following topics:

- **P-Chain:** What is the role of the P-Chain in Avalanche Warp Messaging?
- **Warp Message Format:** What does a Warp message consist of?
- **Warp Message Signing:** How does AWM utilize the multi-signature scheme BLS to create aggregated signatures?
- **Warp Message Signature Verification:** How are the signatures of warp messages verified?
- **Trust Assumptions:** What trust assumptions does AWM introduce?

# Recap P-Chain (/academy/interchain-messaging/08-avalanche-warp-messaging/02-p-chain)

---
title: Recap P-Chain
description: Recap about the P-Chain main functionality of handling validator operations.
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

import PChain from "@/content/common/primary-network/p-chain.mdx";

<PChain />

<Quiz quizId="311"/>


# Warp Message Format (/academy/interchain-messaging/08-avalanche-warp-messaging/03-warp-message-format)

---
title: Warp Message Format
description: Learn about the structure of a Warp Message.
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

Warp Messages have a minimal message format that only contains the absolute necessary data for the transportation:

- **NetworkID:** The ID of the Network (Mainnet, Fuji Test Network, Local Test Network). This is included as a security mechanisms, so messages from the Fuji Test Network cannot be replayed on the Mainnet.
- **SourceChainID:** The chainID where the message originates from. This is not the EVM chain ID you may know from adding a network to a wallet, but the blockchain ID on the P-Chain. The P-Chain uses the transaction ID of the transaction that created those blockchain on the P-Chain for the chain ID, e.g.: 0xd7cdc6f08b167595d1577e24838113a88b1005b471a6c430d79c48b4c89cfc53
- **SourceAddress:** The address of the message sender
- **Payload:** The payload of the message

Every Warp message can be uniquely identified by its ID: the SHA256 hash of the serialized message (NetworkID, SourceChainID, SourceAddress & Payload).

The fields above are actually an UnsignedMessage. Hence, it has not been attached an aggregated signature yet. We will examine this in the following sections. 


# AWM Relayer (/academy/interchain-messaging/08-avalanche-warp-messaging/04-awm-relayer)

---
title: AWM Relayer
description: Learn the basic AWM role and configuration.
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

The AWM Relayer is an application run independently of the blockchain clients. Anyone can run their own AWM Relayer to create a communication channel between two Avalanche L1s, and there can be multiple relayers for the same communication channel. There is an open source implementation anyone can use [here](https://github.com/ava-labs/awm-relayer). 

[AvaCloud](https://www.avacloud.io) also offers their own hosted relayers.

![AWM Relayer data flow](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/teleporter/teleporter-source-destination-with-relayer-SvUFYGP77XxLjoyWqf7IpC85Ssxmmo.png)

The AWM Relayers are responsible for picking up the messages at the source Avalanche L1, aggregating the BLS signatures from a sufficiently large share of the source Avalanche L1's validators and submitting a transaction on the destination Avalanche L1.

It is up to the cross-chain application to decide if they allow any relayer to be part of the delivery process, or whether to restrict participation to certain Relayers.

## AWM Relayer Config

The AWM Relayer can be configured so that it is reusable for different networks (Mainnet, Fuji Testnet, Local) and communication channels between Avalanche L1s. The following configurations are available:

```json title="https://github.com/ava-labs/awm-relayer/blob/main/sample-relayer-config.json"
{
  "info-api": {
    "base-url": "https://api.avax-test.network"
  },
  "p-chain-api": {
    "base-url": "https://api.avax-test.network"
  },
  "source-blockchains": [
    {
      "subnet-id": "11111111111111111111111111111111LpoYY",
      "blockchain-id": "yH8D7ThNJkxmtkuv2jgBa4P1Rn3Qpr4pPr7QYNfcdoS6k6HWp",
      "vm": "evm",
      "rpc-endpoint": {
        "base-url": "https://api.avax-test.network/ext/bc/C/rpc"
      },
      "ws-endpoint": {
        "base-url": "wss://api.avax-test.network/ext/bc/C/ws"
      },
      "message-contracts": {
        "0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf": {
          "message-format": "teleporter",
          "settings": {
            "reward-address": "0x5072..."
          }
        }
      }
    }
  ],
  "destination-blockchains": [
    {
      "subnet-id": "7WtoAMPhrmh5KosDUsFL9yTcvw7YSxiKHPpdfs4JsgW47oZT5",
      "blockchain-id": "2D8RG4UpSXbPbvPCAWppNJyqTG2i2CAXSkTgmTBBvs7GKNZjsY",
      "vm": "evm",
      "rpc-endpoint": {
        "base-url": "https://subnets.avax.network/dispatch/testnet/rpc"
      },
      "account-private-key": "0x7493..."
    }
  ]
}
```

- **Info API URL:** An RPC endpoint where the AWM Relayer can access the Info API to retrieve the information about the network
- **P-Chain API URL:** An RPC endpoint where the AWM Relayer can access the P-Chain to retrieve the validators of the source Avalanche L1
- **Source Avalanche L1 Configs:** An array of configurations for the source Avalanche L1s where the messages are picked up from
- **Destination Avalanche L1 Configs:** An array of configurations for the destination Avalanche L1s where the messages are delivered to

# Dataflow (/academy/interchain-messaging/08-avalanche-warp-messaging/05-dataflow)

---
title: Dataflow
description: Learn the complete flow of a Cross-Chain message.
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

Looking at the bigger picture, the data flow of an interchain message can be described as follows:

 
<Steps>
<Step>
 
### Message Initialization
Cross-Chain dApp initiating the message calls the Interchain Messaging Contract on the source Avalanche L1
 
</Step>
 
<Step>
 
### Warp Precompile
The Interchain Messaging contracts interacts with the AWM precompile of the EVM
 
</Step>

<Step>
 
### Message Relaying
An AWM Relayer relays the message to the destination Chain. It periodically checks the source Avalanche L1 for outgoing messages and delivers these by calling the Interchain Messaging contract on the destination Avalanche L1.
 
</Step>

<Step>
 
### Signature Verification
The Interchain Messaging contract on the destination chain interacts with AWM to verify the signature of the message and whether it has been signed by a sufficiently large stake share of the source Avalanche L1's validator set.
 
</Step>

<Step>
 
### Destination Contract Call
The Interchain Messaging contract then calls the destination dApp contract 

</Step>

<Step>
 
### Message Processing
The dApp decodes the message payload and processes it accordingly.

</Step>
</Steps>

As you noticed in the `Teleporter Basics` chapter most of the cross-chain communication has been abstracted away from the dApp developer. The only interfaces for them are:

- **Sending a message:** Simply calling the Interchain Messaging contract on the source chain
- **Receiving a message:** Being able to be called by the Interchain Messaging on the destination chain

To start, we will assume there is always an AWM Relayer to deliver our messages without any incentives. Let's dive deeper into the sending and receiving of messages in the next sections.

<Quiz quizId="312"/>

# Message Pickup (/academy/interchain-messaging/08-avalanche-warp-messaging/06-message-pickup)

---
title: Message Pickup
description: Learn about the role of the Relayer when picking up the message.
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

When the AWM Relayer detects a new message, it collects the signatures of that message from the validators of the source Avalanche L1. The validator uses the BLS private key corresponding to their  BLS public key (registered on the P-Chain) to create a signature for the unsigned warp message we've learned about earlier (in the Warp Message Format).

![](/common-images/awm/relayer-pickup.png)

The AWM Relayer does not necessarily need to collect the signature of all validators. It only needs to ensure that the validators of the collected signatures represent a sufficiently large share of the total stake of the Avalanche L1. It is up to the receiving Avalanche L1 to determine what the threshold is.

## New Outgoing Messages

How does a AWM Relayer learn about new messages? The AWM Relayer has two options to check for outgoing warp message on the source Avalanche L1:

- **Polling:** The AWM Relayer periodically checks the source chain for new outgoing messages. 
- **Notification:** The AWM Relayer is triggered whenever a new outgoing message is detected by a node. 

## AWM Relayer Source Avalanche L1 Configuration

For the source Avalanche L1s, the AWM Relayer offers the following configuration:

```json
"source-blockchains": [
    {
      "subnet-id": "11111111111111111111111111111111LpoYY",
      "blockchain-id": "yH8D7ThNJkxmtkuv2jgBa4P1Rn3Qpr4pPr7QYNfcdoS6k6HWp",
      "vm": "evm",
      "rpc-endpoint": {
        "base-url": "https://api.avax-test.network/ext/bc/C/rpc"
      },
      "ws-endpoint": {
        "base-url": "wss://api.avax-test.network/ext/bc/C/ws"
      },
      "message-contracts": {
        "0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf": {
          "message-format": "teleporter",
          "settings": {
            "reward-address": "0x5072..."
          }
        }
      }
    }
  ],
```

- **subnet-id:** The id of the source Avalanche L1
- **blockchain-id:** The chainId of the source Avalanche L1's blockchain that should be checked for outgoing messages
- **vm:** A string specifying the virtual machine of the source Avalanche L1's blockchain. Currently, only the evm is supported, but this field has been added in anticipation of communication between blockchains powered by different virtual machines in the future.
- **rpc-endpoint:** The host of a node that can be queried for outgoing messages 
- **ws-endpoint:** The websocket endpoint of a node that can be queried for outgoing messages 
- **message-contracts:** A map with the address of the Interchain Messaging contract as key and the following config parameters as values:
    - **message-format:** A string specifying the format. Currently, only the format "teleporter" exists, but this field has been added in anticipation of multiple formats in the future
    - **settings:** A dictionary with settings for this Interchain Messaging contract 
    - **reward-address:** The address rewards are paid out to

<Quiz quizId="313"/>

# Message Delivery (/academy/interchain-messaging/08-avalanche-warp-messaging/07-message-delivery)

---
title: Message Delivery
description: Learn about the role of the Relayer for delivering the message.
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

Next, the AWM Relayer delivers the message with the aggregated signature by simply submitting a transaction to the destination Avalanche L1. The transaction is propagated through the validator set of the destination blockchain just as any other regular transaction would be.

In order to submit the transaction, the AWM Relayer needs access to the private key of a wallet holding the gas token of the destination blockchain to sign the transaction.

![](/common-images/awm/relayer-delivery.png)

When the validators verify the transaction, they perform the following steps:

<Steps>
<Step>
 
### Query the P-Chain:
The verifying validators of the destination L1 each query the validator set of the source Avalanche L1 with its stake weights and BLS Public Keys.

</Step>
 
<Step>
 
### Verify Sufficient Stake Weight:
First, the verifying validators are checking if the combined stake weight of the validators that have signed the Warp message is large enough to accept the message (e.g. validators representing 50% of the total stake have signed the message). The required stake weight to accept a message from a source chain can be set arbitrarily by the destination chain. An Avalanche L1 may require 50% for chain A and 90% for chain B. If the stake weight of the validators of the aggregate signature is insufficient the message is rejected.

</Step>

<Step>
 
### Aggregate BLS Public Keys:
The verifying validators of the destination L1 aggregate the BLS Public Keys of the source L1 validators that signed the message. 

</Step>
 
<Step>
 
### Verify BLS Multi-Signature:
The aggregated signature (created by the AWM Relayer) is now being verified using the aggregated BLS Public Key (aggregated by the destination L1 validators). If the verification fails (e.g. the AWM Relayer modified the message), the message is rejected.

</Step>

<Step>
 
### Message Execution:
If the verification is successful, the message is executed. 

</Step>

</Steps>


## Why doesn't the AWM Relayer also aggregate the BLS Public Keys?

The BLS public key aggregation has to be done by every validator of the destination L1. Some may ask why we don't perform this action off-chain through the AWM Relayer and attach it to the message (similar to the BLS signature aggregation).

Even though this would make the verification much faster, there is a security issue here. How can we be sure that the aggregated public key actually represents the public keys of the signing validators? How do we know that the AWM Relayer did not just create a bunch of public keys and an aggregated signature of these?

The only way to verify that is to aggregate the public keys of the signing validators and compare it to the one sent by the AWM Relayer. Therefore, it is pointless to attach it to the message.

<Quiz quizId="314"/>


# Load Considerations (/academy/interchain-messaging/08-avalanche-warp-messaging/08-load-considerations)

---
title: Load Considerations
description: Learn which chains experience a load increase when sending a Cross-Chain message.
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

Let's take a moment and determine where AWM takes up load:

- **Source Avalanche L1**: Validators sign the message
- **Relayer**: Signature aggregation
- **Destination Avalanche L1**: Validators verify the message using the BLS Public Key registry on the P-Chain

There is no record of the network communication, the signatures, or the message itself on the P-Chain. It solely functions as a registry of the BLS public keys where the destination Avalanche L1 validators read from. Since they each already validate the primary network, they are already tracking the P-Chain.

Thus, sending messages from one Avalanche L1 to another does not put any load on the P-Chain or another part of the Primary Network. This is a crucial feature, as there is no bottleneck or dependencies between Avalanche L1s for cross-chain communication. 


# Trust Assumptions (/academy/interchain-messaging/08-avalanche-warp-messaging/09-trust-assumption-of-awm)

---
title: Trust Assumptions
description: Learn where the trust relays when using AWM.
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

Avalanche Warp Messaging uses a trick: The trusted third party is the validator set of the source L1. We are already trusting them, or else we wouldn't communicate with that L1. 

The only thing that needs to be ensured is that there is always an AWM Relayer doing the signature aggregation and delivery of the warp message. Since it will have to pay gas on the destination chain, the sender needs to make sure it has enough incentives to do so. Either those incentives come from the sender itself, or from the receiving L1 if it has an inherent interest to onboard users to its chain. You will learn how users can incentivize AWM Relayers with ERC20 tokens with Interchain Messaging in following chapters. 

Generally, if there were no relayer available, anyone could run a AWM Relayer and deliver their own messages.

# Relayer Introduction (/academy/interchain-messaging/09-running-a-relayer/01-relayer-introduction)

---
title: Relayer Introduction
description: Learn how to run and manage a AWM Relayer.
updated: 2024-05-31
authors: [martineckardt]
icon: Book
---

As you now know Interchain Messaging requires a running relayer to deliver the warp messages underlying it, so far we just assumed a relayer is running. However, in a production environment, you will either need to run a relayer yourself or have someone else run it for you.

![AWM Relayer data flow](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/teleporter/teleporter-source-destination-with-relayer-SvUFYGP77XxLjoyWqf7IpC85Ssxmmo.png)

In this section you will learn how to run a relayer for Avalanche Warp Messaging. As discussed in the section on AWM, the relayer is responsible for checking for outgoing warp messages on the source L1, aggregate the signatures and deliver it with a transaction on the destination L1.

This chapter utilizes the reference relayer implementation created by Ava Labs. In this case the relayer is a standalone application written in Go. There may be different implementations in the future that are adapted to special use cases. Anyone can build and run a relayer.

## What you will learn

In this section, you will learn how to:

- **Configure the Relayer:** Create and understand the relayer configuration file that defines which blockchains to monitor and how to interact with them
- **Set Up the Relayer Wallet:** Learn about the relayer's wallet requirements and how to fund it with testnet tokens
- **Run the Relayer:** Deploy and operate the ICM relayer using Docker
- **Monitor Message Delivery:** Track and verify cross-chain message delivery through relayer logs and blockchain transactions

# Configuration Breakdown (/academy/interchain-messaging/09-running-a-relayer/02-relayer-configuration)

---
title: Configuration Breakdown
description: Understand the Relayer Configuration  
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

A relayer is configured to relayer messages between certain source and destination L1s. Therefore, the configuration consists of three parts:
- **General Config:** Configuration independent of the source and destination L1s concerning the network as a whole
- **Source Blockchain Configs:** All parameters necessary for the relayer to pick up the messages 
- **Destination Blockchain Configs:** All parameters necessary to deliver the messages

Let's go through an example JSON understanding the different values you will configure with the Toolbox in the next section:

## General Config

The general config contains among others the following parameters:

```json
{
  "p-chain-api": {
    "base-url": "http://127.0.0.1:9650",
    "query-parameters": {},
    "http-headers": null
  },
  "info-api": {
    "base-url": "http://127.0.0.1:9650",
    "query-parameters": {},
    "http-headers": null
  	},  
   	// ...
}
```

- **info-api-url:** The URL of the [Info API](/docs/api-reference/info-api) node to which the relayer will connect to to receive information like the NetworkID.
- **p-chain-api-url:** The URL of the Avalanche [P-Chain API](/docs/api-reference/p-chain/api) node to which the relayer will connect to query the validator sets. 

## Source Blockchain Configs

Next is the configuration for our source blockchain. This is the configuration of the blockchain where messages will be initiated and picked up. The relayer will aggregate the signatures of the validators of that L1. 

```json
{
  // General Config ...

  "source-blockchains": [
	{
      "subnet-id": "11111111111111111111111111111111LpoYY",
      "blockchain-id": "epm5fG6Pn1Y5rBHdTe36aZYeLqpXugreyHLZB5dV81rVTs7Ku",
      "vm": "evm",
      "rpc-endpoint": {
        "base-url": "http://127.0.0.1:9650/ext/bc/epm5fG6Pn1Y5rBHdTe36aZYeLqpXugreyHLZB5dV81rVTs7Ku/rpc",
        "query-parameters": null,
        "http-headers": null
      },
      "ws-endpoint": {
        "base-url": "ws://127.0.0.1:9650/ext/bc/epm5fG6Pn1Y5rBHdTe36aZYeLqpXugreyHLZB5dV81rVTs7Ku/ws",
        "query-parameters": null,
        "http-headers": null
      },
      "message-contracts": {
        "0x0000000000000000000000000000000000000000": {
          "message-format": "off-chain-registry",
          "settings": {
            "teleporter-registry-address": "0x17aB05351fC94a1a67Bf3f56DdbB941aE6c63E25"
          }
        },
        "0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf": {
          "message-format": "teleporter",
          "settings": {
            "reward-address": "0xbAE6Ff34d6Da45128C1ddFEDA008e55A328f5665"
          }
        }
      }
    }
  ]

  // Destination Blockchains
}
```

- **subnet-id:** The Blockchain ID of the L1 that the source blockchain is part of. In this example this is the Blockchain ID of the Primary Network.
- **blockchain-id:** The blockchain ID of the source. In this example this is the blockchain ID of Fuji's C-Chain.
- **vm:** A string specifying the virtual machine of the destination L1's blockchain. Currently, only the EVM is supported, but this field has been added in anticipation of communication between blockchains powered by different virtual machines in the future.
- **rpc-endpoint:** An API Config containing:
<div class="pl-6">
- **base-url:** RPC endpoint of the source L1's API node.
- **query-parameters:** Additional query parameters to include in the API requests
- **http-headers:** Additional HTTP headers to include in the API requests
</div>
- **wss-endpoint:** An API Config containing:
<div class="pl-6">
- **base-url**: The WebSocket endpoint of the source L1's API node
- **query-parameters:** Additional query parameters to include in the API requests
- **http-headers:** Additional HTTP headers to include in the API requests
</div>
- **message-contracts:** A map of contract addresses to the config options of the protocol (e.g. Teleporter) at that address. Each MessageProtocolConfig consists of a unique message-format name, and the raw JSON settings. "0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf" is the address of the TeleporterMessenger on the Fuji C-Chain.
<div class="pl-6">
- **message-format:** should be set to Teleporter. Additional message formats next to Interchain Messaging may be developed in the future 
- **settings > reward-address:** The address that will be rewarded if an L1 is incentivizing relayers to send messages on it's behalf. This is the address of the wallet you will create for this relayer. 
</div>

## Destination Blockchains

Next is the configuration for our destination blockchain. This is the configuration of the blockchain where messages will be sent to. The relayer will aggregate the signatures of the validators of that L1. 
```json
{
  "destination-blockchains": [
    {
      "subnet-id": "11111111111111111111111111111111LpoYY",
      "blockchain-id": "epm5fG6Pn1Y5rBHdTe36aZYeLqpXugreyHLZB5dV81rVTs7Ku",
      "vm": "evm",
      "rpc-endpoint": {
        "base-url": "http://127.0.0.1:9650/ext/bc/epm5fG6Pn1Y5rBHdTe36aZYeLqpXugreyHLZB5dV81rVTs7Ku/rpc",
        "query-parameters": null,
        "http-headers": null
      },
      "kms-key-id": "",
      "kms-aws-region": "",
      "account-private-key": "6dc6ba26b9b17f82b7b44fc316857a35ff201613072d500231ce3f2ee235bc16"
    },
  ],
}
```

For each destination L1, the relayer has the following config parameter:

- **subnet-id:** The ID of the L1 that the destination blockchain is part of. 
- **blockchain-id:** The blockchain ID of the destination blockchain. This is the Blockchain ID of Fuji's Dispatch L1.
- **vm:** A string specifying the virtual machine of the destination L1's blockchain. Currently, only the EVM is supported, but this field has been added in anticipation of communication between blockchains powered by different virtual machines in the future.
- **rpc-endpoint:** The RPC endpoint of the destination L1's API node. Used in favor of api-node-host, api-node-port, and encrypt-connection when constructing the endpoint.
- **kms-key-id:** The ID of the KMS key to use for signing transactions on the destination blockchain. Only one of account-private-key or kms-key-id should be provided. If kms-key-id is provided, then kms-aws-region is required. Please note that the private key in KMS should be exclusive to the relayer. 
- **kms-aws-region:** The AWS region in which the KMS key is located. Required if kms-key-id is provided. 
- **account-private-key:** A private key for a wallet that holds gas tokens on the destination L1. This is required so the relayer can sign the transaction that delivers the warp message.

If you have been following all the course up to this point with the Avalanche-starter-kit and Avalanche-CLI will provide you with a relayer already funded to perform transactions between the local C-chain and your own chain

Some configuration fields have been omitted for the purpose of this exercise. If you are interested to read the extensive list of relayer configurations, you can visit the awm-relayer GitHub repository [here](https://github.com/ava-labs/awm-relayer/tree/main?tab=readme-ov-file#configuration).

## Two-Way Messaging

The relayer can be configured to support two-way messaging between multiple Layer 1 blockchains. This means you can use a single relayer instance to handle communication in both directions between your chains. The key points to remember are:

<Callout type="warn" title="The relayer needs sufficient funds on both chains to deliver messages in both directions" />

To enable two-way communication:
- Add both chains to the `source-blockchains` array to listen for messages on both sides
- Add both chains to the `destination-blockchains` array to deliver messages to both sides
- Ensure the relayer account has enough funds on both chains for transaction fees

The ICM Relayer component in the Toolbox automatically handles this configuration for you, making it easy to set up two-way messaging between your chains.


# Configure & Run Relayer (/academy/interchain-messaging/09-running-a-relayer/03-configure-and-run-relayer)

---
title: Configure & Run Relayer
description: Configure and run an ICM relayer using Toolbox
updated: 2024-05-31
authors: [martineckardt]
icon: Terminal
---

The ICM Relayer is responsible for delivering messages between chains. Using the Toolbox interface, you can easily configure and manage your relayer instance.

## Relayer Setup

The Toolbox interface provides a simple way to configure and setup your relayer. Follow these steps to run your relayer:

1. Select both **Dispatch and C-Chain** as source and destination networks
2. Fund the relayer address with enough native tokens on each chain
3. Copy and run the configuration command
4. Start the relayer using the provided Docker command on you **interchain-messaging codespaces terminal**

<Callout type="warn" title="Make sure you are in testnet mode before proceeding & you have sufficient balance to fund the relayer" />

<ToolboxMdxWrapper walletMode="l1">
    <ICMRelayer />
</ToolboxMdxWrapper>

In order to check if the relayer is running you can run this command:

```bash
docker logs -f relayer
```

And the output should look like this:

```bash
{"level":"info","timestamp":"2024-07-11T01:38:40.093Z","logger":"awm-relayer","caller":"main/main.go:94","msg":"Initializing awm-relayer"}
{"level":"info","timestamp":"2024-07-11T01:38:40.093Z","logger":"awm-relayer","caller":"main/main.go:99","msg":"Set config options."}
{"level":"info","timestamp":"2024-07-11T01:38:40.093Z","logger":"awm-relayer","caller":"main/main.go:102","msg":"Initializing destination clients"}
{"level":"info","timestamp":"2024-07-11T01:38:40.094Z","logger":"awm-relayer","caller":"evm/destination_client.go:105","msg":"Initialized destination client","blockchainID":"epm5fG6Pn1Y5rBHdTe36aZYeLqpXugreyHLZB5dV81rVTs7Ku","evmChainID":"43112","nonce":0}
{"level":"info","timestamp":"2024-07-11T01:38:40.096Z","logger":"awm-relayer","caller":"evm/destination_client.go:105","msg":"Initialized destination client","blockchainID":"dXobeMTZB89Fy6E987aaRBDz2j8mVparqRRfvvmQDsH8haNJJ","evmChainID":"123","nonce":0}
{"level":"info","timestamp":"2024-07-11T01:38:40.096Z","logger":"awm-relayer","caller":"main/main.go:121","msg":"Initializing app request network"}
{"level":"info","timestamp":"2024-07-11T01:38:41.757Z","logger":"awm-relayer","caller":"main/main.go:440","msg":"starting metrics server...","port":9091}
{"level":"info","timestamp":"2024-07-11T01:38:41.757Z","logger":"awm-relayer","caller":"main/main.go:373","msg":"Creating application relayers","originBlockchainID":"epm5fG6Pn1Y5rBHdTe36aZYeLqpXugreyHLZB5dV81rVTs7Ku"}
{"level":"info","timestamp":"2024-07-11T01:38:41.758Z","logger":"awm-relayer","caller":"main/main.go:373","msg":"Creating application relayers","originBlockchainID":"dXobeMTZB89Fy6E987aaRBDz2j8mVparqRRfvvmQDsH8haNJJ"}
{"level":"info","timestamp":"2024-07-11T01:38:41.758Z","logger":"awm-relayer","caller":"checkpoint/checkpoint.go:40","msg":"Creating checkpoint manager","relayerID":"0x96ba68805e937e7695ffb1c956dab0aff39ec5529fd037d8168eb6d5587866fe","startingHeight":4}
{"level":"info","timestamp":"2024-07-11T01:38:41.758Z","logger":"awm-relayer","caller":"checkpoint/checkpoint.go:40","msg":"Creating checkpoint manager","relayerID":"0xf8b2da5b262b41a2ee2d2b46e61e68c95ec7fb8f6b0abbe4101f75f8281b85aa","startingHeight":4}
{"level":"info","timestamp":"2024-07-11T01:38:41.758Z","logger":"awm-relayer","caller":"main/main.go:283","msg":"Created application relayers","blockchainID":"epm5fG6Pn1Y5rBHdTe36aZYeLqpXugreyHLZB5dV81rVTs7Ku"}
{"level":"info","timestamp":"2024-07-11T01:38:41.759Z","logger":"awm-relayer","caller":"relayer/listener.go:127","msg":"Creating relayer","subnetID":"11111111111111111111111111111111LpoYY","subnetIDHex":"0000000000000000000000000000000000000000000000000000000000000000","blockchainID":"epm5fG6Pn1Y5rBHdTe36aZYeLqpXugreyHLZB5dV81rVTs7Ku","blockchainIDHex":"55e1fcfdde01f9f6d4c16fa2ed89ce65a8669120a86f321eef121891cab61241"}
{"level":"info","timestamp":"2024-07-11T01:38:41.760Z","logger":"awm-relayer","caller":"checkpoint/checkpoint.go:40","msg":"Creating checkpoint manager","relayerID":"0xe73a74b50d44b1b216bf806bc7e230d5305e544d35d41c2313cda26766ccd8ec","startingHeight":4}
{"level":"info","timestamp":"2024-07-11T01:38:41.760Z","logger":"awm-relayer","caller":"checkpoint/checkpoint.go:40","msg":"Creating checkpoint manager","relayerID":"0x66f44659b15f9d819caf71978931df3d5d7925b5d800cc4ef8153f12151401f6","startingHeight":4}
{"level":"info","timestamp":"2024-07-11T01:38:41.760Z","logger":"awm-relayer","caller":"main/main.go:283","msg":"Created application relayers","blockchainID":"dXobeMTZB89Fy6E987aaRBDz2j8mVparqRRfvvmQDsH8haNJJ"}
{"level":"info","timestamp":"2024-07-11T01:38:41.772Z","logger":"awm-relayer","caller":"relayer/listener.go:127","msg":"Creating relayer","subnetID":"26eqgD4Kt1MvTKXC9BDjEwBAfhcBcHCKj2EXjR2UuFpSWoAHhw","subnetIDHex":"9087d2f383171f73819baa49c3be63a5a6e2b492114dfc3556e42eedd182050a","blockchainID":"dXobeMTZB89Fy6E987aaRBDz2j8mVparqRRfvvmQDsH8haNJJ","blockchainIDHex":"52f2c4d51ef13a5781babe42c1b916e98fc88fc72919b20527782c939c8be71d"}
{"level":"info","timestamp":"2024-07-11T01:38:41.782Z","logger":"awm-relayer","caller":"evm/subscriber.go:131","msg":"Successfully subscribed","blockchainID":"dXobeMTZB89Fy6E987aaRBDz2j8mVparqRRfvvmQDsH8haNJJ"}
{"level":"info","timestamp":"2024-07-11T01:38:41.782Z","logger":"awm-relayer","caller":"evm/subscriber.go:131","msg":"Successfully subscribed","blockchainID":"epm5fG6Pn1Y5rBHdTe36aZYeLqpXugreyHLZB5dV81rVTs7Ku"}
{"level":"info","timestamp":"2024-07-11T01:38:41.782Z","logger":"awm-relayer","caller":"relayer/listener.go:166","msg":"processed-missed-blocks set to false, starting processing from chain head","blockchainID":"dXobeMTZB89Fy6E987aaRBDz2j8mVparqRRfvvmQDsH8haNJJ"}
{"level":"info","timestamp":"2024-07-11T01:38:41.783Z","logger":"awm-relayer","caller":"main/main.go:335","msg":"Created listener","blockchainID":"dXobeMTZB89Fy6E987aaRBDz2j8mVparqRRfvvmQDsH8haNJJ"}
{"level":"info","timestamp":"2024-07-11T01:38:41.783Z","logger":"awm-relayer","caller":"main/main.go:348","msg":"Listener initialized. Listening for messages to relay.","originBlockchainID":"dXobeMTZB89Fy6E987aaRBDz2j8mVparqRRfvvmQDsH8haNJJ"}
{"level":"info","timestamp":"2024-07-11T01:38:41.782Z","logger":"awm-relayer","caller":"relayer/listener.go:166","msg":"processed-missed-blocks set to false, starting processing from chain head","blockchainID":"epm5fG6Pn1Y5rBHdTe36aZYeLqpXugreyHLZB5dV81rVTs7Ku"}
{"level":"info","timestamp":"2024-07-11T01:38:41.783Z","logger":"awm-relayer","caller":"main/main.go:335","msg":"Created listener","blockchainID":"epm5fG6Pn1Y5rBHdTe36aZYeLqpXugreyHLZB5dV81rVTs7Ku"}
{"level":"info","timestamp":"2024-07-11T01:38:41.783Z","logger":"awm-relayer","caller":"main/main.go:348","msg":"Listener initialized. Listening for messages to relay.","originBlockchainID":"epm5fG6Pn1Y5rBHdTe36aZYeLqpXugreyHLZB5dV81rVTs7Ku"}
{"level":"info","timestamp":"2024-07-11T01:43:59.040Z","logger":"awm-relayer","caller":"relayer/listener.go:406","msg":"Unpacked warp message","sourceBlockchainID":"epm5fG6Pn1Y5rBHdTe36aZYeLqpXugreyHLZB5dV81rVTs7Ku","originSenderAddress":"0x5DB9A7629912EBF95876228C24A848de0bfB43A9","destinationBlockchainID":"dXobeMTZB89Fy6E987aaRBDz2j8mVparqRRfvvmQDsH8haNJJ","destinationAddress":"0x52C84043CD9c865236f11d9Fc9F56aa003c1f922","warpMessageID":"2ZV5u7WPVozo386A3d8T5B81vAKvcSDdNsggpmHFvihy5Yut1S"}
{"level":"info","timestamp":"2024-07-11T01:43:59.052Z","logger":"awm-relayer","caller":"relayer/application_relayer.go:320","msg":"Fetching aggregate signature from the source chain validators via AppRequest"}
{"level":"info","timestamp":"2024-07-11T01:43:59.060Z","logger":"awm-relayer","caller":"relayer/application_relayer.go:461","msg":"Created signed message.","destinationBlockchainID":"dXobeMTZB89Fy6E987aaRBDz2j8mVparqRRfvvmQDsH8haNJJ"}
{"level":"info","timestamp":"2024-07-11T01:43:59.060Z","logger":"awm-relayer","caller":"teleporter/message_handler.go:187","msg":"Sending message to destination chain","destinationBlockchainID":"dXobeMTZB89Fy6E987aaRBDz2j8mVparqRRfvvmQDsH8haNJJ","warpMessageID":"2ZV5u7WPVozo386A3d8T5B81vAKvcSDdNsggpmHFvihy5Yut1S","teleporterMessageID":"Hqr8jHV4NjTf4sbCoGqNJEuntm8QoWnDXdivFNLizAzFxRxm3"}
{"level":"info","timestamp":"2024-07-11T01:43:59.063Z","logger":"awm-relayer","caller":"evm/destination_client.go:192","msg":"Sent transaction","txID":"0x291bc3a3784dd79871cf4f95ba8f3fb3519e25c73848ee27bc5ebd7e3fe178d5","nonce":0}
{"level":"info","timestamp":"2024-07-11T01:43:59.266Z","logger":"awm-relayer","caller":"teleporter/message_handler.go:250","msg":"Delivered message to destination chain","destinationBlockchainID":"dXobeMTZB89Fy6E987aaRBDz2j8mVparqRRfvvmQDsH8haNJJ","warpMessageID":"2ZV5u7WPVozo386A3d8T5B81vAKvcSDdNsggpmHFvihy5Yut1S","teleporterMessageID":"Hqr8jHV4NjTf4sbCoGqNJEuntm8QoWnDXdivFNLizAzFxRxm3","txHash":"0x291bc3a3784dd79871cf4f95ba8f3fb3519e25c73848ee27bc5ebd7e3fe178d5"}
{"level":"info","timestamp":"2024-07-11T01:43:59.266Z","logger":"awm-relayer","caller":"relayer/application_relayer.go:246","msg":"Finished relaying message to destination chain","destinationBlockchainID":"dXobeMTZB89Fy6E987aaRBDz2j8mVparqRRfvvmQDsH8haNJJ"}
```

# Restricting a Relayer (/academy/interchain-messaging/10-restricting-the-relayer/01-restricting-the-relayer)

---
title: Restricting a Relayer
description: Learn about the basics of Avalanche.
updated: 2024-05-31
authors: [martineckardt]
icon: Book
---

In this segment, we'll delve into the mechanisms of restricting relayers for transmitting messages across Avalanche L1s. While the security in AWM and Interchain Messaging doesn't rely at all on the Relayer, there might be some reasons why you would want to restrict the delivery of the message to certain Relayers. 

The more obvious one is when you run your own Relayer, and don't want to incentivize any other to ensure your message gets to the destination. On following sections you will learn how to run your own Relayer so you can restrict the messages to your own.

## What You Will Learn

In this section, you will go through the following topics:

- **Allowed Relayers:** Learn how to restrict the relayer for transmitting messages across Avalanche L1s
- **Dynamically update the allowed Relayers:** Understand how to update the allowed relayers dynamically

# Allowed Relayer (/academy/interchain-messaging/10-restricting-the-relayer/02-allowed-relayers)

---
title: Allowed Relayer
description: Learn about the basics of Avalanche.
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

In this segment, we'll delve into the mechanisms of restricting relayers for transmitting messages across Avalanche L1s. While the security in AWM and Interchain Messaging doesn't rely at all on the Relayer, there might be some reasons why you would want to restrict the delivery of the message to certain Relayers. 

The more obvious one is when you run your own Relayer, and don't want to incentivize any other to ensure your message gets to the destination. On following sections you will learn how to run your own Relayer so you can restrict the messages to your own.

Let's look at the `TeleporterMessageInput` structure included when we call the `sendCrossChainMessage` one more time.

```solidity
struct TeleporterMessageInput {
    bytes32 destinationBlockchainID;
    address destinationAddress;
    TeleporterFeeInfo feeInfo;
    uint256 requiredGasLimit;
    address[] allowedRelayerAddresses;
    bytes message;
}

interface ITeleporterMessenger {
    function sendCrossChainMessage(TeleporterMessageInput calldata messageInput)
        external
        returns (bytes32);
}
```

As you can see the `TeleporterMessageInput` allows you to specify an array of addresses for the allowed relayers. Previously we have set that to an empty array, which means that any relayer can pick up the message.

```solidity
messenger.sendCrossChainMessage( 
    TeleporterMessageInput({
        // BlockchainID of Dispatch L1
        destinationBlockchainID: 0x9f3be606497285d0ffbb5ac9ba24aa60346a9b1812479ed66cb329f394a4b1c7,
        destinationAddress: destinationAddress, 
        feeInfo: TeleporterFeeInfo({feeTokenAddress: address(0), amount: 0}),
        requiredGasLimit: 100000,
        allowedRelayerAddresses: new address[](0), // [!code highlight]
        message: abi.encode(message)
    })
);
```

If you want to restrict the message to a certain relayer, you can simply add the address of the relayer to the array. A Relayer will be identified by the reward address it is associating each time it delivers a message.

```solidity
messenger.sendCrossChainMessage( 
    TeleporterMessageInput({
        // BlockchainID of Dispatch L1
        destinationBlockchainID: 0x9f3be606497285d0ffbb5ac9ba24aa60346a9b1812479ed66cb329f394a4b1c7,
        destinationAddress: destinationAddress, 
        feeInfo: TeleporterFeeInfo({feeTokenAddress: address(0), amount: 0}),
        requiredGasLimit: 100000,
        allowedRelayerAddresses: [0x321f6B73b6dFdE5C73731C39Fd9C89c7788D5EBc], // [!code highlight]
        message: abi.encode(message)
    })
);
```

# Incentivizing a Relayer (/academy/interchain-messaging/11-incentivizing-a-relayer/01-incentivizing-a-relayer)

---
title: Incentivizing a Relayer
description: Learn how to add Relayer Incentives.
updated: 2024-06-09
authors: [andyvargtz]
icon: Book
---

You already mastered how to send messages from one chain to another, but we have been working under the assumption that all messages will be picked by the Relayers. That is not always true, and external Relayers might want to have something in exchange for their services.

Relayer fees are an optional way to incentivize relayers to deliver a Interchain Messaging message to its destination chain. They are not strictly necessary, and may be omitted if a relayer is willing to relay messages with no fee, such as with a self-hosted relayer. If the relayer is not self hosted though, user will need to incentivize them, since they need to pay the transaction fees on the destination chain

## What you will learn

- What is the data flow for fees
- How to calculate an adecuate incentive amount
- How to implement those incentives

## Exercises

In this section you will apply the learned knowledge by calculating and adding fees to our basic send-receive contracts used in the [Interchain Messaging Basics chapter](/academy/interchain-messaging/04-icm-basics/01-icm-basics).

# Fee Data Flow (/academy/interchain-messaging/11-incentivizing-a-relayer/02-fee-data-flow)

---
title: Fee Data Flow
description: Learn the logic behind the fee incentivization.
updated: 2024-06-09
authors: [andyvargtz]
icon: BookOpen
---

The basic idea of incentivizing an external AWM Relayer to relay our message is to deposit an amount of an ERC-20 token into the Interchain Messaging contract as a reward for whichever relayer delivers our message.

Let's see how the fees are transferred from the user at the very beginning of sending a Cross Chain message, up to the point where the relayer is able to claim the fee.
![AWM Relayer with fees data flow](/common-images/teleporter/teleporter-fees-receipt.png)


We are using the following emoji guide to show the actors of each action:


**👩 User**

**📜 Cross-Chain dApp**

**👾 TeleporterMessenger**

**🛸 Relayer**

### Previous to Sending the Message:

- 👩 The message sender (user) requires to approve the Cross-Avalanche L1 dApp as a spender on the ERC20 contract to be used as fee.

### Sending the Message:

- 👩 User sends a message.
- 📜 Fee funds (previously approved) are transferred from the user's wallet to the Cross-Chain dApp.
- 📜 Cross-Chain dApp approves the Interchain Messaging Contract to spend the ERC20 fee tokens.
- 👾 Fee tokens are transferred into the Interchain Messaging Contract.
- 👾 Interchain Messaging assigns a unique ID to the Message and keeps track of the fee Info.
- 🛸 Relayer can now pick and deliver the Message.

### Message Delivered in the Destination Chain:

- 👾 Interchain Messaging in the Destination Chain generates a receipt with the `messageID` and Relayer address who delivered the message.
- Receipt is sent back to the Source Chain.
- 🛸 Relayers can send the receipts back to the Source Chain themselves or wait until a new (unrelated) message is sent now from the once Destination Chain to the former Source chain. Messages include up to 5 pending receipts in a message.

### Once Message is Received in the Source Chain:

- 👾 The Interchain Messaging marks the `messageID` as received and increases the Relayer redeemable reward.
- 🛸 The relayer can now claim its unlocked rewards.

As you can see, there are just a few actions you as a cross-chain dApp developer need to implement so dApp works smoothly with fees, everything else is being done by the Interchain Messaging contract and the Relayer.

If you run your own relayer, you don't have to attach any fees.

<Quiz quizId="315"/>

# Determining the Fee (/academy/interchain-messaging/11-incentivizing-a-relayer/03-determining-the-fee-amount)

---
title: Determining the Fee
description: Calculate a fair incentive amount.
updated: 2024-06-09
authors: [andyvargtz]
icon: BookOpen
---

## Economic Considerations for Relayers

### Determining Relayer Incentives

The first question to address is: How much should you pay a Relayer to ensure they are incentivized to deliver the message? The answer is straightforward but requires some analysis. The incentive should at least cover the expenses the Relayer will incur by delivering your message.

As mentioned in previous lessons, a message will be considered delivered in the destination Chain if the Relayer sends at least the `requiredGasLimit` stated in the message, regardless of whether the execution succeeds or fails. Thus, the associated cost in $USD (or another asset like AVAX) that the Relayer will face to deliver your message is:  

*Cost = requiredGasLimit * gas_price_in_native_token * native_token_price*

While the income the Relayer will be paid for delivering your message is:  

*Income = Fee_Amount * ERC20_Price*

Excluding the Relayer's hosting costs, any Fee amount where *Costs < Income* will be profitable for the Relayer. Different types of messages or actions available in a cross-chain dApp may require different amounts of gas to deliver successfully. For instance, in a cross-chain ERC20 minter, creating the token contract is more expensive than minting new tokens, simply because creation requires deploying a new contract. Thus, it makes sense to reward the Relayer with a higher amount for delivering a creation message compared to a minting message (assuming both `requiredGasLimit` are set accordingly).

### Example Calculation

Let's calculate the minimum fee that could incentivize a Relayer to pick and deliver a message.

To simplify, consider the following assumptions:
- We are sending a message from C-Chain to Dispatch.
- ERC20 incentives will be paid in TLP.
- DIS is the fee token in Bulletin.
- Assume *DIS_price = TLP_price*.
- Relayer will only take your message if it can make at least 10% profit.
- The `requiredGasLimit` for sending our message is 10,000 gas units.
- Gas price in Dispatch = 50 nDIS (DIS * 10^-9).

### Calculating the Fee

The cost of relaying this message will be:  

*Cost = 10,000 * 50 * DIS_price*

The Relayer will take your message only if it can make a 10% profit:  

*Income = 1.1 * Cost*

Therefore:  

*TLP_price * Amount = 1.1 * 10,000 * 50 * DIS_price*

Knowing that *TLP_price = DIS_price*:  

*Amount = 1.1 * 10,000 * 50*

Then:  

*Amount = 550,000 nTLP*  
*Amount = 550,000,000,000,000 weiTLP*

All amounts in Solidity need to be declared in wei, so use a unit converter to convert from nTLP to wei (10^-18).

<Quiz quizId="316"/>

# Setting Incentives (/academy/interchain-messaging/11-incentivizing-a-relayer/04-setting-incentives)

---
title: Setting Incentives
description: Learn where incentives details need to be included
updated: 2024-06-09
authors: [andyvargtz]
icon: BookOpen
---

As we studied in previous lessons, the `sendCrossChainMessage` function takes `TeleporterMessageInput` struct as an input. The fields feeInfo in the `TeleporterMessageInput` will be a `TeleporterFeeInfo` struct formed by the ERC20 contract address in which the fee will be paid, as well as the amount of tokens to incentivize the relayer. This amount needs to be set in wei units. 

Let's take a look at it:

```solidity
// (c) 2023, Ava Labs, Inc. All rights reserved.
// See the file LICENSE for licensing terms.

// SPDX-License-Identifier: Ecosystem

pragma solidity 0.8.18;

struct TeleporterMessageInput {
    bytes32 destinationBlockchainID;
    address destinationAddress;
    TeleporterFeeInfo feeInfo; // [!code highlight]
    uint256 requiredGasLimit; 
    address[] allowedRelayerAddresses;
    bytes message;
}

struct TeleporterFeeInfo {
    address contractAddress; // [!code highlight]
    uint256 amount; // [!code highlight]
}

interface ITeleporterMessenger {
    function sendCrossChainMessage(TeleporterMessageInput calldata messageInput)
        external
    returns (bytes32);
}
```
As you can see, the `TeleporterMessageInput` now needs to include the ERC20 address that will pay the incentives and the amount, all this as part of the `TeleporterFeeInfo`




# Deploy Fee Token Contract (/academy/interchain-messaging/11-incentivizing-a-relayer/05-deploy-fee-token-contract)

---
title: Deploy Fee Token Contract
description: Deploy an ERC20 to work as the Fee Token for incentives.
updated: 2024-06-09
authors: [andyvargtz]
icon: Terminal
---

To add incentives for relayers, we need an ERC20 token on the source chain (Fuji C-Chain). We'll deploy a simple ERC20 token that will be used to pay relayers for delivering our cross-chain messages.

<ToolboxMdxWrapper chain="fuji-c">
  <DeployExampleERC20 />
</ToolboxMdxWrapper>

<Steps>
<Step>

### Save the Token Address

After deploying the token through the interface above, save the token address to use it in the next steps:

```bash
export FEE_TOKEN_ADDRESS=<your-deployed-token-address>
```

Replace `<your-deployed-token-address>` with the address shown in the interface after deployment.

</Step>
<Step>

### Verify Your Token Balance

You can check that you received the initial supply:

```bash
cast call --rpc-url fuji-c \
  $FEE_TOKEN_ADDRESS \
  "balanceOf(address)(uint256)" \
  $FUNDED_ADDRESS
```

The balance should show 1,000,000 * 10^18 tokens (1,000,000 tokens with 18 decimals).

</Step>
</Steps>

These tokens will be used in the next sections to incentivize relayers to deliver your cross-chain messages.


# Incentivize an AWM relayer (/academy/interchain-messaging/11-incentivizing-a-relayer/06-incentivize-an-awm-relayer)

---
title: Incentivize an AWM relayer
description: Add incentives to the basic send-receive contracts.
updated: 2024-06-09
authors: [andyvargtz]
icon: Terminal
---

## Add Incentives to our Sender Contract

Now that we have an ERC20 token deployed and some of those tokens in our account to incentivize our relayer, let's include the incentive in our Sender contract.

```solidity title="contracts/interchain-messaging/incentivize-relayer/senderWithFees.sol"
// (c) 2023, Ava Labs, Inc. All rights reserved.
// See the file LICENSE for licensing terms.

// SPDX-License-Identifier: Ecosystem

pragma solidity ^0.8.18;

import "@teleporter/ITeleporterMessenger.sol";
import {IERC20} from "@openzeppelin/contracts@4/token/ERC20/IERC20.sol";

contract SenderWithFeesOnCChain {
    ITeleporterMessenger public immutable messenger = ITeleporterMessenger(0x253b2784c75e510dD0fF1da844684a1aC0aa5fcf);
    /**
     * @dev Sends a message to another chain.
     */
    function sendMessage(address destinationAddress, string calldata message, address feeAddress) external {
        IERC20 feeContract = IERC20(feeAddress);
        uint256 feeAmount = 500000000000000;
        feeContract.transferFrom(msg.sender, address(this), feeAmount);
        feeContract.approve(address(messenger), feeAmount);

        messenger.sendCrossChainMessage(
            TeleporterMessageInput({
                // BlockchainID of Dispatch L1
                destinationBlockchainID: 0x9f3be606497285d0ffbb5ac9ba24aa60346a9b1812479ed66cb329f394a4b1c7,
                destinationAddress: destinationAddress,
                feeInfo: TeleporterFeeInfo({feeTokenAddress: feeAddress, amount: feeAmount}),
                requiredGasLimit: 100000,
                allowedRelayerAddresses: new address[](0),
                message: abi.encode(message)
            })
        );
    }
}
```

Notice, our contract implementing Fees now needs to include the functionality we described in the fee flow section:

- Import `IERC20` and create the fee contract interface instance 
- 📜The Cross-Avalanche L1 dApp transfers the ERC20 fee amount to the control of the Cross-Chain dApp contract.
- 📜Cross-Avalanche L1 dApp needs to implement the approval for the Interchain Messaging contract of these ERC20 tokens.
- Include the `TeleporterFeeInfo` struct in the message. 



# Interaction Flow With Fees (/academy/interchain-messaging/11-incentivizing-a-relayer/07-interaction-flow-with-fees)

---
title: Interaction Flow With Fees
description: Go trhough the complete deployment flow and send an incentivized message.
updated: 2024-06-09
authors: [andyvargtz]
icon: Terminal
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

Now we have all the Smart Contract 📜 set we can start sending incentivized cross-chain messages. Now let complete the flow 

- Deploy sender contract on **C-Chain**
- Deploy receiver contract on **Dispatch**
- Approve the sender contract to spend ERC20 funds from the message sender address
- Send the message

<Steps>
<Step>

### Deploy Sender Contract 

To deploy the sender contract run:

```bash
forge create --rpc-url fuji-c --private-key $PK contracts/interchain-messaging/incentivize-relayer/senderWithFees.sol:SenderWithFeesOnCChain --broadcast
```

```bash {6}
[⠊] Compiling...
[⠒] Compiling 2 files with Solc 0.8.18
[⠢] Solc 0.8.18 finished in 92.98ms
Compiler run successful!
Deployer: 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC
Deployed to: 0xa4DfF80B4a1D748BF28BC4A271eD834689Ea3407
Transaction hash: 0xb0ff20527818fcc0836944a13ddb3b336b95047d434bb52f6c064ab407950166
```

</Step>
<Step>
### Save the Sender Contract Address

```bash
export SENDER_ADDRESS=0xa4DfF80B4a1D748BF28BC4A271eD834689Ea3407
```

</Step>
<Step>

### Deploy Receiver Contract

Now, deploy the receiver contract.

```bash
forge create --rpc-url fuji-dispatch --private-key $PK contracts/interchain-messaging/incentivize-relayer/receiverWithFees.sol:ReceiverOnDispatch --broadcast
```

```bash {6}
[⠊] Compiling...
[⠢] Compiling 1 files with Solc 0.8.18
[⠆] Solc 0.8.18 finished in 105.36ms
Compiler run successful!
Deployer: 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC
Deployed to: 0xe336d36FacA76840407e6836d26119E1EcE0A2b4
Transaction hash: 0x379f0a4b875effc9b80a33f039d9a49404514e7aabaef4490f57b56fb4818f65
```

</Step>
<Step>

### Save the Receiver Contract Address

```bash
export RECEIVER_ADDRESS=0xe336d36FacA76840407e6836d26119E1EcE0A2b4
```

</Step>
<Step>

### Approve ERC20 Token Expense

👩 The Message Sender (User) requires to approve the Cross-Avalanche L1 dApp as a spender on the ERC20 contract to be used as fee. We'll approve 0.0005 tokens (500000000000000 wei) from your total supply of 1,000,000 tokens which matches the fee amount set in the sender contract.

```bash
cast send --rpc-url fuji-c --private-key $PK $FEE_TOKEN_ADDRESS "approve(address,uint256)" $SENDER_ADDRESS 500000000000000
```

</Step>
<Step>

### Send an incentivized message

```bash
cast send --rpc-url fuji-c --private-key $PK $SENDER_ADDRESS "sendMessage(address, string, address)" $RECEIVER_ADDRESS "Hello" $FEE_TOKEN_ADDRESS
```

</Step>
<Step>

### Verify message was received on Avalanche L1 

```bash
cast call --rpc-url fuji-dispatch $RECEIVER_ADDRESS "lastMessage()(string)"
```
```bash
"Hello"
```

**Success!** The message was received on the destination chain while incentivizing the Relayer.

</Step>
</Steps>


# Introduction (/academy/interchain-messaging/13-access-chainlink-vrf-services/01-introduction)

---
title: Introduction
description: Learn how to use ICM to access Chainlink VRF services on L1 networks that do not have direct Chainlink support.
updated: 2024-10-21
authors: [0xstt]
icon: Book
---

As decentralized applications (dApps) expand across multiple blockchains, some Layer 1 (L1) networks lack direct support from essential services like **Chainlink VRF (Verifiable Random Functions)**. This presents a significant challenge for developers who rely on verifiable randomness for use cases such as gaming, lotteries, NFT minting, and other decentralized functions that require unbiased, unpredictable random numbers.

The challenge arises because not every L1 network has integrated with Chainlink, meaning developers on those chains are left without native access to VRF services. Without verifiable randomness, critical aspects of dApps, such as fairness and security, can be compromised.

### Why ICM is Necessary

To address this gap, **Interchain Messaging (ICM)** provides a solution by allowing L1 networks that don’t have direct Chainlink support to still access these services. Through ICM, any blockchain can request VRF outputs from a Chainlink-supported network (e.g., Fuji) and receive the results securely on their own L1. 

This cross-chain solution unlocks the ability to use Chainlink VRF on unsupported networks, bypassing the need for native integration and ensuring that dApp developers can continue building secure and fair decentralized applications.

In the following sections, we will explore how to use ICM to access Chainlink VRF services across different chains by deploying two key smart contracts: one on the Chainlink-supported network and another on the target L1.

# Understanding the Flow (/academy/interchain-messaging/13-access-chainlink-vrf-services/02-understanding-the-flow)

---
title: Understanding the Flow
description: Learn how requests for random words flow across chains using ICM.
updated: 2024-10-21
authors: [0xstt]
icon: BookOpen
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

This section explains how random words are requested and fulfilled using Chainlink VRF across two different blockchains through **Interchain Messaging (ICM)**. The entire process involves several key components: the decentralized application (DApp), `CrossChainVRFConsumer`, `CrossChainVRFWrapper`, and `TeleporterMessenger`.

Let’s walk through the flow step by step:

<Steps>
<Step>

### DApp Submits Request for Random Words

The DApp, running on an L1 without direct Chainlink support, initiates a request for verifiable randomness by interacting with the `CrossChainVRFConsumer` contract deployed on its chain.

</Step>
<Step>

### `CrossChainVRFConsumer` Sends Cross-Chain Message

Once the DApp submits the request, the `CrossChainVRFConsumer` prepares a message containing the necessary VRF request parameters (such as `keyHash`, `request confirmations`, `gas limit`, etc.). This message is sent across chains via the `TeleporterMessenger` to the `CrossChainVRFWrapper` on the Chainlink-supported network (e.g., Fuji).

</Step>
<Step>

### `TeleporterMessenger` Receives Message & Calls `CrossChainVRFWrapper`
1. On the Chainlink-supported network, the `TeleporterMessenger` receives the cross-chain message sent by the `CrossChainVRFConsumer`. It passes the message to the `CrossChainVRFWrapper`, which is authorized to handle VRF requests.
2. The `CrossChainVRFWrapper` contract, deployed on the supported network, sends the request to **Chainlink VRF** for random words, using the parameters received in the message (e.g., `subscription ID`, `callback gas limit`, etc.).

</Step>

<Step>

### Chainlink VRF Fulfills Random Words Request

1. The **Chainlink VRF** fulfills the request and returns the random words to the `CrossChainVRFWrapper` contract by invoking its callback function.
2. Once the random words are received, the `CrossChainVRFWrapper` encodes the fulfilled random words and sends them back as a cross-chain message to the `CrossChainVRFConsumer` on the original L1.

</Step>

<Step>

### `TeleporterMessenger` Returns Random Words to `CrossChainVRFConsumer`
   
The `TeleporterMessenger` on the original L1 receives the message containing the random words and passes it to the `CrossChainVRFConsumer`.

</Step>

<Step>

### `CrossChainVRFConsumer` Returns Random Words to the DApp

Finally, the `CrossChainVRFConsumer` processes the random words and sends them to the DApp that originally requested them, completing the flow.

</Step>

</Steps>

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/interchain-messaging/cross-chain-vrf-NiG2EHgc4ulWBUx9Ekx0DZxTGdoHXk.png)

This end-to-end process demonstrates how decentralized applications on unsupported L1 networks can request verifiable randomness from Chainlink VRF, leveraging **ICM** to handle cross-chain communication.



# Orchestrating VRF Requests Over Multiple Chains (Wrapper) (/academy/interchain-messaging/13-access-chainlink-vrf-services/03-orchestrating-vrf-requests)

---
title: Orchestrating VRF Requests Over Multiple Chains (Wrapper)
description: Learn how the CrossChainVRFWrapper contract on a Chainlink-supported L1 handles cross-chain requests for VRF.
updated: 2024-10-21
authors: [0xstt]
icon: BookOpen
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

The `CrossChainVRFWrapper` contract plays a critical role in handling requests for randomness from an unsupported L1. It is deployed on a **Chainlink-supported network** (like Avalanche Fuji) and serves as the intermediary that interacts with Chainlink VRF to request random words.

Here’s how it functions as the provider for VRF services:

## Receives Cross-Chain Messages

<Steps>
<Step>

When the `CrossChainVRFConsumer` on the unsupported L1 initiates a request for randomness, it sends a cross-chain message via the `TeleporterMessenger` to the `CrossChainVRFWrapper` on the supported network.

</Step>
<Step>

The `CrossChainVRFWrapper` verifies that the request came from an authorized address. This is essential to ensure that only verified consumers can request randomness.

</Step>
<Step>

Upon receiving a valid request, the **VRFWrapper** calls **Chainlink VRF** and sends the request with the required parameters, such as the number of random words, request confirmations, and gas limits.

</Step>
<Step>

The `CrossChainVRFWrapper` keeps track of all pending requests using a mapping, associating each request ID with its destination (the L1 where the `CrossChainVRFConsumer` resides). This ensures that the random words are returned to the correct destination once fulfilled.

</Step>
</Steps>

<Accordions>
<Accordion title="Implementation">
```solidity
function receiveTeleporterMessage(
    bytes32 originChainID,
    address originSenderAddress,
    bytes calldata message
) external {
    require(msg.sender == address(teleporterMessenger), "Caller is not the TeleporterMessenger");
    // Verify that the origin sender address is authorized
    require(authorizedSubscriptions[originSenderAddress].isAuthorized, "Origin sender is not authorized");
    uint256 subscriptionId = authorizedSubscriptions[originSenderAddress].subscriptionId;
    // Verify that the subscription ID belongs to the correct owner
    (,,,, address[] memory consumers) = s_vrfCoordinator.getSubscription(subscriptionId);
    // Check wrapper contract is a consumer of the subscription
    bool isConsumer = false;
    for (uint256 i = 0; i < consumers.length; i++) {
        if (consumers[i] == address(this)) {
            isConsumer = true;
            break;
        }
    }
    require(isConsumer, "Contract is not a consumer of this subscription");
    // Decode message to get the VRF parameters
    CrossChainRequest memory vrfMessage = abi.decode(message, (CrossChainRequest));
    // Request random words
    VRFV2PlusClient.RandomWordsRequest memory req = VRFV2PlusClient.RandomWordsRequest({
        keyHash: vrfMessage.keyHash,
        subId: subscriptionId,
        requestConfirmations: vrfMessage.requestConfirmations,
        callbackGasLimit: vrfMessage.callbackGasLimit,
        numWords: vrfMessage.numWords,
        extraArgs: VRFV2PlusClient._argsToBytes(VRFV2PlusClient.ExtraArgsV1({nativePayment: vrfMessage.nativePayment}))
    });
    uint256 requestId = s_vrfCoordinator.requestRandomWords(req);
    pendingRequests[requestId] = CrossChainReceiver({
        destinationBlockchainId: originChainID,
        destinationAddress: originSenderAddress
    });
}   
```
</Accordion>
</Accordions>

## Handles Callback from Chainlink VRF

<Steps>
<Step>

When **Chainlink VRF** fulfills the randomness request, the `CrossChainVRFWrapper` receives the random words through a callback function. This ensures that the request has been successfully processed.

</Step>
<Step>

After receiving the random words, the `CrossChainVRFWrapper` encodes the result and sends it back as a cross-chain message to the `CrossChainVRFConsumer` on the unsupported L1. This is done using the `TeleporterMessenger`.

</Step>
</Steps>

<Accordions>
<Accordion title="Implementation">
```solidity
function fulfillRandomWords(uint256 requestId, uint256[] calldata randomWords) internal override {
    require(pendingRequests[requestId].destinationAddress != address(0), "Invalid request ID");
    // Create CrossChainResponse struct
    CrossChainResponse memory crossChainResponse = CrossChainResponse({
        requestId: requestId,
        randomWords: randomWords
    });
    bytes memory encodedMessage = abi.encode(crossChainResponse);
    // Send cross chain message using ITeleporterMessenger interface
    TeleporterMessageInput memory messageInput = TeleporterMessageInput({
        destinationBlockchainID: pendingRequests[requestId].destinationBlockchainId,
        destinationAddress: pendingRequests[requestId].destinationAddress,
        feeInfo: TeleporterFeeInfo({ feeTokenAddress: address(0), amount: 0 }),
        requiredGasLimit: 100000,
        allowedRelayerAddresses: new address[](0),
        message: encodedMessage
    });
    teleporterMessenger.sendCrossChainMessage(messageInput);
    delete pendingRequests[requestId];
}
```
</Accordion>
</Accordions>

In summary, the `CrossChainVRFWrapper` contract acts as the **bridge** between the unsupported L1 and Chainlink’s VRF services, ensuring that random words are requested, fulfilled, and delivered back across chains efficiently.


# Bringing Chainlink VRF to Unsupported L1s (Consumer) (/academy/interchain-messaging/13-access-chainlink-vrf-services/04-bring-vrf-to-unsupported-l1)

---
title: Bringing Chainlink VRF to Unsupported L1s (Consumer)
description: Learn how to request VRF from an unsupported L1 using CrossChainVRFConsumer.
updated: 2024-10-21
authors: [0xstt]
icon: BookOpen
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

The `CrossChainVRFConsumer` contract enables DApps on an unsupported L1 to request random words from Chainlink VRF using a cross-chain communication mechanism. Since Chainlink does not natively support all blockchains, this setup allows developers to access Chainlink's VRF service even on networks that don’t have direct support.

<Steps>
<Step>

## Requesting Random Words

The `CrossChainVRFConsumer` contract sends a cross-chain message to the `CrossChainVRFWrapper` on a Chainlink-supported L1, requesting random words. This request is sent using `TeleporterMessenger`, which handles cross-chain communication.

<Accordions>
<Accordion title="Implementation">
```solidity
function requestRandomWords(
    bytes32 keyHash,
    uint16 requestConfirmations,
    uint32 callbackGasLimit,
    uint32 numWords,
    bool nativePayment,
    uint32 requiredGasLimit
) external {
    // Create CrossChainRequest struct
    CrossChainRequest memory crossChainRequest = CrossChainRequest({
        keyHash: keyHash,
        requestConfirmations: requestConfirmations,
        callbackGasLimit: callbackGasLimit,
        numWords: numWords,
        nativePayment: nativePayment
    });
    // Send Teleporter message
    bytes memory encodedMessage = abi.encode(crossChainRequest);
    TeleporterMessageInput memory messageInput = TeleporterMessageInput({
        destinationBlockchainID: DATASOURCE_BLOCKCHAIN_ID, 
        destinationAddress: vrfRequesterContract,
        feeInfo: TeleporterFeeInfo({ feeTokenAddress: address(0), amount: 0 }),
        requiredGasLimit: requiredGasLimit,
        allowedRelayerAddresses: new address[](0),
        message: encodedMessage
    });
    teleporterMessenger.sendCrossChainMessage(messageInput);
}
```
</Accordion>
</Accordions>

</Step>

<Step>

## Processing the Request
Once the request is received by the `CrossChainVRFWrapper`, it interacts with the Chainlink VRF Coordinator to request the random words on behalf of the consumer on the unsupported L1.

</Step>

<Step>

## Receiving Random Words

Once Chainlink fulfills the request, the `CrossChainVRFWrapper` sends the random words back to the `CrossChainVRFConsumer` via a cross-chain message, enabling the DApp on the unsupported L1 to use them.

<Accordions>
<Accordion title="Implementation">
```solidity
function receiveTeleporterMessage(
    bytes32 originChainID,
    address originSenderAddress,
    bytes calldata message
) external {
    require(originChainID == DATASOURCE_BLOCKCHAIN_ID, "Invalid originChainID");
    require(msg.sender == address(teleporterMessenger), "Caller is not the TeleporterMessenger");
    require(originSenderAddress == vrfRequesterContract, "Invalid sender");
    
    // Decode the message to get the request ID and random words
    CrossChainResponse memory response = abi.decode(message, (CrossChainResponse));
    
    // Fulfill the request by calling the internal function
    fulfillRandomWords(response.requestId, response.randomWords);
}

function fulfillRandomWords(uint256 requestId, uint256[] memory randomWords) internal {
    // Logic to handle the fulfillment of random words
    // Implement your custom logic here

    // Emit event for received random words
    emit RandomWordsReceived(requestId);
}
```
</Accordion>
</Accordions>

</Step>
</Steps>


# Deploy Wrapper (/academy/interchain-messaging/13-access-chainlink-vrf-services/05-deploy-vrf-wrapper)

---
title: Deploy Wrapper
description: Learn how to deploy the CrossChainVRFWrapper contract to handle cross-chain VRF requests.
updated: 2024-10-21
authors: [0xstt]
icon: Terminal
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

Once you have set up your Chainlink VRF subscription and have your LINK tokens ready, the next step is to deploy the **CrossChainVRFWrapper** contract. This contract will act as the bridge between your unsupported L1 and the Chainlink VRF network on a supported L1, enabling cross-chain requests for random words.

<Steps>
<Step>

## Prerequisites
Before deployment, make sure you have:
- A valid **Chainlink VRF Subscription ID** (see previous section for details).
- The `TeleporterMessenger` contract address on your supported L1 (e.g., Avalanche Fuji).
</Step>
<Step>

## Deploy the Contract
Using the `forge create` command, deploy the `CrossChainVRFWrapper` contract to the supported L1 (e.g., Avalanche Fuji).

```bash
forge create --rpc-url <RPC_URL> --private-key <PRIVATE_KEY> --broadcast --constructor-args <TELEPORTER_MESSENGER_ADDRESS> src/CrossChainVRFWrapper.sol:CrossChainVRFWrapper
```

Replace the following:

- `<RPC_URL>`: The RPC URL for the L1.
- `<PRIVATE_KEY>`: The private key for the account used to deploy the contract.
- `<TELEPORTER_MESSENGER_ADDRESS>`: The address of the deployed `TeleporterMessenger` contract.

After deployment, save the `Deployed to` address in an environment variable for future use.

```bash
export VRF_WRAPPER=<address>
```

</Step>
<Step>

## Verify the Deployment
After deploying the contract, verify that the `CrossChainVRFWrapper` has been successfully deployed by checking its address on a block explorer.

</Step>
<Step>

## Configure Authorized Subscriptions
Once deployed, the `CrossChainVRFWrapper` contract needs to be configured with authorized subscriptions to process requests for random words.

- Call the `addAuthorizedAddress` function to authorize a specific address with a given subscription ID.
- This ensures that only authorized addresses can request random words via the wrapper.

```bash
cast send --rpc-url <RPC_URL> --private-key <PRIVATE_KEY> $VRF_WRAPPER "addAuthorizedAddress(address caller, uint256 subscriptionId)" <CALLER_ADDRESS> <SUBSCRIPTION_ID>
```

Replace the following:

- `<CALLER_ADDRESS>`: The address that will be authorized to request random words.
- `<SUBSCRIPTION_ID>`: The ID of your Chainlink VRF subscription.
</Step>
</Steps>

# Deploy Consumer (/academy/interchain-messaging/13-access-chainlink-vrf-services/06-deploy-vrf-consumer)

---
title: Deploy Consumer
description: Learn how to deploy the CrossChainVRFConsumer contract on any L1 that does not support Chainlink VRF.
updated: 2024-10-21
authors: [0xstt]
icon: Terminal
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

Now that the `CrossChainVRFWrapper` is deployed on a Chainlink-supported L1, it’s time to deploy the `CrossChainVRFConsumer` contract on the L1 where Chainlink VRF is not supported. This contract will handle requests for random words and interact with the **TeleporterMessenger** to communicate with the supported L1.

<Steps>
<Step>
## Prerequisites
Make sure you have:
- The `TeleporterMessenger` contract address on the unsupported L1.
- The deployed `CrossChainVRFWrapper` on the supported L1. `($VRF_WRAPPER)`
</Step>
<Step>
## Deploy the Contract
Use the following command to deploy the `CrossChainVRFConsumer` contract on your unsupported L1.

```bash
forge create --rpc-url <RPC_URL> --private-key <PRIVATE_KEY> --broadcast --constructor-args <TELEPORTER_MESSENGER_ADDRESS> $VRF_WRAPPER src/CrossChainVRFConsumer.sol:CrossChainVRFConsumer
```

Replace the following:

- `<RPC_URL>`: The RPC URL for the L1.
- `<PRIVATE_KEY>`: The private key for the account used to deploy the contract.
- `<TELEPORTER_MESSENGER_ADDRESS>`: The address of the `TeleporterMessenger` contract on your unsupported L1.

After deployment, save the `Deployed to` address in an environment variable for future use.

```bash
export VRF_CONSUMER=<address>
```
</Step>
<Step>
## Verify the Deployment
Once the `CrossChainVRFConsumer` contract is deployed, verify the contract’s address and confirm that it has been successfully deployed on your L1 using a block explorer.
</Step>
</Steps>

# Create Chainlink VRF Subscription (/academy/interchain-messaging/13-access-chainlink-vrf-services/07-create-vrf-subscription)

---
title: Create Chainlink VRF Subscription
description: Learn how to create a Chainlink VRF subscription to enable cross-chain randomness requests.
updated: 2024-10-21
authors: [0xstt]
icon: BookOpen
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

Before you can request random words using Chainlink VRF, you need to set up a **Chainlink VRF subscription**. This subscription allows you to fund requests for randomness and manage the list of consumers that are authorized to use the VRF service.

<Steps>
<Step>

## Access Chainlink's VRF Subscription Manager

To create a subscription, go to the Chainlink VRF Subscription Manager on the network where you plan to request VRF (e.g., Avalanche Fuji). You can access the manager here: [VRF | Subscription Management for Fuji](https://vrf.chain.link/fuji).
![](/common-images/chainlink-vrf/visit-subscription-management.png)

</Step>
<Step>

## Create a New Subscription

Once on the subscription manager, create a new subscription. The subscription will have a unique ID, which you'll need to reference in your `CrossChainVRFWrapper` contract. This ID is used to track your random word requests and the balance associated with them.
![](/common-images/chainlink-vrf/create-subscription.png)

</Step>
<Step>

## Fund the Subscription

After creating the subscription, you need to fund it with LINK tokens. These tokens are used to pay for the randomness requests made through Chainlink VRF. Make sure your subscription has enough funds to cover your requests.
You can get testnet LINK tokens from the Fuji Faucet: [Chainlink Faucet for Fuji](https://faucets.chain.link/fuji)

![](/common-images/chainlink-vrf/faucet.png)

![](/common-images/chainlink-vrf/add-funds.png)

</Step>
<Step>

## Add Consumers

After funding your subscription, add the `CrossChainVRFWrapper` contract `($VRF_WRAPPER)` as a consumer. This step authorizes the contract to make randomness requests on behalf of your subscription. You can add other consumers, such as other contracts or addresses, depending on your use case.
![](/common-images/chainlink-vrf/add-consumer.png)

</Step>
<Step>

## Save Subscription ID

After completing these steps, save your subscription ID. You will need this ID when configuring the `CrossChainVRFWrapper` contract to request random words.

```bash
export VRF_SUBSCRIPTION_ID=<subscription_id>
```

</Step>
</Steps>

---


# Request Random Words (/academy/interchain-messaging/13-access-chainlink-vrf-services/08-request-random-words)

---
title: Request Random Words
description: Learn how to request random words using CrossChainVRFConsumer.
updated: 2024-10-21
authors: [0xstt]
icon: Terminal
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

In this section, you will learn how to request random words from Chainlink VRF using both the `CrossChainVRFConsumer` contracts.

<Steps>
<Step>

## Authorize an Address to Request Random Words

After deploying the `CrossChainVRFWrapper` contract, the first step is to authorize an address to make requests for random words. This ensures that only specific addresses linked to a subscription can request VRF.

- Use the `addAuthorizedAddress` function to authorize a specific address with a given subscription ID. This step allows the address to make random word requests through the wrapper.

```bash
cast send --rpc-url <RPC_URL> --private-key <PRIVATE_KEY> $VRF_WRAPPER "addAuthorizedAddress(address caller, uint256 subscriptionId)" $VRF_CONSUMER $VRF_SUBSCRIPTION_ID
```

</Step>
<Step>

## Request Random Words from `CrossChainVRFConsumer`

Once the address is authorized, the next step is to send a request for random words from the `CrossChainVRFConsumer` contract on the unsupported L1. This request is then sent to the `CrossChainVRFWrapper` via a cross-chain message.

```bash
cast send --rpc-url <RPC_URL> --private-key <PRIVATE_KEY> $VRF_CONSUMER "requestRandomWords(bytes32 keyHash, uint16 requestConfirmations, uint32 callbackGasLimit, uint32 numWords, bool nativePayment, uint32 requiredGasLimit)" <KEY_HASH> <CONFIRMATIONS> <GAS_LIMIT> <NUM_WORDS> <NATIVE_PAYMENT> <REQUIRED_GAS_LIMIT>
```

Replace the placeholders with:

- `<KEY_HASH>`: The VRF key hash used for random word generation.
- `<CONFIRMATIONS>`: Number of confirmations required for the request.
- `<GAS_LIMIT>`: The gas limit for the VRF callback function.
- `<NUM_WORDS>`: The number of random words requested.
- `<NATIVE_PAYMENT>`: Indicates whether the payment will be made in the native token.
- `<REQUIRED_GAS_LIMIT>`: The gas limit required for the cross-chain message to be processed.

</Step>
</Steps>

# Introduction (/academy/l1-native-tokenomics/01-tokens-fundamentals/01-introduction)

---
title: Introduction
description: chapter outline and learning goals
updated: 2025-08-21
authors: [nicolasarnedo]
icon: Book
---

## What You Will Learn

This foundational section covers the essential concepts of blockchain tokens:

- **Token Fundamentals**: How tokens represent ownership and value
- **Token Design**: Technical parameters that shape token behavior
- **Native Tokens**: Primary blockchain currencies and their roles
- **ERC-20 Tokens**: Standardized smart contract tokens for DeFi
- **Practical Skills**: Deploy and transfer ERC-20 tokens

## Learning Goals

By the end of this section, you will understand:
- What native and ERC-20 tokens are and how they work
- How to design tokens with appropriate technical parameters
- How to deploy and transfer ERC-20 tokens

The next section will cover the key differences between native and ERC-20 tokens, including wrapped tokens.

Let's get started! 

# Token Design (/academy/l1-native-tokenomics/01-tokens-fundamentals/02-token-design)

---
title: Token Design
description: Technical parameters that shape how a token behaves on-chain.
updated: 2024-09-03
authors: [0xstt]
icon: BookOpen
---

Designing a token can also have technical approach: choices you make in the contract (or at the protocol level for native tokens) determine precision, issuance, transfer rules, permissions, gas usage, and composability. Below are the core levers to consider when specifying a token

### Decimals (Precision)

Defines the smallest unit and affects UX, pricing, rounding, and integrations.

- 6 decimals → smallest unit is 0.000001
- 18 decimals → smallest unit is 0.000000000000000001 (common on EVM)

Implementation detail: ERC‑20 exposes `decimals()`; native tokens inherit precision from the chain/protocol.

---

### Total Supply and Issuance Model

Specify whether supply is fixed at deployment or elastic over time.

- Fixed supply: immutable cap set in constructor/genesis
- Elastic supply: emissions/vesting/mint/burn mechanisms adjust supply
- Programmatic schedules vs role‑gated actions

---

### Minting and Burning Functions

Control how supply can change post‑deployment.

- `mint(address,toAmount)`: who can call (owner, `MINTER_ROLE`)? caps?
- `burn(amount)` / `burnFrom(address,amount)`: opt‑in user burn vs admin burn
- Event emissions (`Transfer` from/to zero address) for indexers

---

### Transfer Mechanics

Define how balances move and what hooks apply.

- Plain ERC‑20 `transfer/transferFrom`
- Fee/tax on transfer (discouraged for DeFi composability)
- Blacklist/whitelist or trading windows (be careful: centralization + DEX issues)
- Pausable transfers (circuit breakers via `Pausable`)

### Allowance and Approvals

Permissions for third‑party spenders.

- Standard `approve/allowance/transferFrom`
- EIP‑2612 Permit (gasless approvals via signatures)
- Race‑condition safe patterns (set to 0 then new amount)

---

### Access Control and Roles

Who can mint, pause, upgrade, or change parameters.

- `Ownable` vs `AccessControl` (role‑based: `MINTER_ROLE`, `PAUSER_ROLE`)
- Timelocks and multisig admins for safer governance changes

---


Choosing these parameters up front ensures your token remains secure, composable, and easy to integrate while matching the precision, control, and lifecycle you intend.

# Native Tokens (/academy/l1-native-tokenomics/01-tokens-fundamentals/03-native-tokens)

---
title: Native Tokens
description: Learn about native tokens and their role in blockchain ecosystems.
updated: 2024-09-03
authors: [0xstt]
icon: BookOpen
---

A **native token** in a blockchain running the Ethereum Virtual Machine (EVM) refers to the primary digital currency or cryptocurrency native to that blockchain. Native tokens act as the foundation for value transfer and network operation within their respective ecosystems.

- **Ethereum**: ETH
- **Avalanche C-Chain**: AVAX
- **Dexalot**: ALOT
- many more...

---

### The Role of Native Tokens

Native tokens serve multiple key roles within EVM-based blockchain networks, such as:

- **Value Transfer**: Native tokens act as the primary currency for peer-to-peer transactions within the network, enabling value exchange between participants.
- **Gas Fees**: Native tokens are used as **gas** to pay for transaction fees, contract deployments, and other network operations. This ensures that resources are allocated efficiently within the network.
- **Security**: In Proof-of-Stake (PoS) networks, native tokens are often used for staking to secure the network and validate transactions.
- **Governance**: In some cases, native tokens grant holders governance rights, allowing them to participate in decision-making processes that shape the blockchain’s future.
- **Configurability**: On Avalanche L1s, networks may designate different assets for gas and staking, separating user fee UX from validator economics.

---

Native tokens are the backbone of blockchain ecosystems, serving multiple roles that maintain the network's stability, security, and functionality.

# Transfer Native Tokens (/academy/l1-native-tokenomics/01-tokens-fundamentals/04-transfer-native-token)

---
title: Transfer Native Tokens
description: Learn how to transfer native tokens using Core Wallet
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

In this exercise, you will learn how to transfer native tokens (AVAX) between accounts using Core Wallet. We'll demonstrate this using the Fuji testnet.

<Steps>
<Step>

## Open Core Wallet

First, make sure you have Core Wallet installed. If you don't have Core Wallet installed already, click the Download Core Wallet button below.

<ToolboxMdxWrapper />

</Step>
<Step>

## Switch to Fuji Testnet

<ToolboxMdxWrapper enforceChainId={43113} />

</Step>
<Step>

## Get Test AVAX

Before transferring tokens, ensure you have some test AVAX:

**Option 1 (Recommended):** Create a [Builder Hub account](https://build.avax.network/login) and connect your wallet to receive testnet AVAX automatically on the C-Chain.

**Option 2:** Use the external [Avalanche Faucet](https://core.app/tools/testnet-faucet/?subnet=c&token=c) with coupon code `avalanche-academy25` to claim AVAX tokens on the C-Chain of the Fuji testnet.

</Step>
<Step>

## Transfer AVAX

To transfer AVAX to another address:

1. Click the "Send" button in Core Wallet
2. Enter the recipient's address
3. Enter the amount of AVAX to send
4. Review the transaction details
5. Click "Send" to confirm

</Step>
<Step>

## Verify the Transfer

To verify the transfer was successful:

1. Check the transaction status in Core Wallet
2. View the transaction details on the [Fuji Explorer](https://testnet.snowtrace.io)
3. The recipient can check their balance in their Core Wallet

</Step>
</Steps>

<Callout>
Remember that you need to have enough AVAX in your wallet to cover both the transfer amount and the gas fees. Always double-check the recipient address before sending to avoid any loss of funds.
</Callout>

Now that you know how to transfer native tokens, you can proceed to learn about transferring ERC-20 tokens in the next section.


# ERC-20 Tokens (/academy/l1-native-tokenomics/01-tokens-fundamentals/05-erc20)

---
title: ERC-20 Tokens
description: Learn about ERC-20 tokens and their role in blockchain ecosystems.
updated: 2024-09-03
authors: [0xstt]
icon: BookOpen
---

While a blockchain has a single **native token**, the **ERC-20** token standard was developed to allow for the representation of a wide range of assets on EVM-compatible chains. 

**ERC** stands for **Ethereum Request for Comment**, and **20** is the identifier for the specific proposal that defines the standard.

ERC-20 tokens are **fungible**, meaning each token is identical to another and can be exchanged on a one-to-one basis. These tokens are created and managed through smart contracts that adhere to the ERC-20 standard, ensuring interoperability between different tokens and decentralized applications (DApps).

---

### ERC-20 Token Architecture

At the core of every ERC-20 token is a simple **mapping** of addresses to balances, representing the number of tokens an address holds.

```solidity
abstract contract ERC20 is Context, IERC20, IERC20Metadata, IERC20Errors {
    
  mapping(address account => uint256) private _balances;
  
  //...
}
```

Addresses holding ERC-20 tokens can belong to either **Externally Owned Accounts (EOAs)** or **smart contracts**. Both types of accounts can store and transfer ERC-20 tokens, making ERC-20 tokens versatile in decentralized finance (DeFi) and decentralized applications.

---

### Role of ERC-20 Tokens in Blockchain Ecosystems

ERC-20 tokens play an essential role in enabling the creation of decentralized applications with various functionalities:

- **Tokenized Assets**: ERC-20 tokens can represent anything from digital currencies to tokenized real-world assets.
- **DeFi Protocols**: Many DeFi protocols use ERC-20 tokens for lending, staking, and liquidity pools.
- **Token Sales**: ICOs (Initial Coin Offerings) and other fundraising models rely heavily on ERC-20 tokens.

---

### The ERC-20 Interface

All ERC-20 tokens follow a standard interface to ensure compatibility with decentralized applications (DApps). This allows tokens to be easily transferred, approved for spending, and managed by any DApp that follows the same rules.

```solidity
interface IERC20 {
    function name() external view returns (string memory);

    function symbol() external view returns (string memory);

    function decimals() external view returns (uint8);

    function totalSupply() external view returns (uint256);

    function balanceOf(address _owner) external view returns (uint256 balance);

    function transfer(address _to, uint256 _value) external returns (bool success);

    function transferFrom(address _from, address _to, uint256 _value) external returns (bool success);

    function approve(address _spender, uint256 _value) external returns (bool success);

    function allowance(address _owner, address _spender) external view returns (uint256 remaining);
}
```

You can review the full **ERC-20 standard** [here](https://eips.ethereum.org/EIPS/eip-20).

---

### Transferring ERC-20 Tokens

To transfer ERC-20 tokens between accounts, you use the `transfer()` function, where the sender specifies the recipient’s address and the amount to be transferred.

For more complex interactions, such as allowing a smart contract to transfer tokens on behalf of someone else, the ERC-20 standard includes the `approve()` and `transferFrom()` functions. 


<Accordions>
<Accordion title="transfer()">
Transfers tokens from the sender’s account to another account, decreasing the sender's balance and increasing the recipient’s.
</Accordion>
<Accordion title="approve()">
This function allows the owner of a token balance to approve another account (the **spender**) to withdraw up to a specified amount of tokens. The spender can withdraw from the owner's balance multiple times, as long as the total amount doesn’t exceed the approved limit.
</Accordion>
<Accordion title="allowance()">
The `allowance()` function returns the amount that a spender is still allowed to withdraw from an owner's balance.
</Accordion>
<Accordion title="transferFrom()">
This function facilitates the transfer of tokens from one account to another on behalf of the account owner. It is typically used in scenarios where smart contracts need to execute token transfers according to the contract's logic.
</Accordion>
</Accordions>

---

ERC-20 tokens revolutionized the blockchain space by enabling the tokenization of assets and simplifying the creation of decentralized applications. Their standardization ensures compatibility across platforms and DApps, making them an integral part of the broader crypto ecosystem.

# Deploy an ERC-20 (/academy/l1-native-tokenomics/01-tokens-fundamentals/06-deploy-erc20)

---
title: Deploy an ERC-20
description: Transfer an ERC-20 token between accounts
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

<Steps>
<Step>

### Deploy ERC-20

Let's deploy a basic demo ERC20 token on the Fuji testnet using our toolbox.

<ToolboxMdxWrapper>
    <DeployExampleERC20 />
</ToolboxMdxWrapper>

</Step>
<Step>

### Add Token to Core Wallet

After deploying your ERC-20 token:

1. Open Core Wallet
2. Go to the Tokens tab
3. Click "Manage"
4. Click "+ Add Custom Token"
5. Enter the token contract address from the deployment
6. The token symbol and decimals should be automatically detected
7. Click "Add Token"

<Callout>
Make sure you're connected to the Fuji testnet when adding the token. The token will only be visible on the network where it was deployed.
</Callout>

</Step>
<Step>

### Transfer ERC-20 Token

To transfer your ERC-20 token:

1. In Core Wallet, select your token from the token list
2. Click "Send"
3. Enter the recipient's address
4. Enter the amount to transfer
5. Review the transaction details
6. Click "Send" to confirm

<Callout>
Always double-check the recipient address before sending. ERC-20 transfers cannot be reversed once confirmed.
</Callout>

</Step>
<Step>

### Verify Transfer

To verify the transfer was successful:

1. Check the transaction status in Core Wallet
2. View the transaction details on the [Fuji Explorer](https://testnet.snowtrace.io)
3. The recipient can add the token to their Core Wallet to see their balance

<Callout>
If the recipient doesn't see the token in their wallet, they'll need to add it using the token contract address, just like you did in step 2.
</Callout>

</Step>
</Steps>

Now that you know how to deploy and transfer ERC-20 tokens, you can proceed to learn about token bridging in the next section.

# Key Differences (/academy/l1-native-tokenomics/01b-native-vs-erc20/08-native-and-erc20-tokens)

---
title: Key Differences
description: Learn the key differences between native tokens and ERC20 tokens on Avalanche L1s
updated: 2025-01-15
authors: [nicolasarnedo]
icon: Book
---

Before moving forward, and now that we have seen both, it's crucial to understand the fundamental differences between native tokens and ERC20 tokens. Each has distinct characteristics that affect how they function within your blockchain ecosystem.

## Key Differences

| Feature | ERC20 | Native |
|---------|-------|--------|
| **Defined By** | Smart Contract Deployer | Protocol Level |
| **Balance Storage** | Mapping in contract storage<br/>`mapping(address => balance)` | EVM Account state<br/>`account.balance` |
| **Transfer Logic** | Handled by contract functions<br/>`transfer()`, `transferFrom()` | Handled by EVM opcodes<br/>`CALL`, `SELFDESTRUCT` |
| **Smart Contract Awareness** | Built-in hooks for DeFi compatibility<br/>Allows programmatic approvals<br/>(e.g., Uniswap, Aave) | Can't call functions<br/>`approve()`, `transferFrom()` |
| **Receiving in Functions** | No special modifier needed<br/>`function deposit(token, amount)` | Requires `payable` modifier<br/>`function deposit() payable` |

## The Protocol Limitation

One critical limitation of native tokens is that **protocols cannot "pull" native tokens from your wallet using `transferFrom()`**. This fundamental difference impacts how DeFi protocols interact with native tokens.

## Real-World Example: Aave Lending

Let's look at how supplying ETH (a native token) to Aave works:

1. **Wrap it into WETH** - Convert native ETH to ERC20 WETH
2. **Call `approve()`** - Give Aave permission to spend your WETH
3. **Aave calls `transferFrom()`** - Aave pulls the WETH from your wallet
4. **You receive aTokens** - Start earning interest and can borrow against your deposit

## Why ERC20 Standardization Matters

The main advantage of ERC20 tokens is **standardization**. Without it:
- You could build a `deposit()` payable function for native tokens
- But then you'd have two different logics for depositing tokens
- This creates complexity and potential security issues


# Wrapped Native Tokens (/academy/l1-native-tokenomics/01b-native-vs-erc20/09-wrapped-tokens)

---
title: Wrapped Native Tokens
description: Learn about wrapped tokens and their role in blockchain ecosystems.
updated: 2025-09-15
authors: [0xstt]
icon: BookOpen
---

Now that we understand the key differences between native tokens and ERC20s, we can explore **native token wrapping** - what it is and why it's necessary for blockchain ecosystems.

**Wrapped tokens** are blockchain assets that represent a native cryptocurrency (e.g., AVAX, ALOT, ETH) in a tokenized form, typically conforming to the **ERC-20 token standard**. Wrapping a native token allows it to be used in decentralized applications (dApps) and protocols that require ERC-20 tokens.

---

### What Are Wrapped Tokens?

Wrapped tokens are created through a process where the native cryptocurrency is locked in a smart contract, and an equivalent amount of the wrapped token is minted. These wrapped tokens are backed 1:1 by the underlying native asset, ensuring that the value of the wrapped token mirrors that of the original native cryptocurrency.

This **ERC-20 compatibility** is crucial for enabling the native asset to interact with dApps, decentralized exchanges (DEXs), and smart contracts within the EVM ecosystem, where ERC-20 tokens are the standard. As we learned in the previous section, this solves the fundamental limitation where protocols cannot "pull" native tokens using `transferFrom()`.

---

### Why Are Wrapped Tokens Important?

Wrapped tokens play an essential role in **interoperability** within the EVM ecosystem, facilitating seamless use across decentralized applications and protocols. They directly address the limitations we discussed about native tokens:

- **DeFi Integration**: Wrapped tokens enable native assets to participate in DeFi protocols that require ERC-20 tokens. Remember our Aave example? Native ETH needs to be wrapped to WETH before it can be supplied to lending protocols.
- **Protocol Compatibility**: They solve the `transferFrom()` limitation by allowing protocols to "pull" tokens from user wallets, which is impossible with native tokens.
- **Liquidity**: Wrapped tokens increase liquidity in DeFi by enabling users to participate in protocols that require ERC-20 tokens, even when their original asset is a native token.
- **Cross-Chain Compatibility**: Wrapped tokens allow assets from one blockchain (e.g., Bitcoin) to be used on another chain, enhancing cross-chain functionality.

---

### Wrapped Token Contract Interface

A **wrapped token contract** is typically an implementation of the ERC-20 token standard, with added functions for minting and burning tokens to facilitate the wrapping and unwrapping process. Here's a basic contract interface for a wrapped token:

```solidity
interface IWrappedToken {
    function deposit() external payable;
    function withdraw(uint256 amount) external;
    
    function totalSupply() external view returns (uint256);
    function balanceOf(address account) external view returns (uint256);
    function transfer(address recipient, uint256 amount) external returns (bool);
    function allowance(address owner, address spender) external view returns (uint256);
    function approve(address spender, uint256 amount) external returns (bool);
    function transferFrom(address sender, address recipient, uint256 amount) external returns (bool);
}
```

<Accordions>
<Accordion title="deposit()">
This function is used to wrap native tokens. When a user calls deposit(), they send the native cryptocurrency (e.g., AVAX, ETH) to the contract, which then mints an equivalent amount of the wrapped token.
</Accordion>
<Accordion title="withdraw()">
This function is used to unwrap the tokens. It burns the specified amount of wrapped tokens and returns the equivalent amount of native cryptocurrency to the user.
</Accordion>
</Accordions>

# Deploy a Wrapped Token (/academy/l1-native-tokenomics/01b-native-vs-erc20/10-deploy-wrapped-tokens)

---
title: Deploy a Wrapped Token
description: Learn how to deploy and interact with wrapped tokens
updated: 2024-09-03
authors: [0xstt]
icon: Terminal
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

In this section, we will deploy and interact with a wrapped token using the Dev Console.

---

<Steps>
<Step>

#### 1. Deploy Wrapped Native Token with the Dev Console
Use the Dev Console to easily deploy a wrapped native token without any setup or command line tools.

The Dev Console provides a simple interface to deploy wrapped native tokens directly from your browser. This eliminates the need to:
- Set up a local development environment
- Install and configure Foundry
- Manage private keys manually
- Write deployment scripts

You can deploy a wrapped native token in just a few clicks using the integrated deployment tool below.

</Step>
<Step>

### Deploy Your Wrapped Native Token

Use the integrated Dev Console below to deploy your wrapped native token:

<ToolboxMdxWrapper>
  <DeployWrappedNative />
</ToolboxMdxWrapper>

</Step>

<Step>

### Note Your Wrapped Token Address

After deployment, the Dev Console will display your wrapped token address. You can copy this address for use in other tools and interactions. The address will be automatically saved in the Dev Console session for easy reference across different tools.

</Step>

<Step>

### Interacting with Your Wrapped Token

Once deployed, you can interact with your wrapped native token using various methods:

**Using the Dev Console:**
- The Dev Console provides additional tools for interacting with ERC-20 tokens
- Look for token interaction tools in the ICTT section
- These tools provide a user-friendly interface without requiring command-line knowledge

**Using Wallets:**
- Import the token address into MetaMask or other EVM-compatible wallets
- The wrapped token will appear as a standard ERC-20 token
- You can send, receive, and view balances directly in your wallet

**Key Functions:**
- **Deposit/Wrap**: Convert native tokens to wrapped tokens (increases your wrapped token balance)
- **Withdraw/Unwrap**: Convert wrapped tokens back to native tokens (decreases your wrapped token balance)

The wrapped token maintains a 1:1 ratio with the native token, making it perfect for DeFi integrations and cross-chain applications.

</Step>

</Steps>

<Quiz quizId="202"/>

# Introduction (/academy/l1-native-tokenomics/02-custom-tokens/01-introduction)

---
title: Introduction
description: Learn about custom native token of your Avalanche L1 blockchain.
updated: 2025-09-12
authors: [nicolasarnedo]
icon: Book
---

## What is Independent Tokenomics?

Avalanche Custom Blockchains offer multiple ways to implement independent tokenomics. This gives developers more control and can enable new business models that would not be economically feasible on single-chain systems.

The customizations you'll learn about include:

- **Native Token:** Every Avalanche L1 has its own native token used for paying transaction fees
- **Transaction Fees:** Configure how transaction fees should be calculated
- **Initial Native Token Allocation:** Specify how the initial token supply is distributed
- **Native Token Minting Rights:** Define if and who can mint more native tokens
- **Staking Token:** For public and permissionless validation, define your logic for how a node can become a validator

You'll get hands-on experience configuring the tokenomics of your own custom blockchain throughout this course.

Firstly, for financial institutions, having their blockchain with a custom native token can facilitate cheaper transactions compared to traditional banking systems. This flexibility can enable real-time payments, cross-border transactions, and micropayments, fostering financial inclusion and innovation.

For gaming platforms, having their blockchain with a custom native token can revolutionize in-game economies and user experiences. They can design their tokenomics to incentivize gameplay, reward loyal players, and monetize virtual assets.

# Custom Token vs ERC20 (/academy/l1-native-tokenomics/02-custom-tokens/02-custom-native-vs-erc20-native)

---
title: Custom Token vs ERC20
description: Understanding your options for native tokens on Avalanche L1s
updated: 2025-01-15
authors: [nicolasarnedo]
icon: BookOpen
---

Every Avalanche L1 blockchain has its own native token used for paying for transactions (gas). This isolates the fee to use the blockchain from any activity on other chains in the ecosystem.

For example, if there is high usage of the primary network, it does not affect the fees on another Avalanche L1.

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/multi-chain-architecture/gas-comparison-6CHcnngJHLqW9ZluUv60SzpiIdUjo2.png)

Having their own blockchain with a custom native token in the Avalanche network can open up a wide range of new use cases for companies, ranging from financial institutions to gaming platforms. By having control over their gas token, these companies can revolutionize the blockchain landscape and enable innovative applications.

When designing your Avalanche L1, you have two options for what will be the native token of your chain. In this section we outline which one will create the right tokenomics for your use case.

## Option 1 - *Custom Native Token*

Creating a **custom native token** gives you complete control over your blockchain's gas token. This approach offers several advantages:

- **Custom Tokenomics**: Design token distribution, inflation, and utility to match your project's needs
- **Business Model Flexibility**: Avoid the high costs of sponsoring transaction fees on other chains. You can make the native token intentionally valueless to deliver gas-free experiences, eliminate fee sponsorship burdens, and create Web2-like UX that removes barriers for mainstream users
- **Fee Control**: Set predictable, isolated transaction costs independent of other chains' activity and token price volatility
- **Economic Design**: Create token utility, reward mechanisms, and incentive structures that align with your application's goals

## Option 2 - *Existing ERC20 as Native Token*

You can also tie your native token's value to an **existing ERC20 token** (like USDC). This approach offers:

- **Price Stability** (if you chose a stablecoin): It will ensure predictable gas costs for users; say 0.001 AVAX is the gas cost, AVAX might it be worth more in November than in January. During high congestion moments on your Stablecoin-based L1 gas price will still increase, just the underlying asset to pay it will always remain constant.
- **Familiar Asset**: Users already understand and trust the underlying asset

## L1 Native Tokenomics Decision Outline

This **L1 Native Tokenomics** course focuses on implementing and creating an L1 with a **custom native token**. You'll learn how to:

- Create custom token
- Assign Initial Allocation
- Use Wrapped Native Token pre-deployed contract
- Configure Native Minting Rights
- Configure Fee Configuration for Transactions

*Using existing ERC20 tokens* or **another chain's native token** as your L1's native token will be covered in the **Cross-Chain L1 Native** course*.



# Native and Staking Tokens (/academy/l1-native-tokenomics/02-custom-tokens/03-native-vs-staking)

---
title: Native and Staking Tokens
description: Understanding your options for native tokens on Avalanche L1s
updated: 2025-01-15
authors: [nicolasarnedo]
icon: BookOpen
---

It's important to understand that your **native token and staking token don't necessarily have to be the same**:

- **Native Token**: Used for paying transaction fees (gas)
- **Staking Token**: Used for validator rewards and network security

This separation allows for more flexible tokenomics design and can optimize different aspects of your blockchain's economy.

**Validator management and staking tokenomics** will be covered in:
- [Permissioned L1s](/academy/permissioned-l1s) course: Learn about validator manager deployment options
- [Permissionless L1s](/academy/permissionless-l1s) course: Learn about staking tokenomics and validator economics

# Token Symbol (/academy/l1-native-tokenomics/02-custom-tokens/04-token-symbol)

---
title: Token Symbol
description: Understanding token symbol conventions and their importance in blockchain ecosystems
updated: 2025-08-21
authors: [nicolasarnedo]
icon: BookOpen
---

When creating a custom native token for your Avalanche L1, choosing the right token symbol is more important than it might initially seem. A token symbol serves as the shorthand identifier for your token across wallets, exchanges, and applications.

## Symbol Conventions

Token symbols typically follow these conventions:
- **Length**: 3-5 characters (ETH, AVAX, USDC, BTC)
- **Format**: All uppercase letters
- **Uniqueness**: Should be distinct from existing popular tokens
- **Relevance**: Often relates to the project name or purpose

## Native Token Symbol in Code

In Solidity and other EVM-based smart contracts, there's an important convention to understand. The native token is always referred to as **"ether"** in the code, regardless of what the actual token symbol is on your blockchain.

For example:
```solidity
// This always refers to the native token, whether it's ETH, AVAX, or your custom token
msg.value // Amount of native token sent
address.balance // Native token balance
payable(recipient).transfer(1 ether) // Transfer 1 unit of native token
```

This convention exists because Solidity was originally designed for Ethereum, where the native token is Ether. The keyword "ether" became a unit denomination in the language itself.

## Custom L1 Considerations

When launching your Avalanche L1:
- Your chosen symbol (e.g., "GAME", "DEFI") is what users see in wallets and explorers
- But in smart contract code, you'll still use "ether" as the unit
- This separation between display symbol and code convention helps maintain compatibility

## Best Practices

1. **Research existing symbols** to avoid conflicts
2. **Keep it memorable** and easy to type
3. **Consider your brand** - the symbol becomes part of your identity
4. **Check trademark considerations** for your chosen symbol

Your token symbol is often the first thing users encounter, so choose wisely!

# Create Custom Token (/academy/l1-native-tokenomics/02-custom-tokens/05-create-custom-token)

---
title: Create Custom Token
description: Understanding token symbol conventions and their importance in blockchain ecosystems
updated: 2025-08-21
authors: [nicolasarnedo]
icon: Terminal
---

In this course, we'll use the [Developer Console](/console) to create a new L1. While you may have already created an L1 in the Avalanche Fundamentals course, we'll now walk through the process again—this time explaining in detail each tokenomics configuration option available. The goal of this first step is simple: create your Subnet and set your blockchain's token name and token symbol.

## Create Subnet and Chose Token name

Use the tool below to create a Subnet and then add a blockchain to it. In the Genesis configuration, only set the token name and token symbol for now (you can ignore the other sections).

<Callout type="info">
**Token Name**: The token name is purely cosmetic and not recorded anywhere in the blockchain code (except for the wrapped native token contract). It's mainly used for display purposes in wallets and explorers.
</Callout>

<Callout type="warning" type="warn">
Don't hit **create chain** yet, we will configure other tokenomics (supply, allocation, fees, etc.) in later steps of this course.
</Callout>

<ToolboxMdxWrapper walletMode="c-chain">
  <CreateChain embedded={true} initiallyExpandedSections={['ChainParamsSection']} />
</ToolboxMdxWrapper>



# Native Token Allocation (/academy/l1-native-tokenomics/02-custom-tokens/06-native-token-allocation)

---
title: Native Token Allocation
description: Initial token allocation of a blockchain refers to the distribution of native tokens when a new blockchain network is launched.
updated: 2024-06-28
authors: [usmaneth]
icon: BookOpen
---

The creator of an Avalanche L1 can pre-allocate the native tokens during the chain genesis event. The initial token allocation of a blockchain refers to the distribution of tokens or digital assets when a new blockchain network is launched.

This allocation is a critical aspect of the network's design, as it determines how tokens are distributed among various stakeholders and participants.

There are several considerations that go into the initial token allocation:

- **Founders and Development Team:** Often, a portion of the initial token supply is allocated to the founders and development team as a reward for their efforts in creating the blockchain protocol. This allocation serves as an incentive for them to continue developing and maintaining the network.
- **Early Investors and Backers:** Another portion of the token supply may be allocated to early investors and backers who provided funding or support during the project's early stages. These individuals or entities take on early risk and are rewarded with tokens that may increase in value as the network grows.
- **Community:** A significant portion of tokens may be allocated to the community through mechanisms such as a token sale, airdrops, or other distribution methods. This ensures widespread ownership and participation in the network, fostering decentralization and security.
- **Reserve:** Some tokens may be allocated to a reserve or treasury to fund ongoing development, marketing, and ecosystem growth initiatives. This reserve can be managed by a decentralized autonomous organization (DAO) or a designated entity responsible for allocating funds in the best interest of the network.

Overall, the initial token allocation of a blockchain is a complex and crucial aspect of its design, shaping the network's distribution of ownership, governance, and incentives from the very beginning.

Transparent and equitable token allocation mechanisms are essential for fostering trust and confidence in the network among its stakeholders.

# Configure Native Token Allocation (/academy/l1-native-tokenomics/02-custom-tokens/07-configure-token-allocation)

---
title: Configure Native Token Allocation
description: Learn how to configure your blockchain native token allocation.
updated: 2024-06-28
authors: [usmaneth]
icon: Terminal
---

Alright, so let's set the initial token allocation. When prompted select **addresses and the amount of your token they will have from the genesis*.

<GenesisBuilder embedded={true} initiallyExpandedSections={['tokenomics']} />

# Introduction (/academy/l1-native-tokenomics/03-precompiles/01-introduction)

---
title: Introduction
description: Chapter overview and core blockchain concepts review
updated: 2025-01-15
authors: [nicolasarnedo]
icon: Book
---

In this section we are going to quickly address what Precompiles are, why we need them and how they are implemented. The reason we cover this in the L1 Native Tokenomics course is because in the next two sections we will be working with 2 precompiles that heavily influence the tokenomics of a chain, the [Native Minter](/l1-native-tokenomics/04-native-minter) and [Fee Config](/l1-native-tokenomics/05-fee-config) Precompiles.

Specifically we are going to look into **Stateful Precompiles**, but if you wish to learn more in detail about Precompiles and how you can use them to configure your L1 please check out the [Customizing the VM](/customizing-evm) course!

## Core Concepts Review (Optional)

Before we look more closely into precompiles, it is important we re-visit and fully understand some core concepts about how blockchains and virtual machines work.

### Deterministic State Transitions

Blockchains rely on a **deterministic machine (the EVM)** to calculate transitions from one state to the next. Every transaction modifies the blockchain state in a predictable, reproducible way—ensuring all nodes reach consensus on the new state.

![State Transitions](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/Precompiles_State.png)

### EVM as a Configurable Specification

Think of the EVM like a class in Object-Oriented Programming: it's a specification that defines behavior. Each blockchain—Ethereum, Avalanche C-Chain, or your custom L1—is an **instance** of this EVM class, with its own configuration.

![EVM Instances](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/Precompiles_OOP.png)

**Through Avalanche, you can configure your EVM instance with precompiles that live at the execution level** (will dive deeper into this later), giving you control over core blockchain functionality like native token minting and transaction fee configuration.


# Stateful Precompiles (/academy/l1-native-tokenomics/03-precompiles/02-precompiles)

---
title: Stateful Precompiles
description: Understanding Stateful Precompiles and their role in blockchain optimization
updated: 2025-01-15
authors: [nicolasarnedo]
icon: BookOpen
---

First of all we will start by saying the notion of precompiles contracts, or "*Precompiles*" as we are calling them, is something inherited from the Ethereum community. The EVM, while very robust and efficient for handling thousands of simple transactions like token minting, swapping or so, has a series of limitations:

### Lack of Libraries

Solidity is a relatively new language, hence it doesn't have as many powerful and battle-tested libraries as other languages like *Go*, *Typescript* or *Rust*

### Expensive Computation

Solidity code is compiled into EVM opcodes—low-level instructions designed for simple operations like addition, storage reads, and basic logic. 

When performing complex mathematical operations (like elliptic curve cryptography or modular exponentiation), these simple opcodes must be chained together, requiring many steps and frequent use of expensive operations like `SSTORE` (storage writes) which cost 20,000 gas or more. This makes advanced cryptography impractically expensive in pure Solidity

## Basic Precompiles 

Given these limitations - many developer teams/communities have proposed creating programs written in more efficient languages (Go/Rust) for well-known or frequently used operations that may temporarily by-pass the limitations of the smart contract language of that blockchain. These "programs" are then wrapped in a interface (solidity/move) and deployed to a pre-defined address so they can be called from other smart contracts in the application layer.

<img src="https://qizat5l3bwvomkny.public.blob.vercel-storage.com/precompile_strucutre.png" alt="Precompiles Structure" style={{ maxWidth: '60%', height: 'auto', margin: '0 auto', display: 'block' }} />

Instances of these Precompiles exists across most major blockchain platforms:
- Ethereum has standard precompiles at fixed addresses
- Solana uses "Native Programs" written in Rust
- Aptos and Sui have "Native Functions" exposed through Move modules

For Avalanche, these precompiles are especially important because you are the **owner** of your L1. Rather than having to go through several community approvals (the case for single-chain environments like Ethereum and Solana) and executing a network upgrade to implement them, you can directly define them in the genesis block! (*or add them as well through a network upgrade*)

### Common Precompiles

Here are some of the most widely used precompiles across EVM-compatible blockchains:

**Cryptographic Operations:**
- `ecRecover` (0x01): Recover Ethereum address from ECDSA signature
- `SHA256` (0x02): SHA-256 hash function

## Stateful Precompiles

The basic precompiles we've discussed so far (like ecRecover and SHA256) are **stateless**—they perform computations and return results without modifying the blockchain state. However, Avalanche introduces a more powerful concept: **Stateful Precompiles**.

Stateful precompiles go a step further by **injecting state access** through the `PrecompileAccessibleState` interface. This gives them the ability to:
- Read and modify account balances
- Read and write to contract storage
- Access the full EVM state during execution

This state access makes stateful precompiles far more powerful than their stateless counterparts. Instead of just performing calculations, they can directly manipulate blockchain state at the protocol level—enabling use cases like native token minting, fee configuration, and transaction/contract deployer permissioning.

Through stateful precompiles, Avalanche provides a level of EVM customization that goes beyond what's possible with the original precompile interface, making it ideal for building highly customized L1 blockchains.


# Protocol Integration (/academy/l1-native-tokenomics/03-precompiles/03-precompile-architecture)

---
title: Protocol Integration
description: How precompiles integrate with the VM stack and optimize execution
updated: 2025-01-15
authors: [nicolasarnedo]
icon: BookOpen
---

Blockchains are organized into three distinct layers, each with specific responsibilities:

![Blockchain Layers](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/Precompiles_Layers1.png)

1. **Application Layer**: Where smart contracts and user applications run
2. **Execution Layer**: Where the EVM processes transactions and executes code
3. **Consensus Layer**: Where validators agree on the blockchain state

Precompiles live in the **Execution Layer**, directly integrated into the EVM itself:

![Precompiles in Execution Layer](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/Precompiles_Layers2.png)

## Why Aren't Precompiles in the Application Layer?

You might wonder: if precompiles can be called like smart contracts, why aren't they stored with other smart contracts in the application layer?

The answer comes down to **performance and access**:

**1. Direct State Access**  
Smart contracts in the application layer must go through the EVM interpreter to access blockchain state. Precompiles, living in the execution layer, have **direct access** to the EVM state—they can read and modify balances, storage, and consensus data without the overhead of bytecode interpretation.

**2. Native Code Execution**  
Application layer contracts are compiled to EVM bytecode and executed opcode-by-opcode. Precompiles are written in Go (Avalanche's client language) and execute as **native code**, making them orders of magnitude faster for complex operations.

**3. Protocol-Level Operations**  
Precompiles need to perform operations that regular smart contracts cannot or should not do—like minting native tokens, configuring transaction fees, or managing validator permissions. These are **protocol-level concerns** that require execution layer access.

**4. Security Boundaries**  
By keeping precompiles in the execution layer, we maintain a clear security boundary. User-deployed contracts can't interfere with protocol operations, and protocol operations benefit from the stability and security of the client software itself.

This architectural separation is what makes stateful precompiles so powerful: they bridge the gap between user applications and the blockchain protocol, enabling customizations that would be impossible in the application layer alone.

# Introduction (/academy/l1-native-tokenomics/04-native-minter/01-introduction)

---
title: Introduction
description: Understanding the Native Minter Precompile and token supply management
updated: 2025-08-21
authors: [nicolasarnedo]
icon: Book
---

In the previous section, we learned about precompiles and how they enable protocol-level customization of your L1. Now we'll put that knowledge into practice with the **Native Minter Precompile**—one of the most powerful tools for managing your blockchain's tokenomics.

## What You'll Learn

This section covers:
- **Native Token Supply**: Understanding hard-capped vs. flexible token supplies
- **Native Minter Precompile**: How to enable and control native token minting
- **Minting Rights Management**: Configuring who can mint new tokens

## Why This Matters

The Native Minter Precompile determines whether your blockchain has a fixed token supply (like Bitcoin's 21M cap) or can mint additional tokens as needed. This decision has major implications:

- **Valueless Gas Tokens**: Enable gas-free user experiences by minting tokens as needed
- **Controlled Inflation**: Manage token supply for economic incentives
- **Protocol Flexibility**: Adapt your tokenomics as your ecosystem grows

By the end of this section, you'll understand how to configure native token minting rights for your L1's specific use case.

Let's dive in!


# Native Token Minting Rights (/academy/l1-native-tokenomics/04-native-minter/02-native-token-minting-rights)

---
title: Native Token Minting Rights
description: Learn how to manage the native token minting rights.
updated: 2024-06-28
authors: [usmaneth]
icon: BookOpen
---

Many chains have a hard-capped supply for their gas token. The Avalanche C-Chain uses AVAX as their gas token and there will only ever be 720m AVAX. This may not be optimal for enterprise use cases, especially if they want to **create an experience with a valueless gas token**.

Therefore, they have the option to mint more native tokens at any time. This can be done through the **Native Minter Precompile**. If a community running an Avalanche L1 wants to hard-cap the native token, that is perfectly doable as well. They just keep the native minter capabilities deactivated (which is the default).

import NativeMinter from "@/content/common/evm-precompiles/native-minter.mdx";

import defaultMdxComponents from "fumadocs-ui/mdx";

<NativeMinter components={defaultMdxComponents}/>

In the upcoming chapter, we will only use an admin address in order to keep the exercise simple.

<Quiz quizId="410"/>

# Activate Native Minter (/academy/l1-native-tokenomics/04-native-minter/03-activate-native-minter)

---
title: Activate Native Minter
description: Learn how to activate the native minter precompile.
updated: 2024-06-28
authors: [usmaneth]
icon: Terminal
---

When prompted if you want to allow minting of new natie tokens, select **Allow minting additional tokens**.

<Callout type="warning">
Remember, we're still configuring the genesis for our L1—**don't hit "Create Chain" yet!** We'll continue adding more tokenomics configurations in the following sections and finally create the chain in the Genesis Breakdown section where you'll see all your configurations come together.
</Callout>

<GenesisBuilder embedded={true} initiallyExpandedSections={['tokenomics']} />

# Introduction (/academy/l1-native-tokenomics/05-fee-config/01-introduction)

---
title: Introduction
description: Let's recap our knowledge on transaction fees in blockchains
updated: 2024-06-28
authors: [usmaneth]
icon: BookOpen
---

import TransactionFees from '@/content/common/multi-chain-architecture/transaction-fees.mdx';

<TransactionFees />
<Quiz quizId="403"/>

# Transaction Fees (/academy/l1-native-tokenomics/05-fee-config/02-transaction-fees)

---
title: Transaction Fees
description: Learn about L1 blockchain gas fees.
updated: 2024-06-28
authors: [usmaneth]
icon: BookOpen
---

When creating an Avalanche L1 we can configure not only our custom native token, but also how the transaction fees (also known as gas fees) are determined. This allows Avalanche L1s to define the desired or maximal throughput of the blockchain differently.

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/multi-chain-architecture/subnet-fee-comparison-RDdq99JjKbXqvCIQBnreWAwwjzY2jn.png)

To adjust the fee dynamics we have the following parameters:

**Gas Limit:** The total amount of gas that can be used in a single block. This impacts how much computation happens in one block. The value represents the maximum amount of gas a single transaction can use (which would result in a single-transaction block).

**Target Block Rate:** The network aims to produce a new block in targetBlockRate seconds. This value is in seconds. If the network starts producing faster than this, base fees are increased accordingly. Otherwise, if the network starts producing slower than this, base fees are decreased accordingly.

**Min. Base Fee:** The minimum base fee that can be used by a transaction and the cost to do native token transfers. No matter how simple a transaction is, it will cost at least the minimum base fee.

**Target Gas:** The targeted amount of gas (including block gas cost) to consume within a rolling 10s window.

**Base Fee Change Denominator:** The transaction base fee changes with demand of the block space. If the parent block used more gas than its target, the base fee should increase. Otherwise, if the parent block used less gas than its target, the base fee should decrease by the amount. There is a formula behind this that would go beyond the scope of this section, but setting this value to a larger value means that the base fee will change more gradually. Setting it to a smaller value will make the base fee change more rapidly.

**Min. Block Gas Cost:** Minimum gas cost a block should cover.

**Max. Block Gas cost:** Maximum gas cost a block should cover.

**Block Gas Cost Step:** This value determines the block gas change rate depending on the targetBlockRate. If the parent block is produced at the targetBlockRate, the block gas cost will stay the same. If the parent block is produced at a slower rate, the block gas cost will decrease.


# Activate Fee Config (/academy/l1-native-tokenomics/05-fee-config/03-activate-fee-config)

---
title: Activate Fee Config
description: Learn how to configure your blockchain gas fees.
updated: 2024-06-28
authors: [usmaneth]
icon: Terminal
---

Below you can set your custom fee configuration, select **Customize fee config**. Below toggle the **Reward Manager** and hit the *Add Wallet* button to include your connected wallet in the allowlist for this Precompile.

<Callout type="warning">
Remember, we're still configuring the genesis for our L1—**don't hit "Create Chain" yet!** We'll continue adding more configurations in the following sections and finally create the chain in the Genesis Breakdown section where you'll see all your configurations come together.
</Callout>

<GenesisBuilder embedded={true} initiallyExpandedSections={['feeConfiguration']} />

# Initial Allocation (/academy/l1-native-tokenomics/07-token-distribution/01-initial-allocation)

---
title: Initial Allocation
description: Considerations for the initial token allocation on an Avalanche L1
updated: 2024-09-03
authors: [0xstt]
icon: Book
---

The creator of an Avalanche L1 can pre-allocate native tokens during the chain genesis event. This **initial token allocation** refers to the distribution of tokens or digital assets when a new blockchain network is launched, which is a crucial aspect of the network's design.

> **Note:** Initial token allocation determines how tokens are distributed among stakeholders and participants.

### Key Considerations for Initial Token Allocation

There are several factors to consider when allocating tokens:

#### Founders and Development Team

A portion of the initial token supply is often allocated to the founders and the development team as a reward for their efforts in creating the blockchain protocol. This serves as an incentive for continued development and network maintenance.

#### Early Investors and Backers

Another portion of the token supply may be allocated to early investors and backers who provided funding or support during the project's early stages. These entities take on early risk and are rewarded with tokens that may increase in value as the network grows.

#### Community

A significant portion of tokens may be allocated to the community through mechanisms such as token sales, airdrops, or other distribution methods. This ensures widespread ownership and participation in the network, fostering decentralization and security.

#### Reserve

Some tokens may be allocated to a reserve or treasury to fund ongoing development, marketing, and ecosystem growth initiatives. This reserve can be managed by a DAO or another entity tasked with allocating funds for the network's benefit.

> **Tip:** Transparent and equitable token allocation mechanisms are essential for fostering trust and confidence in the network among its stakeholders.

<Quiz quizId="212" />

# Vesting Schedules (/academy/l1-native-tokenomics/07-token-distribution/02-vesting-schedules)

---
title: Vesting Schedules
description: Learn about vesting schedules and how to implement them in Solidity.
updated: 2024-10-08
authors: [owenwahlgren]
icon: Book
---

**Vesting schedules** are mechanisms used in blockchain projects to release tokens to team members, investors, or other stakeholders over a specified period. This approach helps align incentives, prevent immediate sell-offs, and promote long-term commitment to the project.

---

## Understanding Vesting Schedules

A vesting schedule dictates how and when tokens are released to a recipient. Common elements include:

- **Cliff Period**: An initial period during which no tokens are vested.
- **Vesting Period**: The total duration over which tokens are gradually released.
- **Release Interval**: The frequency at which tokens are released (e.g., monthly, quarterly).
- **Total Allocation**: The total number of tokens to be vested.

### Types of Vesting Schedules

1. **Linear Vesting**: Tokens are released uniformly over the vesting period.
2. **Graded Vesting**: Tokens vest in portions at different intervals.
3. **Cliff Vesting**: All or a significant portion of tokens vest after the cliff period.

---

## Implementing Vesting Schedules in Solidity

Smart contracts can automate vesting schedules, ensuring transparency and trustlessness. Below is an example of a simple Solidity contract implementing a linear vesting schedule.

### Example Solidity Contract

```solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

contract TokenVesting {
    address public beneficiary;
    uint256 public start;
    uint256 public duration;
    uint256 public cliff;
    uint256 public totalTokens;
    uint256 public released;

    IERC20 public token;

    constructor(
        address _token,
        address _beneficiary,
        uint256 _start,
        uint256 _cliffDuration,
        uint256 _duration,
        uint256 _totalTokens
    ) {
        require(_beneficiary != address(0), "Invalid beneficiary");
        require(_cliffDuration <= _duration, "Cliff longer than duration");
        require(_duration > 0, "Duration must be > 0");

        token = IERC20(_token);
        beneficiary = _beneficiary;
        start = _start;
        cliff = _start + _cliffDuration;
        duration = _duration;
        totalTokens = _totalTokens;
    }

    function release() public {
        require(block.timestamp >= cliff, "Cliff period not reached");
        uint256 unreleased = releasableAmount();
        require(unreleased > 0, "No tokens to release");

        released += unreleased;
        token.transfer(beneficiary, unreleased);
    }

    function releasableAmount() public view returns (uint256) {
        return vestedAmount() - released;
    }

    function vestedAmount() public view returns (uint256) {
        if (block.timestamp < cliff) {
            return 0;
        } else if (block.timestamp >= start + duration) {
            return totalTokens;
        } else {
            return (totalTokens * (block.timestamp - start)) / duration;
        }
    }
}

interface IERC20 {
    function transfer(address recipient, uint256 amount) external returns (bool);
}

# Bonding Curves (/academy/l1-native-tokenomics/07-token-distribution/03-bonding-curves)

---
title: Bonding Curves
description: Learn about bonding curves and their role in token economics.
updated: 2024-10-08
authors: [owenwahlgren]
icon: Book
---

**Bonding curves** are mathematical formulas used in blockchain and token economics to define the relationship between a token's price and its supply. They provide a mechanism for automated price discovery and liquidity, enabling decentralized issuance and trading of tokens without relying on traditional market makers or exchanges.

---

## Understanding Bonding Curves

A bonding curve is a continuous token model where the price of a token is determined by a predefined mathematical function based on the total supply in circulation. As more tokens are purchased and the supply increases, the price per token rises according to the curve. Conversely, selling tokens decreases the supply and lowers the price.

### Key Concepts

- **Automated Market Maker (AMM)**: A system that provides liquidity and facilitates trading by automatically adjusting prices based on supply and demand.
- **Price Function**: A mathematical formula that defines how the token price changes with supply.
- **Liquidity Pool**: A reserve of tokens used to facilitate buying and selling without requiring counterparties.

---

## How Bonding Curves Work

### Price Functions

The bonding curve relies on a price function `P(S)`, where:

- `P` is the price per token.
- `S` is the current supply of tokens.

Common price functions include linear, exponential, and sigmoid curves.

#### Linear Bonding Curve

A simple linear function:

```
P(S) = a * S + b
```

- `a` and `b` are constants defining the slope and intercept.

#### Exponential Bonding Curve

An exponential function:

```
P(S) = e^(k * S)
```

- `e` is the base of the natural logarithm.
- `k` is a constant determining the rate of price increase.

### Buying and Selling Tokens

- **Buying Tokens**: To purchase tokens, a user pays an amount calculated by integrating the price function over the desired increase in supply.
- **Selling Tokens**: To sell tokens, a user receives an amount calculated by integrating the price function over the desired decrease in supply.

---

## Applications of Bonding Curves

### Token Launch Mechanisms

Bonding curves enable projects to launch tokens without initial liquidity or listing on exchanges.

- **Continuous Token Issuance**: Tokens can be minted on-demand as users buy them.
- **Fair Price Discovery**: Prices adjust automatically based on demand.

### Decentralized Finance (DeFi)

Used in AMMs and liquidity pools to facilitate decentralized trading.

- **Uniswap**: Utilizes bonding curves for token swaps.
- **Balancer**: Manages portfolios using bonding curves.

### Fundraising and DAOs

Facilitate fundraising by allowing investors to buy tokens that represent shares or voting rights.

- **Continuous Organizations**: Organizations that continuously raise funds through token sales governed by bonding curves.
- **DAO Membership**: Tokens purchased via bonding curves grant access and voting power.

---

## Implementing Bonding Curves in Smart Contracts

### Solidity Example

Below is a simplified example of implementing a linear bonding curve in Solidity.

```solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

contract BondingCurve {
    uint256 public totalSupply;
    uint256 public constant a = 1e18; // Slope
    uint256 public constant b = 1e18; // Intercept
    mapping(address => uint256) public balances;

    function buy() external payable {
        uint256 tokensToMint = calculateTokensToMint(msg.value);
        balances[msg.sender] += tokensToMint;
        totalSupply += tokensToMint;
    }

    function sell(uint256 tokenAmount) external {
        require(balances[msg.sender] >= tokenAmount, "Insufficient balance");
        uint256 ethToReturn = calculateEthToReturn(tokenAmount);
        balances[msg.sender] -= tokenAmount;
        totalSupply -= tokenAmount;
        payable(msg.sender).transfer(ethToReturn);
    }

    function calculatePrice(uint256 supply) public pure returns (uint256) {
        return a * supply + b;
    }

    function calculateTokensToMint(uint256 ethAmount) public view returns (uint256) {
        // Simplified calculation for demonstration purposes
        uint256 tokens = ethAmount / calculatePrice(totalSupply);
        return tokens;
    }

    function calculateEthToReturn(uint256 tokenAmount) public view returns (uint256) {
        // Simplified calculation for demonstration purposes
        uint256 ethAmount = tokenAmount * calculatePrice(totalSupply);
        return ethAmount;
    }
}
```

Explanation

- **`buy()`:** Users send ETH to buy tokens. The number of tokens minted is calculated based on the bonding curve.
- **`sell()`:** Users can sell their tokens back for ETH. The amount of ETH returned is calculated based on the current supply.
- **`calculatePrice()`:** Determines the price per token based on the total supply.

<Callout>This is a simplified example and not suitable for production. Proper handling of floating-point arithmetic and security considerations is necessary.</Callout>

### Considerations and Risks

**Price Volatility**

- **Speculation**: Prices can become volatile due to speculative trading.
- **Market Manipulation**: Large trades may influence prices significantly.

**Smart Contract Risks**

- **Security Vulnerabilities**: Bugs in the contract can lead to loss of funds.
- **Complexity**: Implementing accurate bonding curves requires careful mathematical and technical design.

**Liquidity Concerns**

- **Slippage**: Large trades may experience significant price slippage.
- **Liquidity Pools**: Adequate reserves are necessary to handle buy and sell orders.

## Conclusion

Bonding curves offer a powerful tool for automated price discovery and token issuance in decentralized networks like Avalanche. They enable projects to create self-sustaining economies with built-in liquidity and dynamic pricing. Understanding bonding curves is essential for developers and stakeholders involved in tokenomics and decentralized finance.

By carefully designing bonding curve parameters and smart contracts, projects can align incentives, promote fair participation, and foster sustainable growth within their ecosystems.
<Quiz quizId="213"/>

# Airdrops (/academy/l1-native-tokenomics/07-token-distribution/04-airdrop)

---
title: Airdrops
description: Learn about token airdrops and Core's airdrop service in the Avalanche ecosystem.
updated: 2024-10-08
authors: [owenwahlgren]
icon: Book
---

**Token airdrops** are a popular method in the blockchain ecosystem for distributing tokens to users, promoting projects, and incentivizing community engagement. In the Avalanche network, airdrops can help bootstrap new projects, reward loyal participants, and increase the distribution of tokens to a wider audience.

---

## Understanding Airdrops

Airdrops involve sending tokens directly to users' wallets, typically for free or in exchange for simple tasks like participating in network activities, holding a specific token, or interacting with a smart contract. They serve multiple purposes:

- **Marketing and Promotion**: Raise awareness about a new project or token.
- **User Acquisition**: Attract new users to a platform or service.
- **Community Rewards**: Reward loyal users and early adopters.
- **Decentralization**: Distribute tokens widely to enhance network decentralization.

---

## Core Wallet's Airdrop Tool

[Core](https://core.app/), Avalanche's native ecosystem wallet and portfolio, has integrated a new promotions and airdrop tool developed by Ava Labs. This tool leverages on-chain data sources for seamless token distribution, allowing any builder to strategically reward their loyal community members.

### Key Features

- **On-Chain Data Integration**: Utilizes indexed on-chain data to identify and reward true users based on their interactions with contracts.
- **User-Friendly Interface**: Provides a straightforward, free method to use on-chain data for airdrops and promotions.
- **Custom Queries**: Allows builders to locate community members who have interacted with their contracts using the query builder.
- **Manual Address Addition**: Enables manual addition or upload of addresses for token distribution.

### How It Works

Ava Labs indexes on-chain data, enabling Core's airdrop tool to quickly analyze contract-level activity. Daily aggregation of C-Chain token balances is conducted at the close of each day (UTC time), collecting balances of native tokens, ERC20, and ERC721 tokens. Users can leverage this data to pinpoint addresses that meet specific criteria based on token activity.

At launch, the tool supports Avalanche C-Chain and a subset of ERC20 tokens, with more tokens to be added in the future.

#### Query Builder

- **Filter Options**: Filter based on holding duration, current holdings, minimum holding duration, or customized date ranges.
- **Multiple Queries**: Conduct multiple queries in a single search to refine the target audience.

#### Airdrop Distribution

Airdrops are distributed through contracts deployed on-chain. Core's airdrop tool leverages a deployed version of ThirdWeb's audited Airdrop contract and Ava Labs’ internal security team. At launch, airdrops will be distributed evenly among all selected wallets.

---

## Benefits of Using Core's Airdrop Tool

- **Efficient Distribution**: Streamlines token distribution and community engagement with its intuitive interface.
- **Cost-Free**: Provides a free method for builders to conduct airdrops and promotions.
- **Strategic Rewards**: Allows for targeted airdrops based on specific on-chain activities.
- **Security**: Utilizes audited contracts and security measures to protect token distributions.

---

## Real-World Example: Core Memecoin Month

To showcase the power of the new airdrop tool, Core rewarded all participants from their **Core Memecoin Month**, which ran from April 1 to May 6. Participants received an evenly distributed reward in the same memecoin they used during the event. For example, if a participant qualified by following instructions during COQ’s memecoin week, they were airdropped COQ coins.

---

## Considerations

- **Regulatory Compliance**: Ensure that airdrops comply with relevant laws and regulations in your jurisdiction.
- **User Privacy**: Be mindful of user privacy and data protection when handling wallet addresses.
- **Security Best Practices**: Utilize audited contracts and follow security best practices to protect against vulnerabilities.

---

## Conclusion

Airdrops are a valuable tool for projects in the Avalanche ecosystem to engage with their community, distribute tokens, and promote network growth. Core's new airdrop tool simplifies this process by leveraging on-chain data and providing an intuitive interface for builders and developers.

By utilizing Core's airdrop service, projects can efficiently and securely reward their loyal community members, fostering stronger relationships and encouraging active participation in the Avalanche network.

---

# Introduction (/academy/l1-native-tokenomics/08-governance/01-introduction)

---
title: Introduction
description: An overview of governance use cases in Avalanche Layer 1 tokenomics, focusing on token-based voting and permissioning mechanisms.
updated: 2024-09-03
authors: [owenwahlgren]
icon: Book
---

Governance in Avalanche Layer 1 networks center around two fundamental concepts: **token-based voting** and **permissioning through precompiles**. These mechanisms empower the community to manage critical aspects of network functionality and access control. This chapter explores various governance models within the Avalanche ecosystem, including Decentralized Autonomous Organizations (DAOs), quadratic voting, and real-world governance use cases.

### Key Aspects of Governance in Avalanche

#### Token-Based Voting

Token holders of a Layer 1 can play a pivotal role in the governance of the network. They have the authority to vote on proposals that can affect both technical parameters and broader policy decisions. This system ensures that individuals with a stake in the network have a direct influence over its future development.

#### Permissioning Through Precompiles

Governance on Avalanche L1 networks also involves managing precompiles, specifically precompiles with the [AllowList interface](/docs/avalanche-l1s/upgrade/customize-avalanche-l1#allowlist-interface). Precompiles are specialized smart contracts that provide functionalities not available through standard contracts. The AllowList interface is a part of multiple precompiles and can govern who can deploy contracts or send transactions on the network among other functionality. Through governance, the community can vote to add or remove addresses from the AllowList, controlling who has permission to perform specific actions on the network.

### Examples of Governance Use Cases for an Avalanche L1

1. **AllowList Precompile Governance**

   - **Adding or Removing Addresses**

   A common governance activity involves proposals to modify the AllowList for a specific precompile (ie [NativeTokenMinter](/docs/avalanche-l1s/upgrade/customize-avalanche-l1#minting-native-coins)). These proposals may focus on adding or removing addresses, thereby determining who is authorized to interact with the precompile, for example deploying contracts or sending transactions on specific L1s. Token holders can vote on these proposals to ensure that only trusted entities are granted these permissions.

2. **DAOs and L1 Governance**

   - **Decentralized Autonomous Organizations (DAOs)**

   In the Avalanche ecosystem, DAOs can govern specific L1s by making critical decisions on upgrades, permissioning, and operational rules. These organizations typically use token-based voting to reach consensus and effectively manage their resources.

3. **Quadratic Voting**

   - **Promoting Fair Decision-Making**

   Quadratic voting could be employed in a Layer 1's governance to promote more democratic decision-making. This method allocates voting power more equitably among participants, allowing for nuanced decisions. It helps balance the influence between larger and smaller token holders, ensuring that the governance process is fair and representative.

### Importance of Governance in Avalanche L1 Tokenomics

**Permission and Access Control**  
  Governance over precompiles with the AllowList interface is crucial for decentralizing control over key network functions. It ensures that only community-approved entities can access sensitive parts of the network, enhancing security and trust.

**Balancing Influence**  
  Mechanisms such as quadratic voting help balance power between large and small token holders. This leads to fairer decision-making processes and fosters a more inclusive community.

**Community-Driven Development**  
  Token-based governance empowers the community to propose and vote on changes that directly influence the network’s future. This includes decisions related to L1 management, technical upgrades, and the addition or removal of participants.

In the following sections, we will delve deeper into these governance models and examine how they function in practice within Avalanche L1 networks.

# Governance Models (/academy/l1-native-tokenomics/08-governance/02-governance-models)

---
title: Governance Models
description: Learn about different governance models in blockchain networks.
updated: 2024-10-08
authors: [owenwahlgren]
icon: Book
---

In blockchain networks like Avalanche and other EVM-compatible platforms, governance models are essential for guiding how decisions are made, who holds the authority, and how changes are implemented within the system. Effective governance ensures that the network evolves in a manner that reflects the community’s interests while promoting sustainability, security, and innovation.

## Understanding Governance Models

Governance models can be broadly categorized into three types:

### 1. On-Chain Governance

On-chain governance involves decision-making processes encoded directly into the blockchain protocol. Participants use the network’s native tokens to vote on proposals, and outcomes are automatically enforced by smart contracts.

**Advantages**:
- Transparency
- Automation
- Immutability

**Disadvantages**:
- Potential for low voter participation
- Risk of governance attacks if tokens are concentrated

### 2. Off-Chain Governance

Off-chain governance relies on discussions and decisions made outside the blockchain, often through forums, social media, or community meetings. While final implementations may involve on-chain actions, deliberation and consensus-building occur off-chain.

**Advantages**:
- Flexibility
- Ability to consider qualitative factors

**Disadvantages**:
- Less transparency
- Potential for slower decision-making

### 3. Hybrid Governance

Hybrid governance combines on-chain and off-chain elements, aiming to balance the advantages of both models. Initial discussions and proposal formulations happen off-chain, while voting and implementation are conducted on-chain.

**Advantages**:
- Improved flexibility
- Enhanced efficiency

**Disadvantages**:
- Complexity in coordination
- Potential disconnect between off-chain discussions and on-chain actions

## Key Components of Governance Models

Effective governance models comprise several key components:

### 1. Proposal Mechanism

A structured process for submitting and discussing proposals is essential.

- **Proposal Submission**: Guidelines for who can submit proposals and how they should be formatted.
- **Discussion Period**: Allocated time for the community to debate and provide feedback.
- **Amendments**: Allowing modifications based on community input before voting.

### 2. Voting System

The method by which votes are cast and counted significantly impacts the governance model’s effectiveness.

- **Token-Based Voting**: Votes are weighted based on the number of tokens held.
- **Quadratic Voting**: Voting power increases quadratically with the number of tokens, promoting fairness.
- **Delegated Voting**: Token holders can delegate their voting power to representatives.


### 3. Execution and Enforcement

Ensuring that approved proposals are implemented correctly is crucial.

- **Automatic Execution**: Smart contracts automatically enforce decisions without human intervention.
- **Manual Execution**: Designated entities carry out decisions, which may introduce delays or risks.

## Governance Models in the Avalanche Ecosystem

Avalanche supports flexible governance models that can be customized for different Layer 1 (L1) chains and projects.

### L1-Specific Governance

Each L1 can implement its own governance model tailored to its needs.

- **DeFi L1**: Might prioritize rapid, on-chain governance to adapt quickly to market changes.
- **Enterprise L1**: Might opt for a hybrid model to incorporate regulatory compliance considerations.

### DAO-Based Governance

Decentralized Autonomous Organizations (DAOs) on Avalanche often adopt on-chain governance models with token-based or quadratic voting systems.

- **Transparency**: All decisions are recorded on the blockchain for auditing.
- **Automation**: Leverage smart contracts to automate proposal submission, voting, and execution.
- **Efficiency**: Enhance efficiency and trust within the community.

### Permissioned Governance

Some L1s may require permissioned governance models, where only authorized participants can vote or propose changes.

- **Private Networks**: Suitable for applications requiring compliance with specific regulations.
- **Controlled Participation**: Ensures that only vetted members influence the network.

## Factors Influencing Governance Model Choice

Several factors influence the selection of a governance model:

### Community Size and Diversity

- **Engagement**: Larger communities may benefit from models that promote inclusivity.
- **Power Distribution**: Models like quadratic voting help mitigate power concentration.

### Regulatory Environment

- **Compliance**: Networks in regulated industries may need governance structures that allow for auditing.
- **Authority Control**: May require oversight by recognized authorities.

### Network Goals and Values

- **Decentralization**: Networks prioritizing decentralization might avoid models with central points of control.
- **Security and Scalability**: The chosen model should align with the network’s primary objectives.

## Challenges in Governance Models

Implementing governance models comes with challenges that need addressing:

### Voter Apathy

- **Low Participation**: Can undermine the legitimacy of decisions.
- **Encouraging Engagement**: Use incentives or simplify processes to boost involvement.

### Governance Attacks

- **Malicious Actors**: May acquire significant voting power to push harmful proposals.
- **Mitigation Strategies**: Implement time locks, quorum requirements, and reputation systems.

### Complexity and Usability

- **Deterring Participation**: Complex models may discourage users.
- **User-Friendly Design**: Ensure mechanisms are accessible to encourage broad involvement.

## The Evolution of Governance Models

Governance models are continually evolving to address new challenges and integrate innovative ideas.

### Enhancing Participation

- **Tools and Interfaces**: Develop user-friendly platforms for easier participation.

### Improving Security

- **Safeguards**: Implement measures against attacks to ensure robustness.

### Adapting to Community Needs

- **Feedback Integration**: Allow models to evolve based on community input and changing requirements.

## Conclusion

Governance models are foundational to the success of blockchain networks like Avalanche. They shape decision-making processes, power distribution, and the network’s ability to adapt over time. By designing and implementing effective governance structures, the community can ensure the network remains secure, innovative, and aligned with participant interests.

Understanding these models enables stakeholders to contribute meaningfully to the network’s evolution. As the ecosystem grows, collaborative and well-structured governance will be key to navigating challenges and seizing opportunities in the decentralized landscape.

<Quiz quizId="214"/>

# DAOs (/academy/l1-native-tokenomics/08-governance/03-daos)

---
title: DAOs
description: Learn about the role and function of DAOs in the Avalanche ecosystem.
updated: 2024-10-07
authors: [owenwahlgren]
icon: Book
---

In the Avalanche ecosystem and other EVM-compatible networks, Decentralized Autonomous Organizations (DAOs) are pivotal for governance. DAOs operate through smart contracts on the blockchain, enabling decentralized management without centralized leadership. They empower communities to collectively make decisions on protocol upgrades, fund allocations, and other critical governance matters.

### How DAOs Function

DAOs in the Avalanche network govern specific L1s or projects using token-based voting mechanisms. Members hold governance tokens granting them the right to propose initiatives and vote on various issues. The decision-making process is transparent and recorded on the blockchain, ensuring accountability and trust among participants.

For example, a DAO might oversee an L1 dedicated to decentralized finance (DeFi) applications. DAO members can vote on proposals related to L1 upgrades, fee structures, or partnership integrations. By distributing governance tokens to participants, the DAO ensures that contributors have a say in the network’s direction.

Please reference OpenZeppelin's Governance contracts for more information on how DAOs can be implemented: [OpenZeppelin Contracts](https://docs.openzeppelin.com/contracts/4.x/api/governance).
### Benefits of DAOs in Governance

- **Decentralization**: Eliminates the need for centralized authorities, reducing risks of single points of failure and corruption. Decision-making power is distributed among token holders, aligning actions with the community’s interests.
- **Transparency**: All proposals, votes, and decisions are recorded on the blockchain, providing an immutable and transparent governance record. This openness fosters trust and encourages active participation.
- **Efficiency**: Smart contracts automate many governance aspects, such as vote tallying and proposal execution. Automation reduces human error and accelerates decision-making.
- **Inclusivity**: By allowing anyone with governance tokens to participate, DAOs promote inclusivity and democratize organizational control. Broad participation can lead to diverse perspectives and innovative solutions.

### DAOs and Tokenomics

DAOs significantly impact the tokenomics of Avalanche and other EVM networks. Governance tokens often have utility beyond voting rights, including staking rewards or fee reductions. This dual utility incentivizes holding and using the tokens, contributing to the network’s economic health.

Additionally, DAOs can manage treasuries funded by network fees or token issuance. These funds can be allocated to development initiatives, marketing efforts, or community grants, as decided by DAO members. Financial autonomy enables DAOs to invest directly in the growth and sustainability of their networks.

### Challenges and Considerations

While DAOs offer numerous benefits, they also face challenges:

- **Governance Participation**: Ensuring active participation can be difficult, as some token holders may be passive investors. Low voter turnout can lead to decisions not reflecting the broader community’s interests.
- **Security Risks**: Smart contract vulnerabilities pose significant risks. Exploits or bugs in governance contracts can lead to loss of funds or manipulation of voting outcomes.
- **Regulatory Uncertainty**: The legal status of DAOs is evolving in many jurisdictions. Regulatory actions could impact their operation and recognition, affecting functionality.

### Real-World Examples in the Avalanche Ecosystem
- **Avalanche Ambassador DAO**: A group of proven projects from the Avalanche ecosystem that want to partner with the Ambassador DAO and support the Avalanche Community. These projects can create exclusive paid bounties for ambassadors to complete. Ambassadors will get opportunities to contribute and collaborate with these projects and the projects will get access to a global network of ambassadors.
- **DeFi Protocol DAOs**: Projects building on Avalanche establish DAOs to manage protocol parameters like interest rates, collateral requirements, and reward distributions.
- **Community DAOs**: Focus on community initiatives, funding educational content, organizing events, and promoting Avalanche technologies. The Avalanche Ambassador DAO is an example of a community-driven initiative.

### The Role of DAOs in Future Governance

As the Avalanche network grows, DAOs will likely become increasingly important in governance. They offer a scalable and flexible framework for managing complex decentralized systems. By empowering communities to self-govern, DAOs contribute to the resilience, adaptability, and inclusivity of blockchain networks.

In the context of Avalanche Layer 1 (L1) tokenomics, DAOs exemplify how decentralized governance models can effectively manage resources, drive innovation, and align diverse stakeholder interests. Understanding and participating in DAOs allows individuals to influence the network’s evolution and contribute to its long-term success.


<Quiz quizId="215"/>

# Quadratic Voting (/academy/l1-native-tokenomics/08-governance/04-quadratic-voting)

---
title: Quadratic Voting
description: Enter description
updated: 2024-10-07
authors: [owenwahlgren]
icon: Book
---

### Quadratic Voting

Quadratic voting is a governance mechanism designed to achieve a more equitable and democratic decision-making process by allowing participants to express the intensity of their preferences. In the context of the Avalanche network and other EVM-compatible platforms, quadratic voting helps balance the influence between large and small token holders, mitigating the dominance of wealthy participants and promoting fairness.

#### How Quadratic Voting Works

In traditional token-based voting systems, each token typically equates to one vote, which can lead to disproportionate influence by large token holders. Quadratic voting addresses this imbalance by making the cost of casting multiple votes increase quadratically. This means that the cost of an individual's votes is the square of the number of votes they cast.

For example:

- Casting 1 vote costs 1 credit.
- Casting 2 votes costs 4 credits.
- Casting 3 votes costs 9 credits.
- Casting 4 votes costs 16 credits.

This system ensures that casting a large number of votes becomes progressively more expensive, discouraging any single participant from overwhelming the voting process. It allows individuals to allocate their voting power more strategically, focusing on issues they care about most.

#### Implementation in Avalanche Governance

Quadratic voting can be integrated into an L1's governance models to enhance democratic participation. By adjusting the voting mechanisms in DAOs or other governance frameworks to support quadratic voting, the network can:

- **Promote Inclusivity**: Smaller token holders gain a more significant voice in governance decisions, ensuring that the network's direction reflects a broader range of perspectives.
- **Encourage Thoughtful Voting**: Participants must consider the cost of casting multiple votes, leading to more deliberate and meaningful voting behavior.
- **Reduce Plutocracy Risks**: By limiting the disproportionate influence of large token holders, quadratic voting helps prevent the concentration of power and promotes a healthier governance ecosystem.

#### Benefits of Quadratic Voting

- **Fair Representation**: Balances the influence among participants, providing a fairer representation of the community's preferences.
- **Preference Intensity**: Allows participants to express how strongly they feel about specific issues, not just whether they support or oppose them.
- **Enhanced Collaboration**: Encourages dialogue and cooperation among stakeholders, as consensus becomes more valuable than sheer voting power.

#### Challenges and Considerations

While quadratic voting offers significant advantages, there are challenges to consider:

- **Sybil Attacks**: Participants might attempt to create multiple identities to circumvent the quadratic cost. Implementing identity verification or staking mechanisms can mitigate this risk.
- **Complexity**: The quadratic voting system is more complex than traditional voting methods, which may require additional education and user-friendly interfaces to ensure broad adoption.
- **Economic Barriers**: Although quadratic costs balance influence, participants with more resources still have an advantage. Careful calibration of the cost functions and possible subsidies for smaller holders can help address this issue.

#### Real-World Examples in the Avalanche Ecosystem

Quadratic voting is gaining traction in decentralized governance. While its adoption in Avalanche is still emerging, projects can look to examples like:

- **Gitcoin Grants**: Uses quadratic funding, a concept related to quadratic voting, to allocate funds to public goods based on community support.
- **Democracy Earth**: An organization advocating for decentralized, blockchain-based governance systems utilizing quadratic voting to enhance democratic processes.

By learning from these implementations, Avalanche projects can design governance models that incorporate quadratic voting to achieve more equitable outcomes.

### The Role of Quadratic Voting in Avalanche Governance

Quadratic voting represents a significant step towards more democratic and fair governance within the Avalanche ecosystem. By empowering participants to express the strength of their preferences without allowing wealth to dominate the decision-making process, quadratic voting aligns with the principles of decentralization and community-driven development.

Incorporating quadratic voting into Avalanche's governance structures can:

- **Strengthen Community Engagement**: Encourages broader participation by making individual votes more impactful.
- **Improve Decision Quality**: Reflects the true intensity of community sentiments, leading to decisions that better serve the network's interests.
- **Enhance Network Resilience**: Diversifies governance influence, reducing the risk of centralized control and increasing the network's adaptability.

As an L1 continues to evolve, embracing innovative governance mechanisms like quadratic voting will be essential for fostering a vibrant, inclusive, and sustainable ecosystem.


# Governance 2.0 (/academy/l1-native-tokenomics/08-governance/05-governance-20)

---
title: Governance 2.0
description: Learn about the evolution of blockchain governance models.
updated: 2024-10-07
authors: [owenwahlgren]
icon: Book
---

Governance 2.0 represents the evolution of blockchain governance models, aiming to address the limitations of earlier systems and enhance the efficiency, inclusivity, and adaptability of decentralized networks like Avalanche. By integrating innovative mechanisms and technologies, Governance 2.0 seeks to create more robust and responsive governance structures that better align with the needs of the community.

---

## Key Features of Governance 2.0

### Dynamic Participation Incentives

Governance 2.0 models implement incentive structures that reward active engagement. This may include:

- **Staking Rewards**: Earning rewards for participating in voting processes.
- **Reputation Systems**: Recognizing valuable contributions to the network.
- **Aligned Tokenomics**: Aligning individual incentives with the network's success.

### Flexible Governance Frameworks

These models prioritize adaptability, allowing governance structures to evolve as the network grows and community needs change. Modular governance components can be updated or replaced without overhauling the entire system, enabling continuous improvement.

### Enhanced Transparency and Accountability

Advanced smart contract capabilities provide greater transparency in decision-making processes. All proposals, votes, and outcomes are recorded on the blockchain, allowing participants to audit and verify governance activities, which fosters trust and accountability.

### Improved Security Measures

Governance 2.0 incorporates robust safeguards against attacks and exploits, including:

- **Time-Locked Contracts**: Preventing sudden changes without community consensus.
- **Multi-Signature Requirements**: Ensuring multiple approvals for executing decisions.
- **On-Chain Audits**: Detecting and addressing vulnerabilities promptly.

### Integration of Off-Chain Inputs

By bridging on-chain governance with off-chain data and processes, Governance 2.0 allows for more informed decision-making. Oracle systems can feed relevant external information into governance proposals, enhancing the quality and relevance of decisions.

---

## Governance 2.0 in the Avalanche Ecosystem

Avalanche is at the forefront of implementing Governance 2.0 principles, leveraging its high-performance infrastructure and customizable L1s. Key developments include:

### Customizable L1 Governance

Avalanche allows each L1 to adopt its own Governance 2.0 model, tailoring governance mechanisms to the specific needs of its community. This flexibility enables experimentation with innovative governance features and the adoption of best practices across the ecosystem.

### Advanced Voting Mechanisms

The network is exploring and implementing advanced voting systems like:

- **Conviction Voting**: Allowing participants to express the strength of their support.
- **Holographic Consensus**: Balancing proposal visibility with decision-making efficiency.

These mechanisms aim to improve the expressiveness and effectiveness of governance decisions.

### Interoperability and Cross-Chain Governance

Governance 2.0 on Avalanche supports interoperability, enabling coordinated governance across multiple L1s and chains. This interconnectedness enhances collaboration and resource sharing, strengthening the overall ecosystem.

---

## Benefits of Governance 2.0

### Increased Engagement

By providing meaningful incentives and more accessible governance tools, Governance 2.0 encourages higher levels of participation from a diverse range of stakeholders. This leads to decisions that better reflect the community's collective will.

### Adaptive Decision-Making

The flexible nature of Governance 2.0 allows networks to adapt quickly to changing conditions. Whether responding to technological advancements, regulatory shifts, or evolving user needs, these governance models enable timely and effective responses.

### Strengthened Network Resilience

Enhanced security measures and dynamic governance structures reduce vulnerabilities. By mitigating risks of centralization and governance attacks, Governance 2.0 contributes to a more robust and secure network.

### Alignment of Interests

Integrating mechanisms that align individual incentives with the network's success fosters a cooperative environment. Participants are more likely to act in the network's best interest when their own success is directly tied to it.

---

## Challenges and Considerations

While Governance 2.0 offers significant advancements, it also presents challenges:

### Complexity Management

More sophisticated governance models can be complex, potentially creating barriers to understanding and participation. Simplifying user interfaces and providing educational resources are essential to ensure broad community engagement.

### Regulatory Compliance

As governance models become more advanced, they may face increased regulatory scrutiny. Balancing compliance with the principles of decentralization requires careful design and ongoing dialogue with regulatory bodies.

### Scalability

Implementing advanced governance features at scale demands efficient infrastructure. Avalanche's high-throughput capabilities position it well to address scalability concerns, but continuous optimization is necessary as the network grows.

---

## Future Directions

The evolution of Governance 2.0 is an ongoing process. Future developments may include:

### Integration of Artificial Intelligence

Utilizing AI to analyze proposals and predict outcomes could enhance decision-making processes, providing insights that inform more strategic governance actions.

### Cross-Network Governance

As interoperability between different blockchain networks increases, Governance 2.0 models may facilitate governance that spans multiple platforms, promoting broader collaboration.

### Enhanced Privacy Features

Balancing transparency with privacy, future governance models might incorporate zero-knowledge proofs or other cryptographic techniques to protect participant identities while ensuring accountability.

---

## Conclusion

Governance 2.0 represents a significant advancement in how decentralized networks like Avalanche manage decision-making processes. By embracing innovation, enhancing inclusivity, and prioritizing adaptability, these governance models address the shortcomings of earlier systems and set the stage for a more resilient and dynamic blockchain ecosystem.

As your Layer 1 network continues to grow and evolve, implementing Governance 2.0 principles will be crucial for maintaining its competitive edge and ensuring that it meets the needs of its diverse and expanding community. Engaging with these advanced governance models allows participants to directly influence the network's trajectory and contribute to its long-term success.

In the following sections, we will explore specific case studies and practical implementations of Governance 2.0 within the Avalanche ecosystem, highlighting its impact on network governance and community engagement.

# Getting Started with Interchain Token Transfer (/academy/interchain-token-transfer/02-getting-started/01-introduction)

---
title: Getting Started with Interchain Token Transfer
description: Learn how to use our Interchain Token Transfer toolbox to transfer assets across Avalanche chains.
updated: 2024-05-31
authors: [ashucoder9, 0xstt]
icon: Smile
---

# Getting Started with Interchain Token Transfer

In this section, we'll help you get started with our Interchain Token Transfer toolbox. We've made it easier than ever to transfer assets across Avalanche chains by providing a user-friendly interface that handles all the complexity for you.

## Prerequisites

Before you begin, make sure you have:

1. A modern web browser with Core Wallet installed
   - Download Core Wallet from [core.app](https://core.app)
   - Create or import your wallet
   - Add the following testnet chains to your wallet:
     - Fuji C-Chain****
     - Echo
     - Dispatch

2. Test tokens for development
   - **Recommended:** Create a [Builder Hub account](https://build.avax.network/login) and connect your wallet to receive testnet tokens automatically
   - **Alternative:** Get test AVAX from external faucets like [core.app/tools/testnet-faucet](https://core.app/tools/testnet-faucet/?subnet=c&token=c) with code `avalanche-academy`

3. Basic understanding of how to use Core Wallet
   - Adding networks
   - Managing accounts
   - Approving transactions

4. An understanding of Avalanche networks and how to connect to them

<Callout type="warning">
This course focuses on using the existing testnet chains (Fuji C-Chain, Echo, and Dispatch). If you want to create your own L1 blockchain, please refer to the [Creating an L1](/academy/avalanche-fundamentals/04-creating-an-l1/01-creating-an-l1) course.

Since Interchain Token Transfer relies on Interchain Messaging (ICM), you must run your own relayer to enable cross-chain communication. Follow the [Running a Relayer](/academy/interchain-messaging/10-running-a-relayer/01-running-a-relayer) course to set up your relayer.
</Callout>

## Using the Interchain Token Transfer Toolbox

Our Interchain Token Transfer toolbox is a comprehensive web application that provides a complete suite of tools for cross-chain operations. Here's how to get started:

1. Visit the [Interchain Token Transfer Toolbox](https://toolbox.avax.network/interchain-transfer)

2. Connect your wallet:
   - Click the "Connect Wallet" button
   - Select Core Wallet
   - Approve the connection request

3. Explore the toolbox features:

   a. Deploy Contracts:
   - Deploy new ERC-20 tokens
   - Create bridge contracts
   - Set up token bridges

   b. Transfer Assets:
   - Select the source and destination chains (Fuji C-Chain, Echo, or Dispatch)
   - Choose the token and amount
   - Execute cross-chain transfers

   c. Test Transfers:
   - Use the test transfer feature to verify your setup
   - Monitor transfer status
   - View transaction history

## Features

Our toolbox provides several features to help you with cross-chain operations:

- Contract Deployment:
  - ERC-20 token deployment
  - Bridge contract creation
  - Token bridge setup

- Asset Transfers:
  - Support for testnet chains (Fuji C-Chain, Echo, Dispatch)
  - ERC-20 token transfers
  - Native token transfers
  - Cross-chain token swaps

- Testing and Monitoring:
  - Test transfer functionality
  - Transaction history
  - Real-time status updates
  - Cross-chain transaction tracking

## Next Steps

Now that you know how to use the Interchain Token Transfer toolbox, you can:

1. Learn about different token types in the next section
2. Explore token bridging concepts
3. Try out different types of cross-chain transfers
4. Deploy your own tokens and bridges
5. Test your cross-chain setup

Remember that our toolbox handles all the complex interactions with the Interchain Token Transfer protocol, so you can focus on your cross-chain operations without worrying about the technical details. 

# Tokens (/academy/interchain-token-transfer/03-tokens/01-tokens)

---
title: Tokens
description: Learn about tokens
updated: 2024-05-31
authors: [martineckardt]
icon: Book
---

## What You Will Learn

In this section, you will go through the following topics:

- **What is a token**: Learn how tokens serve to represent ownership.
- **Types of tokens**: Learn about ERC20 tokens, Native tokens and Wrapped tokens.
- **Transfers**: Learn differences on transfering the different types of tokens between accounts or with smart contracts.


# Native Tokens (/academy/interchain-token-transfer/03-tokens/02-native-tokens)

---
title: Native Tokens
description: Understand the native token role in a blockchain system
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

A native token in a blockchain running the Ethereum Virtual Machine (EVM) refers to the primary digital currency or cryptocurrency native to the EVM blockchain. Every EVM layer 1 chain has it's own native token:

- Ethereum: ETH
- Avalanche C-Chain: AVAX
- Dexalot: ALOT
- many more...

The native token serves as both a means of value transfer within the EVM network and as the gas token for executing transfers or smart contracts. Therefore, native tokens play a crucial role in the EVM chain by enabling participants to interact with and utilize the platform's decentralized features, serving as the foundational unit of value.
<Quiz quizId="118" />

# Transfer Native Tokens (/academy/interchain-token-transfer/03-tokens/03-transfer-native-tokens)

---
title: Transfer Native Tokens
description: Learn how to transfer native tokens using Core Wallet
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

In this exercise, you will learn how to transfer native tokens (AVAX) between accounts using Core Wallet. We'll demonstrate this using the Fuji testnet.

<Steps>
<Step>

## Open Core Wallet

First, make sure you have Core Wallet installed. If you don't have Core Wallet installed already, click the Download Core Wallet button below.

<ToolboxMdxWrapper />

</Step>
<Step>

## Switch to Fuji Testnet

<ToolboxMdxWrapper enforceChainId={43113} />

</Step>
<Step>

## Get Test AVAX

Before transferring tokens, ensure you have some test AVAX:

**Option 1 (Recommended):** Create a [Builder Hub account](https://build.avax.network/login) and connect your wallet to receive testnet AVAX automatically on the C-Chain.

**Option 2:** Use the external [Avalanche Faucet](https://core.app/tools/testnet-faucet/?subnet=c&token=c) with coupon code `avalanche-academy25` to claim AVAX tokens on the C-Chain of the Fuji testnet.

</Step>
<Step>

## Transfer AVAX

To transfer AVAX to another address:

1. Click the "Send" button in Core Wallet
2. Enter the recipient's address
3. Enter the amount of AVAX to send
4. Review the transaction details
5. Click "Send" to confirm

</Step>
<Step>

## Verify the Transfer

To verify the transfer was successful:

1. Check the transaction status in Core Wallet
2. View the transaction details on the [Fuji Explorer](https://testnet.snowtrace.io)
3. The recipient can check their balance in their Core Wallet

</Step>
</Steps>

<Callout>
Remember that you need to have enough AVAX in your wallet to cover both the transfer amount and the gas fees. Always double-check the recipient address before sending to avoid any loss of funds.
</Callout>

Now that you know how to transfer native tokens, you can proceed to learn about transferring ERC-20 tokens in the next section.


# Transfers and Smart Contract (/academy/interchain-token-transfer/03-tokens/05-transfers-in-smart-contracts)

---
title: Transfers and Smart Contract
description: Transfer native tokens to smart contracts
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---
import { Step, Steps } from 'fumadocs-ui/components/steps';


Now that you know how to transfer native assets between accounts, let's see how to to transfer those funds to the control of an smart contract. Payable smart contract functions are essential for this process, as they allow the contract to receive Native Tokens. A function marked as payable in Solidity signifies that the function can accept and process incoming funds. This is particularly useful for contracts that need to handle funds for instance any financial dApps, such as decentralized applications (dApps), automated market makers (AMMs), or transfering funds from one chain to another, like we do with Avalanche Interchain Token Transfer. 

## Payable functions

The `payable` keyword in Solidity is used to designate functions that are capable of receiving native blockchain tokens. When a function is marked as payable, it allows the contract to accept incoming funds and execute specific logic based on the amount received. Without the payable modifier, any attempt to send native tokens to a contract would result in an error, preventing the transaction from being processed.

A function defined as payable serves multiple purposes. First, it signals to users and other contracts that the function is intended to handle incoming payments. This adds a layer of transparency and ensures that the contract’s behavior is clear and predictable. Second, it allows the function to access special variables such as msg.value, which holds the amount of Ether sent with the call. This can be used within the function to implement various logic, such as recording payments, issuing tokens in return, or triggering other contract behaviors.

Here's an example of a simple payable function in Solidity:

```solidity 
pragma solidity ^0.8.0;

contract PayableExample {
    uint public amountReceived = 0 ;

    function receiveNative() public payable {
        amountReceived += msg.value;
    }
}
```
In this example, the receiveNative function is marked as payable, enabling it to accept the Native Token. The msg.value variable is used to add the amount of native token sent to the amountReceived state variable. This is a basic illustration, but it underscores how the payable keyword facilitates the handling of native token transfers within smart contracts.

<Steps>

<Step>
### Create the working directory to store new contracts

```bash
mkdir -p src/my-contracts
```
</Step>

<Step>
### Copy the above example contract into `/src/my-contracts/PayableExample.sol`
</Step>

<Step>

### Deploy Contract with Payable Function

```bash
forge create --rpc-url myblockchain --private-key $PK src/my-contracts/PayableExample.sol:PayableExample --broadcast
```

</Step>
<Step>

### Save the Contract Address

```bash
export PAYABLE_CONTRACT=0X..

```

</Step>
<Step>

### Check `amountReceived`

```bash
cast call --rpc-url myblockchain $PAYABLE_CONTRACT "amountReceived()(uint)"
```

</Step>
<Step>

### Transfer Native Token to the Contract

Now let's use solidity to transfer funds to our PayableExample contract

```bash
cast send --rpc-url myblockchain --private-key $PK $PAYABLE_CONTRACT "receiveNative()" --value 100000
```

</Step>
<Step>

### Check `amountReceived`
```bash
cast call --rpc-url myblockchain $PAYABLE_CONTRACT "amountReceived()(uint)"
```

</Step>
</Steps>

Well done! You transferred native tokens to a Smart Contract.

It's important to understand the distinction between Native Tokens and ERC-20 tokens. Native tokens, such as `AVAX` or `ETH`, are transferred directly to payable functions within the smart contract. This process is straightforward and involves sending the tokens to the contract's address, invoking the payable function. 

On the other hand, ERC-20 tokens require a different approach due to their standardized interface. We will cover that in the following sections.

<Quiz quizId="119" />


# ERC-20 Tokens (/academy/interchain-token-transfer/03-tokens/07-erc-20-tokens)

---
title: ERC-20 Tokens
description: Learn about ERC-20 Standard for tokens
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

There is only a single native token to a chain. However, to allow to represent a wide range of assets on EVM-chains, the ERC-20 token standard was developed. "ERC" stands for Ethereum Request for Comment, and "20" is the proposal identifier.

ERC-20 tokens are fungible, meaning each token is identical and can be exchanged on a one-to-one basis. These tokens are typically created and managed through smart contracts that adhere to the ERC-20 standard, which defines a set of rules and functions that ensure interoperability between different tokens and decentralized applications (DApps). 

At the base of an ERC-20 token smart contract, there is a simple mapping of addresses to numbers, which represent the amount of tokens an address holds (balance). 

```solidity
abstract contract ERC20 is Context, IERC20, IERC20Metadata, IERC20Errors {
    
  mapping(address account => uint256) private _balances;
	
  //...
}
```
These addresses may belong to EOA or contract accounts. Both of these can hold and transfer ERC-20 tokens. 

ERC-20 tokens can represent various assets, from digital currencies to tokenized assets, and they play a crucial role in the crypto ecosystem by enabling the creation of decentralized applications with diverse functionalities, such as token sales, decentralized finance (DeFi) protocols, and more.

## Interface

To maintain compatibility with dApps designed to work with the ERC20 standard, all ERC20 tokens implement the following interface:

```solidity
interface IERC20 {

    function name() external view returns (string memory);

    function symbol() external view returns (string memory);

    function decimals() external view returns (uint8);

    function totalSupply() external view returns (uint256);

    function balanceOf(address _owner) external view returns (uint256 balance);

    function transfer(address _to, uint256 _value) external returns (bool success);

    function transferFrom(address _from, address _to, uint256 _value) external returns (bool success);

    function approve(address _spender, uint256 _value) external returns (bool success);

    function allowance(address _owner, address _spender) external view returns (uint256 remaining);
}
```
Click [here](https://eips.ethereum.org/EIPS/eip-20) to review the ERC20 standard in full detail.

## Transfer Tokens

Transferring ERC-20 tokens between accounts involves calling the 'transfer' function, specifying the recipient’s address and the amount to transfer. 

To facilitate more complex interactions, such as those involving smart contracts, the ERC-20 standard includes the `approve()` and `transferFrom()` functions. We will check how to implement those so smart contracts can use funds according to its code.

### `approve()`

Since all balances are just a mapping of amount values to addresses, the owner of each address can 'approve' some other account as a _spender of their funds up to some limit determined by the approved _amount. The spender then will be able to withdraw from your account multiple times, up to the value set in amount.

### `allowance()`

Returns the amount which _spender is still allowed to withdraw from _owner.

### `transferFrom()`

Transfers _value amount of tokens from address _from to address _to


<Quiz quizId="120" />


# Deploy and Transfer an ERC-20 Token (/academy/interchain-token-transfer/03-tokens/08-transfer-an-erc-20-token)

---
title: Deploy and Transfer an ERC-20 Token
description: Transfer an ERC-20 token between accounts
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

<Steps>
<Step>

### Deploy ERC-20

Let's deploy a basic demo ERC20 token on the Fuji testnet using our toolbox.

<ToolboxMdxWrapper>
    <DeployExampleERC20 />
</ToolboxMdxWrapper>

</Step>
<Step>

### Add Token to Core Wallet

After deploying your ERC-20 token:

1. Open Core Wallet
2. Go to the Tokens tab
3. Click "Manage"
4. Click "+ Add Custom Token"
5. Enter the token contract address from the deployment
6. The token symbol and decimals should be automatically detected
7. Click "Add Token"

<Callout>
Make sure you're connected to the Fuji testnet when adding the token. The token will only be visible on the network where it was deployed.
</Callout>

</Step>
<Step>

### Transfer ERC-20 Token

To transfer your ERC-20 token:

1. In Core Wallet, select your token from the token list
2. Click "Send"
3. Enter the recipient's address
4. Enter the amount to transfer
5. Review the transaction details
6. Click "Send" to confirm

<Callout>
Always double-check the recipient address before sending. ERC-20 transfers cannot be reversed once confirmed.
</Callout>

</Step>
<Step>

### Verify Transfer

To verify the transfer was successful:

1. Check the transaction status in Core Wallet
2. View the transaction details on the [Fuji Explorer](https://testnet.snowtrace.io)
3. The recipient can add the token to their Core Wallet to see their balance

<Callout>
If the recipient doesn't see the token in their wallet, they'll need to add it using the token contract address, just like you did in step 2.
</Callout>

</Step>
</Steps>

Now that you know how to deploy and transfer ERC-20 tokens, you can proceed to learn about token bridging in the next section.

# ERC-20 and Smart Contracts (/academy/interchain-token-transfer/03-tokens/09-transfer-erc20-to-sc)

---
title: ERC-20 and Smart Contracts
description: Transfer an ERC-20 Token to a smart contracts
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---
import { Step, Steps } from 'fumadocs-ui/components/steps';


Transferring ERC-20 tokens to a smart contract involves a few steps, including setting an allowance and then using the transferFrom function to move the tokens. This process ensures that the smart contract can only withdraw the amount of tokens you've explicitly approved.

First, let's look at the necessary code to achieve this. We'll use the same basic ERC-20 token contract that we used previously. 

<Steps>
<Step>

## Create Smart Contract Receiving an ERC20

We need a smart contract that will receive the tokens:

```solidity 
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;
import "@openzeppelin/contracts@4.8.1/token/ERC20/IERC20.sol";

contract TokenReceiver {
    IERC20 public token;

    constructor(address tokenAddress) {
        token = IERC20(tokenAddress);
    }

    function receiveTokens(address from, uint256 amount) public {
        require(token.transferFrom(from, address(this), amount), "Transfer failed");
    }
}
```

In this contract, the `receiveTokens` function allows the contract to receive tokens from a specified address. It uses the transferFrom function of the ERC-20 token standard.

Copy this code into a new file `src/my-contracts/TokenReceiver.sol`

</Step>
<Step>

### Deploy ERC20 Receiver
Let's deploy this ERC20receiver contract

```bash
forge create --rpc-url myblockchain --private-key $PK --broadcast --constructor-args $ERC20_CONTRACT_L1 src/my-contracts/TokenReceiver.sol:TokenReceiver
```

```
[⠊] Compiling...
No files changed, compilation skipped
Deployer: 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC
Deployed to: 0x4Ac1d98D9cEF99EC6546dEd4Bd550b0b287aaD6D
Transaction hash: 0x31b45c9df0a823254fd51863e217801da809cc77915a7b2901ea348c74aa0cfe
```
</Step>
<Step>

### Save Receiver Address
<Callout title="Note" type="info">
The address `0x4Ac1d98D9cEF99EC6546dEd4Bd550b0b287aaD6D` is your receiver contract address.
</Callout>

```bash
export ERC20_RECEIVER_L1=0x...
```

</Step>
<Step>

### Approve Token Expense

Now to send Tokens to that contract, the Receiver contracts needs to be allowed to take funds on behalf of the user. Therefore, we need to allow our receiver contract as spender on the TOK interface.

```bash
cast send $ERC20_CONTRACT_L1 --private-key $PK "approve(address,uint256)" $ERC20_RECEIVER_L1 20ether --rpc-url myblockchain
```

</Step>
<Step>

### Transfer Tokens to Smart Contract

Finally let's transfer tokens to this contract

```bash
cast send $ERC20_RECEIVER_L1 --private-key $PK "receiveTokens(address,uint256)" $EWOQ 2ether --rpc-url myblockchain
```

</Step>
<Step>

### Confirm transfer

```bash
cast call $ERC20_CONTRACT_L1 "balanceOf(address)(uint256)" $ERC20_RECEIVER_L1 --rpc-url myblockchain
```

</Step>
</Steps>

<Quiz quizId="121" />


# Wrapped Native Tokens (/academy/interchain-token-transfer/03-tokens/10-wrapped-native-tokens)

---
title: Wrapped Native Tokens
description: Represent native assets as ERC-20 tokens
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

Native Wrapped Tokens are blockchain assets that represent a native cryptocurrency (AVAX, ALOT, ETH, etc) in a tokenized form that conforms to a specific token standard, typically ERC-20. This wrapping process involves locking the native cryptocurrency in a smart contract and minting an equivalent amount of the wrapped token.

Wrapped tokens retain the value of the underlying native asset by backing those ERC20 representations 1:1 with the native token while gaining compatibility with the ERC-20 token standard. This compatibility is crucial for interoperability within the EVM ecosystem, enabling the use of wrapped tokens in decentralized applications (dApps), decentralized exchanges (DEXs), and smart contracts that require ERC-20 tokens including the **Avalanche Interchain Token Transfer dApp**.

The process of wrapping and unwrapping tokens ensures that users can seamlessly switch between the native asset and its wrapped counterpart, facilitating smooth integration across various DeFi protocols and enhancing liquidity and usability within the blockchain ecosystem.

Examples of Wrapped Tokens: 

- wAVAX
- wETH
- BTC.b (this is not only wrapped, but also bridged to the Avalanche Ecosystem but represented as ERC20 to gain compatibility with the Avalanche C-chain ecosystem.)

<Quiz quizId="122" />


# Create a Wrapped Native Token (/academy/interchain-token-transfer/03-tokens/11-create-a-wrapped-native-token)

---
title: Create a Wrapped Native Token
description: Wrap the native asset of your blockchain
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

Creating a wrapped token contract for NAT (myblockchain's native token) involves writing a smart contract that adheres to the ERC-20 standard. This allows NAT to be used in dApps without the need of creating certain behavior for native assets. Here’s a simple example of such a contract written in Solidity:

```solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

contract WrappedNAT {
    string public name = "Wrapped NAT";
    string public symbol = "WNAT";
    uint8 public decimals = 18;
    uint256 public totalSupply;
    
    mapping(address => uint256) private balances;
    mapping(address => mapping(address => uint256)) private allowances;
    

    receive() external payable {
        deposit();
    }

    function deposit() public payable {
        balances[msg.sender] += msg.value;
        totalSupply += msg.value;
    }

    function withdraw(uint256 amount) public {
        require(balances[msg.sender] >= amount, "Insufficient balance");
        balances[msg.sender] -= amount;
        totalSupply -= amount;
        payable(msg.sender).transfer(amount);
    }

    function balanceOf(address account) public view returns (uint256) {
        return balances[account];
    }

    function transfer(address to, uint256 amount) public returns (bool) {
        require(balances[msg.sender] >= amount, "Insufficient balance");
        balances[msg.sender] -= amount;
        balances[to] += amount;
        return true;
    }

    function approve(address spender, uint256 amount) public returns (bool) {
        allowances[msg.sender][spender] = amount;
        return true;
    }

    function allowance(address owner, address spender) public view returns (uint256) {
        return allowances[owner][spender];
    }

    function transferFrom(address from, address to, uint256 amount) public returns (bool) {
        require(balances[from] >= amount, "Insufficient balance");
        require(allowances[from][msg.sender] >= amount, "Allowance exceeded");
        balances[from] -= amount;
        allowances[from][msg.sender] -= amount;
        balances[to] += amount;
        return true;
    }
}

```



# Token Bridging (/academy/interchain-token-transfer/04-token-bridging/01-token-bridging)

---
title: Token Bridging
description: Learn about asset transfer between chains
updated: 2024-05-31
authors: [ashucoder9]
icon: Book
---

Asset bridging is a crucial concept in blockchain interoperability, enabling assets to be transferred across different blockchain networks. This process is essential for creating seamless experiences in multi-chain ecosystems.

## What You Will Learn

In this section, you will go through the following topics:

- **Bridging assets:** you will understand why bridging assets is important.
- **Bridge safety:** learn about the most common hacks in bridges and how to prevent them.


# Bridge Architecture (/academy/interchain-token-transfer/04-token-bridging/02-bridge-architecture)

---
title: Bridge Architecture
description: Get familiar with different bridge mechanisms
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

Asset bridging refers to the mechanism that allows assets, such as cryptocurrencies or tokens, to move from one blockchain to another. This is particularly important in ecosystems where multiple blockchains are used for different purposes, and users want to leverage assets across these chains. Bridging effectively extends the usability of assets beyond their native blockchain, facilitating greater liquidity and integration across various platforms.

## Bridge Mechanisms

### Lock & Mint

Locking: The asset is locked in a smart contract on the source blockchain. For example, if you want to bridge AVAX from Avalanche's C-chain to Ethereum, you would lock your AVAX in a smart contract on Avalanche.
Minting: Simultaneously, some event notifies Ethereum that an equivalent amount of a wrapped token (e.g., Wrapped AVAX) must be minted on the target blockchain and sent to the user’s address.

### Burn & Mint

Burning: When transferring assets back to the source blockchain, the wrapped tokens are burned or destroyed on the target blockchain.
Releasing: The original assets are then released from the smart contract on the source blockchain back to the user's address.

### Custodians

Some bridges use a custodian or a centralized party to manage the assets. This party locks the asset on one blockchain and releases it on another, relying on trust and security measures.

### Cross-Chain Communication

Advanced bridges such as Avalanche Interchain Token Transfer utilize native cross-chain communication protocols to facilitate transactions between blockchains without requiring intermediaries. These protocols ensure that the asset's state and ownership are synchronized across different chains.

## Why Bridging

- Enhanced Liquidity: Bridging increases the liquidity of assets by allowing them to be used across different DeFi platforms and blockchain networks. This enhances trading opportunities and financial activities.
- Interoperability: It fosters interoperability between different blockchains, enabling users to access a broader range of services and applications.
- Flexibility: Users can move assets to chains with lower fees, faster transaction times, or better functionalities, optimizing their experience and strategies.

<Quiz quizId="123" />


# Use a Demo Bridge (/academy/interchain-token-transfer/04-token-bridging/03-use-a-demo-bridge)

---
title: Use a Demo Bridge
description: Interact with the ohmywarp bridge
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

This guide will walk you through the process of using a bridge between 2 Avalanche blockchains, providing a step-by-step approach to ensure a smooth and secure experience.

Go to [ohmywarp.com](https://ohmywarp.com) and connect any web3 [wallet](https://core.app). Make sure your wallet has at least some AVAX on the Fuji Testnet. 

**Getting testnet AVAX:**
- **Recommended:** Create a [Builder Hub account](https://build.avax.network/login) and connect your wallet to receive testnet AVAX automatically
- **Alternative:** Use the [external faucet](https://core.app/tools/testnet-faucet/?subnet=c&token=c) with coupon code `avalanche-academy`

Mint some `TLP` token on `C-Chain` in the Mint tab. This is an ERC20 deployed on Fuji's C-chain.
Finally bridge some `TLP` to `Dispatch`. You can confirm the transfer in the Mint tab.


# Bridge Hacks (/academy/interchain-token-transfer/04-token-bridging/04-bridge-hacks)

---
title: Bridge Hacks
description: Learn about the most common bridge hacks.
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

## What are Bridge Hacks?

Asset bridges are vital for blockchain interoperability but have been the target of significant security breaches. The complexities of bridging assets between different blockchains can create vulnerabilities that malicious actors exploit. Here’s an overview of some of the most common types of bridge hacks and security issues:

### Smart Contract Exploits

Smart contract exploits involve vulnerabilities in the bridge's code that can be exploited by attackers to steal assets. Common issues include:

**Reentrancy Attacks**: Exploiting a contract’s ability to call itself, allowing attackers to repeatedly withdraw funds before the contract’s state is updated. Example: The DAO hack in 2016 utilized reentrancy to drain millions of dollars of ETH from a smart contract.
  
**Arithmetic Errors**: Bugs related to integer overflows or underflows that can lead to unintended behavior. Example: In 2020, the **Value DeFi** exploit used an arithmetic bug to drain $6 million from the protocol.

**Logic Flaws**: Errors in the contract's logic that can be exploited to bypass security controls. Example: In the case of bZx exploit, an attacker exploited a logic flaw to manipulate the price of assets and steal funds.

### Centralized Bridge Attacks

Centralized bridges rely on a single custodian or entity to manage the assets. If the custodian is compromised, it can lead to:

1. **Theft of Assets**: Direct theft from the custodian's reserves if their security is breached. Example: The Poly Network hack in 2021 involved a vulnerability that allowed attackers to exploit the bridge's central control mechanisms and steal over $600 million. Although much of the stolen funds were later returned, it highlighted significant risks in centralized bridges.

2. **Mismanagement or Fraud**: The custodian could mismanage funds or engage in fraudulent activities. Example: Various cases of mismanagement or fraud in smaller, less established bridges where the custodian's integrity is in question.

### Governance Attacks

Governance attacks target the mechanisms by which decisions are made in decentralized bridges:

**Vote Manipulation**: Attacking the governance process to make changes that benefit the attacker. Example: In some DeFi protocols, attackers have manipulated governance votes to gain control or access to assets.

**51% Attacks**: Gaining control over a majority of the governance or network nodes to disrupt or exploit the bridge. Example: While more common in blockchains, similar attacks can occur in decentralized bridges with weak governance structures.

### Cross-Chain Communication Vulnerabilities

Cross-chain communication vulnerabilities involve weaknesses in the protocols or mechanisms that facilitate communication between different blockchains:

**Data Manipulation**: Exploiting the data transmitted between chains to falsify transactions or asset states. Example: In 2022, the Wormhole bridge was exploited due to a vulnerability in its data verification process, leading to a loss of over $320 million.

**Consensus Issues**: Problems with how different chains agree on the state of assets or transactions can lead to discrepancies and exploitation. Example: Misalignment between chains can lead to double-spending or other issues if not properly managed.

### Phishing and Social Engineering

Phishing and social engineering attacks target users or administrators rather than the bridge’s technical infrastructure:

**Phishing**: Attacking users to steal their private keys or credentials to access funds. Example: Users may be tricked into entering their private keys on fraudulent websites pretending to be bridge interfaces.

**Social Engineering**: Manipulating individuals involved in the bridge’s operations to gain unauthorized access or influence. Example: Administrators may be tricked into giving away critical access or credentials.

## Mitigation Strategies

1. **Audits and Code Reviews**: Regularly audit smart contracts and bridge code to identify and fix vulnerabilities before they can be exploited.

2. **Security Best Practices**: Implement security best practices, including proper error handling, using well-tested libraries, and following coding standards.

3. **Decentralization**: Where possible, use decentralized bridging solutions to reduce the risk associated with centralized custodians.

4. **Governance Safeguards**: Strengthen governance mechanisms and ensure a robust process for decision-making and voting.

5. **User Education**: Educate users about phishing and social engineering threats to reduce the risk of these types of attacks.

6. **Insurance and Compensation**: Use insurance mechanisms or compensation funds to mitigate the impact of potential losses from breaches.

By understanding and addressing these common bridge hacks, developers and users can better protect their assets and improve the overall security of cross-chain bridging solutions.

<Quiz quizId="124" />


# Avalanche Interchain Token Transfer (/academy/interchain-token-transfer/05-avalanche-interchain-token-transfer/01-avalanche-interchain-token-transfer)

---
title: Avalanche Interchain Token Transfer
description: Learn how to transfer assets between Avalanche L1s
updated: 2024-05-31
authors: [ashucoder9]
icon: Book
---

The Avalanche Interchain Token Transfer is an application that allows users to transfer tokens between Avalanche L1s. The bridge is a set of smart contracts that are deployed across multiple Avalanche L1s, and leverages [Interchain Messaging](https://github.com/ava-labs/teleporter) for cross-chain communication.

# What you will learn

In this chapter you will learn:

- **Bridge Design:** How the bridge is designed on a high level.
- **File Structure:** The structure of the bridge contracts and their dependencies.
- **Token Home:** What the token home is and how it works.
- **Token Remote:** What the token remote is and how it works.


# Interchain Token Transfer Design (/academy/interchain-token-transfer/05-avalanche-interchain-token-transfer/02-bridge-design)

---
title: Interchain Token Transfer Design
description: Get familiar with the ICTT design
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

Each token transferrer instance consists of one "home" contract and at least one but possibly many "remote" contracts. Each home contract instance manages one asset to be transferred out to `TokenRemote` instances. The home contract lives on the Avalanche L1 where the asset to be transferred exists.

A transfer involves locking the asset as collateral on the home Avalanche L1 and minting a representation of the asset on the remote Avalanche L1. The remote contracts, each with a single specified home contract, live on other Avalanche L1s that want to import the asset transferred by their specified home.

The token transferrers are designed to be permissionless: anyone can register compatible `TokenRemote` instances to transfer tokens from the `TokenHome` instance to that new `TokenRemote` instance.

The home contract keeps track of token balances transferred to each `TokenRemote` instance and handles returning the original tokens to the user when assets are transferred back to the `TokenHome` instance.

`TokenRemote` instances are registered with their home contract via a Interchain Messaging message upon creation.

Home contract instances specify the asset to be transferred as either an ERC20 token or the native token, and they allow for transferring the token to any registered `TokenRemote` instances. The token representation on the remote chain can also either be an ERC20 or native token, allowing users to have any combination of ERC20 and native tokens between home and remote chains:

- `ERC20` -> `ERC20`
- `ERC20` -> `Native`
- `Native` -> `ERC20`
- `Native` -> `Native`

The remote tokens are designed to have compatibility with the token transferrer on the home chain by default, and they allow custom logic to be implemented in addition. For example, developers can inherit and extend the `ERC20TokenRemote` contract to add additional functionality, such as a custom minting, burning, or transfer logic.

<Quiz quizId="125" />


# File Structure (/academy/interchain-token-transfer/05-avalanche-interchain-token-transfer/03-file-structure)

---
title: File Structure
description: Understand the components of the ICTT structure
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

## Contract Structure

The ERC20 and native token transferrers built on top of Interchain Messaging are composed of interfaces and abstract contracts that make them extendable to new implementations in the future.

### `ITokenTransferrer`

Interface that defines the events token transfer contract implementations must emit. Also defines the message types and formats of messages between all implementations.

### `IERC20TokenTransferrer` and `INativeTokenTransferrer`

Interfaces that define the external functions for interacting with token transfer contract implementations of each type. ERC20 and native token transferrer interfaces vary from each other in that the native token transferrer functions are `payable` and do not take an explicit amount parameter (it is implied by `msg.value`), while the ERC20 token transferrer functions are not `payable` and require the explicit amount parameter. Otherwise, they include the same functions.

# Token Home (/academy/interchain-token-transfer/05-avalanche-interchain-token-transfer/04-token-home)

---
title: Token Home
description: Learn about the Token Home, the asset origin component of the ICTT
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

## `TokenHome`

An abstract implementation of `ITokenTransferrer` for a token transfer contract on the "home" chain with the asset to be transferred. Each `TokenHome` instance supports transferring exactly one token type (ERC20 or native) on its chain to arbitrarily many "remote" instances on other chains.

It handles locking tokens to be sent to `TokenRemote` instances, as well as receiving token transfer messages to either redeem tokens it holds as collateral (i.e. unlock) or route them to other `TokenRemote` instances (i.e. "multi-hop").

In the case of a multi-hop transfer, the `TokenHome` already has the collateral locked from when the tokens were originally transferred to the first `TokenRemote` instance, so it simply updates the accounting of the transferred balances to each respective `TokenRemote` instance.

Remote contracts must first be registered with a `TokenHome` instance before the home contract will allow for sending tokens to them. This is to prevent tokens from being transferred to invalid remote addresses.

Anyone is able to deploy and register remote contracts, which may have been modified from this repository. It is the responsibility of the users of the home contract to independently evaluate each remote for its security and correctness.

### `ERC20TokenHome`

A concrete implementation of `TokenHome` and `IERC20TokenTransferrer` that handles the locking and releasing of an ERC20 token.

### `NativeTokenHome`

A concrete implementation of `TokenHome` and `INativeTokenTransferrer` that handles the locking and release of the native EVM asset.


# Token Remote (/academy/interchain-token-transfer/05-avalanche-interchain-token-transfer/05-token-remote)

---
title: Token Remote
description: Learn about the Token Remote, the asset destination component of the ICTT
updated: 2024-05-31
authors: [ashucoder9]
icon: BookOpen
---

## `TokenRemote`

An abstract implementation of `ITokenTransferrer` for a token transfer contract on a "remote" chain that receives transferred assets from a specific `TokenHome` instance. Each `TokenRemote` instance has a single `TokenHome` instance that it receives token transfers from to mint tokens. It also handles sending messages (and correspondingly burning tokens) to route tokens back to other chains (either its `TokenHome`, or other `TokenRemote` instances).

Once deployed, a `TokenRemote` instance must be registered with its specified `TokenHome` contract. This is done by calling `registerWithHome` on the remote contract, which will send a Interchain Messaging message to the home contract with the information to register.

All messages sent by `TokenRemote` instances are sent to the specified `TokenHome` contract, whether they are to redeem the collateral from the `TokenHome` instance or route the tokens to another `TokenRemote` instance.

Routing tokens from one `TokenRemote` instance to another is referred to as a "multi-hop", where the tokens are first sent back to their `TokenHome` contract to update its accounting, and then automatically routed on to their intended destination `TokenRemote` instance.

TokenRemote contracts allow for scaling token amounts, which should be used when the remote asset has a higher or lower denomination than the home asset, such as allowing for a ERC20 home asset with a denomination of 6 to be used as the native EVM asset on a remote chain (with a denomination of 18).

### `ERC20TokenRemote`

A concrete implementation of `TokenRemote`, `IERC20TokenTransferrer`, and `IERC20` that handles the minting and burning of an ERC20 asset. Note that the `ERC20TokenRemote` contract is an ERC20 implementation itself, which is why it takes the `tokenName`, `tokenSymbol`, and `tokenDecimals` in its constructor.

All of the ERC20 interface implementations are inherited from the standard OpenZeppelin ERC20 implementation and can be overridden in other implementations if desired.

### `NativeTokenRemote`

A concrete implementation of `TokenRemote`, `INativeTokenTransferrer`, and `IWrappedNativeToken` that handles the minting and burning of the native EVM asset on its chain using the native minter precompile.

Deployments of this contract must be permitted to mint native coins in the chain's configuration. Note that the `NativeTokenRemote` is also an implementation of `IWrappedNativeToken` itself, which is why the `nativeAssetSymbol` must be provided in its constructor.

`NativeTokenRemote` instances always have a denomination of 18, which is the denomination of the native asset of EVM chains. We will cover Native Token Remote in depth later in the course.

# ERC-20 to ERC-20 Bridge (/academy/interchain-token-transfer/06-erc-20-to-erc-20-bridge/01-erc-20-to-erc-20-bridge)

---
title: ERC-20 to ERC-20 Bridge
description: Transfer ERC-20 tokens between Avalanche L1s
updated: 2024-05-31
authors: [ashucoder9]
icon: Book
---
import { Step, Steps } from 'fumadocs-ui/components/steps';
import Link from 'next/link';
import { buttonVariants } from '@/components/ui/button.tsx'

## Transfer an ERC-20 Token &rarr; Echo as an ERC-20 Token

This chapter will show you how to send an ERC-20 Token from C-Chain to Echo using Interchain Messaging and Toolbox. This guide is conducted on the Fuji testnet, where we'll bridge tokens from C-Chain to Echo.

**All Avalanche Interchain Token Transfer contracts and interfaces implemented in this chapter implementation are maintained in the [`avalanche-interchain-token-transfer`](https://github.com/ava-labs/avalanche-interchain-token-transfer/tree/main/contracts/src) repository.**

Deep dives on each template interface can be found [here](https://github.com/ava-labs/avalanche-interchain-token-transfer/blob/main/contracts/README.md).

_Disclaimer: The avalanche-interchain-token-transfer contracts used in this tutorial are under active development and are not yet intended for production deployments. Use at your own risk._

## What we will do

1. Deploy an ERC-20 Contract on C-Chain
2. Deploy the Interchain Token Transferer Contracts on C-Chain and Echo
3. Register Remote Token contract with the Home Transferer contract
4. Add Collateral and Start Sending Tokens






# Deploy an ERC-20 (/academy/interchain-token-transfer/06-erc-20-to-erc-20-bridge/02-deploy-erc-20-token)

---
title: Deploy an ERC-20 
description: Deploy the asset to transfer
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

<Steps>
<Step>

### Deploy an ERC-20 Token

We've already deployed an ERC-20 token in the [Transfer an ERC-20 Token](/academy/interchain-token-transfer/03-tokens/08-transfer-an-erc-20-token) section. If you've completed that step, you can use the same token for this bridge.

If you haven't deployed a token yet, make sure you're connected to the Fuji testnet since we're covering this guide from Fuji to Echo. You can deploy the original ERC-20 token below:

<ToolboxMdxWrapper>
    <DeployExampleERC20 enforceChainId={43113} />
</ToolboxMdxWrapper>

<Callout>
Make sure to save the deployed token address as you'll need it for the next steps. You can find it in the deployment confirmation or by checking your Core Wallet's token list.
</Callout>

</Step>

<Step>
### Add Token to Core Wallet

If you haven't already added the token to your Core Wallet:

1. Go to the Tokens tab
2. Click "Manage"
3. Click "+ Add Custom Token"
4. Enter the token contract address
5. The token symbol and decimals should be automatically detected
6. Click "Add Token"

<Callout>
Remember that you need to be connected to the Fuji testnet to see and interact with your token.
</Callout>
</Step>

<Step>
### Verify Token Balance

To verify your token balance:

1. In Core Wallet, select your token from the token list
2. The balance should be displayed
3. You can also check the token balance on the [Fuji Explorer](https://testnet.snowtrace.io) by entering your address

<Callout>
If you deployed the example token, you should see a balance of 10,000,000,000 tokens in your wallet.
</Callout>
</Step>
</Steps>


# Deploy a Home Contract (/academy/interchain-token-transfer/06-erc-20-to-erc-20-bridge/03-deploy-home)

---
title: Deploy a Home Contract
description: Deploy the Token Home on C-chain
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

We will deploy two Avalanche Interchain Token Transfer contracts. One on the source chain (which is C-chain in our case) and another on the destination chain (Echo in our case).

<Steps>
<Step>
### Deploy ERC20Home Contract

Since we're covering an ERC20 > ERC20 bridge, make sure to set the Transferrer type to "ERC20" and input the ERC20 token address you previously deployed in the token address field. Then deploy the ERC20Home contract on the Fuji testnet using our toolbox:

<Callout>
Make sure you have:
1. Deployed your ERC-20 token (from [Deploy ERC-20 Token](/academy/interchain-token-transfer/06-erc-20-to-erc-20-bridge/02-deploy-erc-20-token))
2. Have enough test AVAX for gas fees
</Callout>

<ToolboxMdxWrapper enforceChainId={43113}>
    <DeployTokenHome />
</ToolboxMdxWrapper>

</Step>

<Step>
### Save the ERC-20 Home Address

After deployment, you'll need to save the contract address for future steps. You can find it in the deployment confirmation in the toolbox

<Callout title="Note" type="info">
Keep this address handy as you'll need it for the next steps in the bridging process.
</Callout>
</Step>
</Steps>


# Deploy a Remote Contract (/academy/interchain-token-transfer/06-erc-20-to-erc-20-bridge/04-deploy-remote)

---
title: Deploy a Remote Contract
description: Deploy the Token Remote on your own blockchain
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

To ensure the wrapped token is bridged into the destination chain (in this case, C-Chain) you'll need to deploy a _remote_ contract that implements the `IERC20Bridge` interface, as well as inheriting the properties of `TeleporterTokenRemote`. In order for the bridged tokens to have all the normal functionality of a locally deployed ERC20 token, this remote contract must also inherit the properties of a standard `ERC20` contract.

<Steps>
<Step>
### Get Test ECH

Before deploying the remote contract, ensure you have some test tokens on Echo:

- **Recommended:** Create a [Builder Hub account](https://build.avax.network/login) and connect your wallet to receive testnet tokens automatically on Echo
- **Alternative:** Use the [external faucet](https://core.app/tools/testnet-faucet/?subnet=echo&token=echo) to claim tokens

</Step>

<Step>
### Deploy the Remote Contract

Now we'll deploy the ERC20TokenRemote contract to the Echo chain. Use our toolbox:

<Callout>
Make sure you have:
1. Deployed your ERC-20 token (from [Deploy ERC-20 Token](/academy/interchain-token-transfer/06-erc-20-to-erc-20-bridge/02-deploy-erc-20-token))
2. Deployed your ERC20Home contract (from [Deploy Home](/academy/interchain-token-transfer/06-erc-20-to-erc-20-bridge/03-deploy-home))
3. Have enough test ECH for gas fees
</Callout>

<ToolboxMdxWrapper enforceChainId={173750}>
    <DeployERC20TokenRemote />
</ToolboxMdxWrapper>

</Step>

<Step>
### Save the Remote Contract Address

After deployment, you'll need to save the contract address for future steps. You can find it in the deployment confirmation in the toolbox.

<Callout title="Note" type="info">
Keep this address handy as you'll need it for the next steps in the bridging process.
</Callout>
</Step>

</Steps>


# Register Remote Bridge (/academy/interchain-token-transfer/06-erc-20-to-erc-20-bridge/05-register-remote)

---
title: Register Remote Bridge
description: Register the remote bridge with the home bridge
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

After deploying both the home and remote bridge contracts, you need to register the remote bridge with the home bridge. This registration process informs the Home Bridge about your destination blockchain and bridge settings.

<Steps>
<Step>
### Register Remote Bridge

To register your remote bridge with the home bridge, use our toolbox:

<Callout>
Make sure you have:
1. Deployed your ERC-20 token (from [Deploy ERC-20 Token](/academy/interchain-token-transfer/06-erc-20-to-erc-20-bridge/02-deploy-erc-20-token))
2. Deployed your ERC20Home contract (from [Deploy Home](/academy/interchain-token-transfer/06-erc-20-to-erc-20-bridge/03-deploy-home))
3. Deployed your ERC20TokenRemote contract (from [Deploy Remote](/academy/interchain-token-transfer/06-erc-20-to-erc-20-bridge/04-deploy-remote))
4. Have enough test ECH for gas fees
</Callout>

<ToolboxMdxWrapper enforceChainId={173750}>
    <RegisterWithHome />
</ToolboxMdxWrapper>

</Step>

<Step>
### Verify Registration

After registration, you can verify the process was successful by looking for the registration event in the transaction logs. You can find the registration confirmation in the toolbox.

<Callout title="Note" type="info">
The registration process is a one-time setup that establishes the connection between your home and remote bridges. Once completed, you can proceed with token transfers.
</Callout>
</Step>
</Steps> 

# Transfer Tokens (/academy/interchain-token-transfer/06-erc-20-to-erc-20-bridge/06-transfer-tokens)

---
title: Transfer Tokens
description: Transfer an ERC20 from C-chain to your own blockchain
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

<Steps>
<Step>

### Transfer the Token Cross-chain

Now that all the bridge contracts have been deployed and registered, you can transfer tokens between chains using our toolbox:

<Callout>
Make sure you have:
1. Deployed your ERC-20 token (from [Deploy ERC-20 Token](/academy/interchain-token-transfer/06-erc-20-to-erc-20-bridge/02-deploy-erc-20-token))
2. Deployed your ERC20Home contract (from [Deploy Home](/academy/interchain-token-transfer/06-erc-20-to-erc-20-bridge/03-deploy-home))
3. Deployed your ERC20TokenRemote contract (from [Deploy Remote](/academy/interchain-token-transfer/06-erc-20-to-erc-20-bridge/04-deploy-remote))
4. Registered your remote bridge with the home bridge (from [Register Remote](/academy/interchain-token-transfer/06-erc-20-to-erc-20-bridge/05-register-remote))
5. Have enough test AVAX for gas fees
</Callout>

<ToolboxMdxWrapper enforceChainId={43113}>
    <TestSend />
</ToolboxMdxWrapper>

</Step>

<Step>

### Verify the Transfer

After initiating the transfer, you can verify it was successful by:

1. Checking the transaction status in the toolbox
2. Checking the transaction status in Core Wallet
3. Viewing the transaction details on the [Fuji Explorer](https://testnet.snowtrace.io)
4. Checking your token balance in Core Wallet on the destination chain

<Callout title="Note" type="info">
The transfer process may take a few moments to complete as it involves cross-chain communication. You can track the progress through the transaction hash.
</Callout>
</Step>
</Steps> 


# Integrate ICTT with Core (/academy/interchain-token-transfer/06-erc-20-to-erc-20-bridge/07-avacloud-and-core-bridge)

---
title:  Integrate ICTT with Core
description: Learn how to integrate ICTT bridges into the Core Bridge through AvaCloud.
updated: 2024-05-31
icon: Book
authors: [owenwahlgren]
---

## Integrate Interchain Token Transfers (ICTT) Into Core

ICTT bridges deployed through [**AvaCloud**](https://avacloud.io/) will automatically integrate into the [**Core Bridge**](https://core.app/en/bridge). This ensures that any bridges created through AvaCloud are available immediately and do not need extra review.

However, **ICTT bridges** deployed outside of AvaCloud (by third-party developers or other methods) will need to be submitted for manual review. Developers will need to provide:

1. **Token Bridge Contract Address(es)**: The bridge contract(s) on the L1.
2. **Layer 1 Information**: Name and other key details of the associated L1 blockchain.

The Core team will review this info to ensure the bridge meets security and compliance standards. This guarantees network reliability while allowing more flexibility.

### [Community Submission Form](https://forms.gle/jdcKcYWu26CsY6jRA)

<iframe src="https://forms.gle/jdcKcYWu26CsY6jRA" className="w-full h-96" />

### AvaCloud Relayer Service and Bridge Integration

When deploying ICTT bridges, the **meta-transaction relayer** plays a key role in enhancing the user experience. Once the bridge is set up, the relayer ensures users can transfer assets between chains without worrying about gas fees. 

By using the **relayer service**, gas costs for transactions made through the bridge are handled on behalf of users, streamlining cross-chain operations. The relayer, funded with the L1's gas token, forwards transactions signed by users to the destination chain, ensuring the asset bridge between chains works smoothly without requiring users to hold or manage gas tokens.

This integration is especially useful for bridging clients who are not familiar with Web3, as it removes the need for them to manage gas tokens during the cross-chain asset transfer process. Once set up, the relayer infrastructure includes:

1. A **relaying node** to handle transactions.
2. A **relayer wallet** funded with gas tokens from the L1.
3. A **trusted forwarder contract** that securely relays transactions.

With this setup, users benefit from a gas-free experience when interacting with your bridge, making cross-chain transfers and other actions seamless and accessible.


# Deploy Your Own ICTT Frontend (/academy/interchain-token-transfer/06-erc-20-to-erc-20-bridge/08-deploy-your-own-frontend)

---
title:  Deploy Your Own ICTT Frontend
description: Set up the BuilderKit for deploying your own Interchain Token Transfer (ICTT) frontend with custom tokens and chains.
updated: 2024-05-31
icon: Terminal
authors: [0xstt]
---
import Link from 'next/link';
import { cn } from '@/utils/cn';
import { buttonVariants } from '@/components/ui/button.tsx'
import { Step, Steps } from 'fumadocs-ui/components/steps';

In this section, you’ll learn how to deploy your own **ICTT frontend** using the BuilderKit and pre-configured tokens and chains. Follow these steps to quickly set up and test your own ICTT frontends with Avalanche L1s.

---

<Steps>

<Step>
### Open the AvaCloudSDK Starter Kit Github Repository

Start by opening the repository on Github.

<Link
    href="https://github.com/ava-labs/avalanche-starter-kit"
    className={cn(
    buttonVariants({ variant: 'default', className: 'mt-4' }),
    )}
    target='_blank'
>Open Avalanche Starter Kit</Link>
</Step>

<Step>
### Open the Dev Container and Navigate to the Chain Definitions

- Open the repository in a Github Codespace or Visual Studio Code.
- Navigate to the `web-apps/src/app/chains/definitions` folder.

In this folder, you’ll find separate files for each chain configuration. For example, `echo.ts` contains the definition for the **Echo L1** chain:

```ts
import { defineChain } from "viem";

export const echo = defineChain({
    id: 173750,
    name: 'Echo L1',
    network: 'echo',
    nativeCurrency: {
        decimals: 18,
        name: 'Ech',
        symbol: 'ECH',
    },
    rpcUrls: {
        default: {
            http: ['https://subnets.avax.network/echo/testnet/rpc']
        },
    },
    blockExplorers: {
        default: { name: 'Explorer', url: 'https://subnets-test.avax.network/echo' },
    },
    iconUrl: "/chains/logo/173750.png"
});
```

### How to Configure Your Own Blockchain

To configure your custom blockchain (e.g., `myblockchain`):

1. Copy the existing echo.ts file and rename it to myblockchain.ts.
2. Update the fields to match your blockchain’s specific details, such as chain ID, network name, and native currency.
3. Save the file in the chains/definitions folder. 

</Step>
<Step> 
### Import Your Chains

- Navigate to the `web-apps/src/app` folder.

Once you're inside the **APP** folder, open the `constants.tsx` file to begin configuring the tokens and chains.

```tsx
import { myblockchain } from './chains/definitions';
```

**Add Imported Chains to Array**

After importing the chains, add them into the chains array:

```tsx
export const CHAINS = [avalanche, avalancheFuji, echo, dispatch, myblockchain];
```

This array will hold the configuration of all the chains that will interact with your ICTT frontend.
</Step>
<Step> 
### Add Your Chain, and Configure Tokens

Next, configure your tokens. Here’s an example token configuration:

```tsx
export const TOKENS = [
  {
    address: "0x8D6f0E153B1D4Efb46c510278Db3678Bb1Cc823d",
    name: "TOK",
    symbol: "TOK",
    decimals: 18,
    chain_id: 43113,
    supports_ictt: true,
    transferer: "0xD63c60859e6648b20c38092cCceb92c5751E32fF",
    mirrors: [
      {
        address: "0x8D6f0E153B1D4Efb46c510278Db3678Bb1Cc823d",
        transferer: "0x8D6f0E153B1D4Efb46c510278Db3678Bb1Cc823d",
        chain_id: 173750,
        decimals: 18
      }
    ]
  },
  {
    address: "0x8D6f0E153B1D4Efb46c510278Db3678Bb1Cc823d",
    name: "TOK.e",
    symbol: "TOK.e",
    decimals: 18,
    chain_id: 173750,
    supports_ictt: true,
    is_transferer: true,
    mirrors: [
      {
        home: true,
        address: "0x8D6f0E153B1D4Efb46c510278Db3678Bb1Cc823d",
        transferer: "0xD63c60859e6648b20c38092cCceb92c5751E32fF",
        chain_id: 43113,
        decimals: 18
      }
    ]
  }
];
```

<Accordions>
<Accordion title="What Are `is_transferer` and `home` Flags?">
- **`is_transferer` Flag**: This flag is used to indicate if the token on the current chain is a transferer. A transferer is a contract that allows the token to be moved between chains using Interchain Token Transfers (ICTT). Set this flag to true if this token is responsible for transferring assets.
- **`home` Flag**: The `home` flag is used to indicate that this token is the original version of the asset on the **home chain**. When a token is mirrored on multiple chains, the home chain holds the original token, while the mirrors are representations of it on other chains.

These flags ensure proper handling of tokens when they are moved across chains. The `home` flag helps identify which chain holds the token, while `the is_transferer` flag specifies whether the token contract is responsible for transfers. 
</Accordion>
</Accordions>


</Step>
<Step> 
### Implement the ICTT Component

- Navigate to the `web-apps/src/app/ictt` folder.

Once you're inside the **ICTT** folder, open the `page.tsx` file to implement the **ICTT component** in the page. Here’s how to pass the token and chain details to the component:

```tsx
<ICTT tokens={tokens} token_in="0x8D6f0E153B1D4Efb46c510278Db3678Bb1Cc823d" source_chain_id={43113} destination_chain_id={173750}></ICTT>
```

In this example:

- `tokens` contains the configuration.
- `token_in` specifies the address of the token being transferred.
- `source_chain_id` and `destination_chain_id` represent the IDs of the source and destination chains. 
</Step>
<Step> 
### Run the Application

Move back to the `web-apps` folder and run the following command to start the app in development mode:

```bash
yarn run dev
```

You can now interact with the ICTT component. 
![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/interchain-token-transfer/site-running-IK70IqfXcCAYZBspWbomhiK601vB0e.png)
</Step>
</Steps>


# Overview of Multi-hop Transfers (/academy/interchain-token-transfer/07-tokens-on-multiple-chains/01-tokens-on-multiple-chain)

---
title: Overview of Multi-hop Transfers
description: Learn about how ICTT supports multi-hop transfers between spoke chains.
updated: 2024-05-31
authors: [owenwahlgren]
icon: Book
---

The token bridge also supports "multi-hop" transfers, where tokens can be transferred between remote chains via the home chain. To illustrate, consider two remotes _R<sub>a</sub>_ and _R<sub>b</sub>_ that are both connected to the same home _H_. A multi-hop transfer from _R<sub>a</sub>_ to _R<sub>b</sub>_ first gets routed from _R<sub>a</sub>_ to _H_, where the remote balances are updated, and then _H_ automatically routes the transfer on to _R<sub>b</sub>_.

In this example, our _R<sub>a</sub>_ chain is `Echo`, our _R<sub>b</sub>_ chain is `Dispatch`, and _H_ chain is the Avalanche C-Chain.

### What we will do

1. Deploy a new `ERC20TokenRemote` contract to `Dispatch`
2. Register the new `ERC20TokenRemote` contract with the `TokenHome` contract on the Avalanche C-Chain
3. Perform a multi-hop transfer of a token from `Echo` to `Dispatch`, with a 'hop' through the Avalanche C-Chain


<Quiz quizId="127"/>

# Deploy Token Remote for Multi-hop (/academy/interchain-token-transfer/07-tokens-on-multiple-chains/02-deploy-token-remote)

---
title: Deploy Token Remote for Multi-hop
description: Deploy and configure the ERC20TokenRemote contract on the second blockchain.
updated: 2024-05-31
authors: [owenwahlgren]
icon: Book
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

To ensure the wrapped token is bridged into the destination chain (in this case, C-Chain) you'll need to deploy a _remote_ contract that implements the `IERC20Bridge` interface, as well as inheriting the properties of `TeleporterTokenRemote`. In order for the bridged tokens to have all the normal functionality of a locally deployed ERC20 token, this remote contract must also inherit the properties of a standard `ERC20` contract.

<Steps>
<Step>
### Get Test DIS

Before deploying the remote contract, ensure you have some test tokens on Dispatch:

- **Recommended:** Create a [Builder Hub account](https://build.avax.network/login) and connect your wallet to receive testnet tokens automatically on Dispatch
- **Alternative:** Use the [external faucet](https://core.app/tools/testnet-faucet/?subnet=dispatch&token=dispatch) to claim DIS tokens

</Step>

<Step>
### Deploy the Remote Contract

Now we'll deploy the ERC20TokenRemote contract to the Echo chain. Use our toolbox:

<Callout>
Make sure you have:
1. Deployed your ERC-20 token (from [Deploy ERC-20 Token](/academy/interchain-token-transfer/06-erc-20-to-erc-20-bridge/02-deploy-erc-20-token))
2. Deployed your ERC20Home contract (from [Deploy Home](/academy/interchain-token-transfer/06-erc-20-to-erc-20-bridge/03-deploy-home))
3. Have enough test ECH for gas fees
</Callout>

<ToolboxMdxWrapper enforceChainId={779672}>
    <DeployERC20TokenRemote />
</ToolboxMdxWrapper>

</Step>

<Step>
### Save the Remote Contract Address

After deployment, you'll need to save the contract address for future steps. You can find it in the deployment confirmation in the toolbox.

<Callout title="Note" type="info">
Keep this address handy as you'll need it for the next steps in the bridging process.
</Callout>
</Step>

</Steps>


# Register Remote Bridge (/academy/interchain-token-transfer/07-tokens-on-multiple-chains/03-register-remote)

---
title: Register Remote Bridge
description: Register the remote bridge with the home bridge
updated: 2024-05-31
authors: [ashucoder9]
icon: Terminal
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

After deploying both the home and remote bridge contracts, you need to register the remote bridge with the home bridge. This registration process informs the Home Bridge about your destination blockchain and bridge settings.

<Steps>
<Step>
### Register Remote Bridge

To register your remote bridge with the home bridge, use our toolbox:

<Callout>
Make sure you have:
1. Deployed your ERC-20 token (from [Deploy ERC-20 Token](/academy/interchain-token-transfer/06-erc-20-to-erc-20-bridge/02-deploy-erc-20-token))
2. Deployed your ERC20Home contract (from [Deploy Home](/academy/interchain-token-transfer/06-erc-20-to-erc-20-bridge/03-deploy-home))
3. Deployed your ERC20TokenRemote contract (from [Deploy Remote](/academy/interchain-token-transfer/07-tokens-on-multiple-chains/02-deploy-token-remote))
4. Have enough test DIS for gas fees
</Callout>

<ToolboxMdxWrapper enforceChainId={779672}>
    <RegisterWithHome />
</ToolboxMdxWrapper>

</Step>

<Step>
### Verify Registration

After registration, you can verify the process was successful by looking for the registration event in the transaction logs. You can find the registration confirmation in the toolbox.

<Callout title="Note" type="info">
The registration process is a one-time setup that establishes the connection between your home and remote bridges. Once completed, you can proceed with token transfers.
</Callout>
</Step>
</Steps> 

# Multi-hop Transfer (/academy/interchain-token-transfer/07-tokens-on-multiple-chains/04-multihop)

---
title: Multi-hop Transfer
description: Perform the multi-hop transfer of `TOK` from `myblockchain` to `myblockchain2`, with a 'hop' through the Avalanche C-Chain.
updated: 2024-05-31
authors: [owenwahlgren]
icon: Book
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

<Steps>
<Step>

### Transfer the Token Cross-chain

Now that all the bridge contracts have been deployed and registered, you can transfer tokens between chains using our toolbox:

<Callout>
Make sure you have:
1. Deployed your ERC-20 token (from [Deploy ERC-20 Token](/academy/interchain-token-transfer/06-erc-20-to-erc-20-bridge/02-deploy-erc-20-token))
2. Deployed your ERC20Home contract (from [Deploy Home](/academy/interchain-token-transfer/06-erc-20-to-erc-20-bridge/03-deploy-home))
3. Deployed your ERC20TokenRemote contract (from [Deploy Remote](/academy/interchain-token-transfer/06-erc-20-to-erc-20-bridge/04-deploy-remote))
4. Registered your remote bridge with the home bridge (from [Register Remote](/academy/interchain-token-transfer/06-erc-20-to-erc-20-bridge/05-register-remote))
5. Have enough ERC-20 tokens on the _R<sub>a</sub>_ chain: `Echo` (you can transfer tokens from the _H_ chain to the _R<sub>a</sub>_ chain first) (from [Transfer Tokens](/academy/interchain-token-transfer/06-erc-20-to-erc-20-bridge/06-transfer-tokens))
6. Have enough test ECH for gas fees
</Callout>

<ToolboxMdxWrapper enforceChainId={173750}>
    <TestSend />
</ToolboxMdxWrapper>

</Step>

<Step>

### Verify the Transfer

After initiating the transfer, you can verify it was successful by:

1. Checking the transaction status in the toolbox
2. Checking the transaction status in Core Wallet
3. Viewing the transaction details on the [Fuji Explorer](https://testnet.snowtrace.io)
4. Checking your token balance in Core Wallet on the destination chain

<Callout title="Note" type="info">
The transfer process may take a few moments to complete as it involves cross-chain communication. You can track the progress through the transaction hash.
</Callout>
</Step>
</Steps> 


# Native to ERC-20 Token Bridge Overview (/academy/interchain-token-transfer/08-native-to-erc-20-bridge/01-native-to-erc-20-bridge)

---
title: Native to ERC-20 Token Bridge Overview
description: Learn how to transfer native Avalanche L1 tokens to the C-Chain as ERC-20 tokens.
updated: 2024-09-09
authors: [owenwahlgren]
icon: Book
---

ICTT is also capable of bridging native tokens between any Avalanche L1s as ERC-20 tokens. This process involves using a `NativeTokenHome` contract on the source L1, and a `ERC20TokenRemote` contract on the destination L1. The `NativeTokenHome` contract will be used to bridge the native token to the destination L1 as an ERC-20 token.

This example will cover native to ERC-20 token bridging between Avalanche C-Chain and Echo, where we'll bridge the native asset, `AVAX`, to Echo as an ERC-20 token.

### What we will do
1. Deploy `NativeTokenHome` on Avalanche C-Chain
2. Deploy `ERC20TokenRemote` on Echo
3. Register `ERC20TokenRemote` on Echo with `NativeTokenHome` on Avalanche
4. Perform a transfer of the native token on Avalanche to Echo as an ERC-20 token


# Deploy Native Token Home (/academy/interchain-token-transfer/08-native-to-erc-20-bridge/02-deploy-native-token-home)

---
title: Deploy Native Token Home
description: Deploy the NativeTokenHome contract on the Avalanche L1 blockchain.
updated: 2024-05-31
authors: [owenwahlgren]
icon: Book
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

<Callout>
For this guide, we'll be using the Avalanche Fuji testnet, which already has a wrapped native asset (WAVAX). If you're creating your own L1 blockchain, you'll need to deploy your own wrapped native asset first.
</Callout>

<Steps>
<Step>
### Deploy NativeTokenHome

Use our toolbox to deploy the NativeTokenHome contract:

<Callout>
Make sure you have:
1. Connected your Core Wallet to the Fuji testnet
2. Have enough test AVAX for gas fees
3. Select "Native Token" as the transferrer type in the toolbox
</Callout>

<ToolboxMdxWrapper enforceChainId={43113}>
    <DeployTokenHome />
</ToolboxMdxWrapper>
</Step>
<Step>
### Save the Native Token Home Address

After deployment, you'll need to save the contract address for future steps. You can find it in the deployment confirmation in the toolbox.

<Callout title="Note" type="info">
Keep this address handy as you'll need it for the next steps in the bridging process.
</Callout>
</Step>
</Steps>

# Deploy ERC20 Token Remote (/academy/interchain-token-transfer/08-native-to-erc-20-bridge/03-deploy-erc20-token-remote)

---
title: Deploy ERC20 Token Remote
description: Deploy the ERC20TokenRemote contract to the Echo chain.
updated: 2024-05-31
authors: [owenwahlgren]
icon: Book
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

<Steps>
<Step>
### Deploy ERC20TokenRemote

Use our toolbox to deploy the ERC20TokenRemote contract:

<Callout>
Make sure you have:
1. Connected your Core Wallet to the Fuji testnet
2. Have enough test ECH for gas fees
3. Select the NativeTokenHome contract you deployed in the previous step from the suggestions
4. If you don't see your NativeTokenHome contract in the suggestions, you'll need to manually enter its address
</Callout>

<ToolboxMdxWrapper enforceChainId={173750}>
    <DeployERC20TokenRemote />
</ToolboxMdxWrapper>

</Step>

<Step>
### Save the ERC20 Token Remote Address

After deployment, you'll need to save the contract address for future steps. You can find it in the deployment confirmation in the toolbox.

<Callout title="Note" type="info">
Keep this address handy as you'll need it for the next steps in the bridging process.
</Callout>
</Step>
</Steps>

# Register Remote Bridge (/academy/interchain-token-transfer/08-native-to-erc-20-bridge/04-register-remote)

---
title: Register Remote Bridge
description: Register the ERC20TokenRemote contract with the NativeTokenHome contract.
updated: 2024-05-31
authors: [owenwahlgren]
icon: Book
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

<Steps>
<Step>
### Register Remote Bridge

After deploying the bridge contracts, you need to register the remote bridge with the home bridge. Use our toolbox to complete the registration:

<Callout>
Make sure you have:
1. Successfully deployed your ERC20TokenRemote contract
2. Have enough test ECH for gas fees
</Callout>

<ToolboxMdxWrapper enforceChainId={173750}>
    <RegisterWithHome />
</ToolboxMdxWrapper>

</Step>

<Step>
### Verify Registration

After registration, you can verify the process was successful by looking for the registration event in the transaction logs. You can find the registration confirmation in the toolbox.

<Callout title="Note" type="info">
The registration process is a one-time setup that establishes the connection between your home and remote bridges. Once completed, you can proceed with token transfers.
</Callout>
</Step>
</Steps> 

# Native Token Bridge Transfer (/academy/interchain-token-transfer/08-native-to-erc-20-bridge/05-bridge-tokens)

---
title: Native Token Bridge Transfer
description: Perform a transfer of a native Avalanche L1 token to the C-Chain as an ERC-20 token.
updated: 2024-05-31
authors: [ashucoder9, owenwahlgren]
icon: Book
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

<Steps>
<Step>
### Transfer the L1's Native Token to the C-Chain

Now that all the bridge contracts have been deployed and configured, you can transfer native tokens from your C-Chain to Echo using our toolbox:

<Callout>
Make sure you have:
1. Successfully registered your remote bridge
2. Have enough native tokens in your C-Chain wallet for the transfer
3. Have enough test AVAX for gas fees
</Callout>

<ToolboxMdxWrapper enforceChainId={43113}>
    <TestSend />
</ToolboxMdxWrapper>

</Step>

<Step>

### Verify the Transfer

After initiating the transfer, you can verify it was successful by:

1. Checking the transaction status in the toolbox
2. Checking the transaction status in Core Wallet
3. Viewing the transaction details on the [Fuji Explorer](https://testnet.snowtrace.io)
4. Checking your token balance in Core Wallet on the destination chain

<Callout title="Note" type="info">
The transfer process may take a few moments to complete as it involves cross-chain communication. You can track the progress through the transaction hash.
</Callout>
</Step>
</Steps>


# Introduction (/academy/interchain-token-transfer/12-send-and-call/01-intro)

---
title: Introduction
description: Learn how to call another contract function after send tokens to another L1s.
updated: 2024-08-23
authors: [0xstt]
icon: Book
---

In addition to supporting basic token transfers, the token transferrer contracts offer a
`sendAndCall` interface for bridging tokens and using them in a smart contract interaction all
within a single Interchain Messaging message. If the call to the recipient smart contract fails, the
transferred tokens are sent to a fallback recipient address on the destination chain of the
transfer. The `sendAndCall` interface enables the direct use of transferred tokens in dApps on other
chains, such as performing swaps, using the tokens to pay for fees when invoking services, etc.

<YouTube id="wGMJCYA7R3g" />

Teleporter Messenger has the ability to receive cross-chain messages on the destination chain and casts related messages to the `TeleporterMessage` struct. It then sends these messages to the Home/Remote Transferrer contract, and handles them as `SEND` or `CALL`, as implemented in `TokenHome.sol` or `TokenRemote.sol`.

In this section we will cover the usage of the `CALL` message type with an example implementation.

When `sendAndCall` function is triggered, the following actions are taken;

- The Transferrer Contract grants an allowance to spend tokens on the destination contract.
- The Transferrer Contract encodes the received message as parameters for the `receiveToken` function, as defined in the `IERC20SendAndCallReceiver` or `INativeSendAndCallReceiver` interface.
- The Transferrer Contract checks whether the destination contract's function execution is successfull.
- The Transferrer Contract retrieves the remaining allowance to check if there are any unspent tokens exists.
- The Transferrer Contract removes the allowance for the destination contract.
- The Transferrer Contract sends the remaining tokens to the fallback recipient. If the destination contract fails to execute the function, the full amount will be sent to the fallback recipient.

## Prerequisites

The following prerequisites were covered in previous sections, so you should have already deployed the following contracts before starting this chapter:

- Base ERC20 Token on L1
- Home Transferrer Contract on L1
- Remote Transferrer Contract on Fuji
- A Running AWM-relayer from your L1 to Fuji


# Send and Call Receivers (/academy/interchain-token-transfer/12-send-and-call/03-send-and-call-receivers)

---
title: Send and Call Receivers
description: Learn how tokens are received by the receivers.
updated: 2024-08-23
authors: [0xstt]
icon: BookOpen
---

The interfaces `IERC20SendAndCallReceiver` or `INativeSendAndCallReceiver` are used for contracts that handle receiving ERC20 or native tokens of the Interchain Token Transfer protocol. They are similar to the `ITeleporterReceiver` interface, but they are specifically designed to handle token transfers.

### IERC20SendAndCallReceiver

The `receiveTokens` function will be called by the Transferrer bridge contract. The contract must implement this function to receive the tokens and can retrieve all the information about the origin of the tokens, the token, the bridge used, and the amount of tokens transferred from the parameters.

```solidity title="lib/icm-contracts/contracts/ictt/interfaces/IERC20SendAndCallReceiver.sol"
/**
 * @notice Interface for contracts that are called to receive token transfers.
 */
interface IERC20SendAndCallReceiver {
    /**
     * @notice Called to receive the amount of the given token
     * @param sourceBlockchainID Blockchain ID that the transfer originated from
     * @param originTokenTransferrerAddress Address of the token transferrer that initiated the Teleporter message
     * @param originSenderAddress Address of the sender that sent the transfer. This value
     * should only be trusted if {originTokenTransferrerAddress} is verified and known.
     * @param token Address of the token to be received
     * @param amount Amount of the token to be received
     * @param payload Arbitrary data provided by the caller
     */
    function receiveTokens(
        bytes32 sourceBlockchainID,
        address originTokenTransferrerAddress,
        address originSenderAddress,
        address token,
        uint256 amount,
        bytes calldata payload
    ) external;
}
```

### INativeSendAndCallReceiver

The `INativeSendAndCallReceiver` interface is used for contracts that handle receiving native tokens of the Interchain Token Transfer protocol. It is similar to the `IERC20SendAndCallReceiver` interface, but does not include the `token` and `amount` parameters. The `receiveTokens` is now `payable`. There is only a single native token on each chain, so the address is not needed. The amount can be determined from calling `msg.value`.

```solidity title="lib/icm-contracts/contracts/ictt/interfaces/INativeSendAndCallReceiver.sol"
/**
 * @notice Interface for a contracts that are called to receive native tokens.
 */
interface INativeSendAndCallReceiver {
    /**
     * @notice Called to receive the amount of the native token. Implementations
     * must properly handle the msg.value of the call in order to ensure it doesn't
     * become improperly made inaccessible.
     * @param sourceBlockchainID Blockchain ID that the transfer originated from
     * @param originTokenTransferrerAddress Address of the token transferrer that initiated the Teleporter message
     * @param originSenderAddress Address of the sender that sent the transfer. This value
     * should only be trusted if {originTokenTransferrerAddress} is verified and known.
     * @param payload Arbitrary data provided by the caller
     */
    function receiveTokens(
        bytes32 sourceBlockchainID,
        address originTokenTransferrerAddress,
        address originSenderAddress,
        bytes calldata payload
    ) external payable;
}
```

# Mock Receivers (/academy/interchain-token-transfer/12-send-and-call/04-mock-receivers)

---
title: Mock Receivers
description: A brief overview of the mock ERC20 and native token receivers used for testing in sendAndCall functions.
updated: 2024-08-23
authors: [0xstt]
icon: BookOpen
---

The primary purpose of these mock contracts is to test cross-chain token transfers and execute contract logic. These contracts implement the `IERC20SendAndCallReceiver` and `INativeSendAndCallReceiver` interfaces to handle token transfers, either for ERC20 tokens or native tokens, across Avalanche L1s.

This contract only performs the following actions:

- Checks if the message was received from a blocked sender.
- Emits a TokensReceived event.
- Checks if the payload is empty.
- Receives tokens to itself.

```solidity title="lib/icm-contracts/contracts/ictt/mocks/MockERC20SendAndCallReceiver.sol"
pragma solidity 0.8.25;

import {IERC20SendAndCallReceiver} from "../interfaces/IERC20SendAndCallReceiver.sol";
import {SafeERC20TransferFrom} from "../utils/SafeERC20TransferFrom.sol";
import {SafeERC20} from "@openzeppelin/contracts@5.0.2/token/ERC20/utils/SafeERC20.sol";
import {IERC20} from "@openzeppelin/contracts@5.0.2/token/ERC20/IERC20.sol";
import {Context} from "@openzeppelin/contracts@5.0.2/utils/Context.sol";

/**
 * THIS IS AN EXAMPLE CONTRACT THAT USES UN-AUDITED CODE.
 * DO NOT USE THIS CODE IN PRODUCTION.
 */

/**
 * @notice This is mock implementation of {receiveTokens} to be used in tests.
 * This contract DOES NOT provide a mechanism for accessing the tokens transfered to it.
 * Real implementations must ensure that tokens are properly handled and not incorrectly locked.
 */
contract MockERC20SendAndCallReceiver is Context, IERC20SendAndCallReceiver {
    using SafeERC20 for IERC20;

    mapping(bytes32 blockchainID => mapping(address senderAddress => bool blocked)) public
        blockedSenders;

    /**
     * @dev Emitted when receiveTokens is called.
     */
    event TokensReceived(
        bytes32 indexed sourceBlockchainID,
        address indexed originTokenTransferrerAddress,
        address indexed originSenderAddress,
        address token,
        uint256 amount,
        bytes payload
    );

    /** // [!code highlight:28]
     * @dev See {IERC20SendAndCallReceiver-receiveTokens}
     */
    function receiveTokens(
        bytes32 sourceBlockchainID,
        address originTokenTransferrerAddress,
        address originSenderAddress,
        address token,
        uint256 amount,
        bytes calldata payload
    ) external {
        require(
            !blockedSenders[sourceBlockchainID][originSenderAddress],
            "MockERC20SendAndCallReceiver: sender blocked"
        );
        emit TokensReceived({
            sourceBlockchainID: sourceBlockchainID,
            originTokenTransferrerAddress: originTokenTransferrerAddress,
            originSenderAddress: originSenderAddress,
            token: token,
            amount: amount,
            payload: payload
        });

        require(payload.length > 0, "MockERC20SendAndCallReceiver: empty payload");

        SafeERC20TransferFrom.safeTransferFrom(IERC20(token), _msgSender(), amount);
    }

    /**
     * @notice Block a sender from sending tokens to this contract.
     * @param blockchainID The blockchain ID of the sender.
     * @param senderAddress The address of the sender.
     */
    function blockSender(bytes32 blockchainID, address senderAddress) external {
        blockedSenders[blockchainID][senderAddress] = true;
    }
}
```

# Deploy a Mock Receiver (/academy/interchain-token-transfer/12-send-and-call/05-mock-receiver)

---
title: Deploy a Mock Receiver
description: Learn how to deploy a mock receiver contract.
updated: 2024-08-23
authors: [0xstt]
icon: Terminal
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

In this section, you will deploy mock receiver contracts on the Avalanche L1. 

<Steps>
<Step>

### Receiver Deployment

You can choose to deploy either the `MockERC20SendAndCallReceiver` or the `MockNativeSendAndCallReceiver` contract depending your token type.

```bash
forge create --rpc-url myblockchain --private-key $PK lib/icm-contracts/contracts/ictt/mocks/MockERC20SendAndCallReceiver.sol:MockERC20SendAndCallReceiver --broadcast
```

</Step>
<Step>

### Save Receiver Address

After deployment, save the `Deployed to` address in an environment variable for future use.

```bash
export MOCK_RECEIVER_ADDRESS=<address>
```

</Step>
<Step>

### Send Tokens

Use the following command to send tokens to the mock receiver contract:

```bash
cast send --rpc-url myblockchain --private-key $PK $ERC20_HOME_C_CHAIN \
"sendAndCall((bytes32, address, address, bytes, uint256, uint256, address, address, address, uint256, uint256), uint256)" \
"(${C_CHAIN_BLOCKCHAIN_ID_HEX}, ${ERC20_TOKEN_REMOTE_L1}, ${MOCK_RECEIVER_ADDRESS}, 0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000, 2500000, 2000000, 0x0000000000000000000000000000000000000000, ${FUNDED_ADDRESS}, ${ERC20_HOME_C_CHAIN}, 0, 0)" 100000000000000000000
```

</Step>
<Step>

### Verify the Results

Check the logs and emitted events to verify that the tokens were received correctly.

TBD: Provide instructions

</Step>
</Steps>

After successfully deploying the contract, move on to testing the mock receivers.

# Wrap Exchange Contract (/academy/interchain-token-transfer/13-cross-chain-token-swaps/07-exchange-contract)

---
title: Wrap Exchange Contract
description: Wrap the exchange contract to execute cross-chain swap operations.
updated: 2024-08-23
authors: [0xstt]
icon: Book
---

In this example, we will wrap Trader Joe's Factory contract to execute swap operations on the destination chain. Trader Joe's exchange contracts are already deployed on Fuji, which why we are choosing Fuji as the destination chain.

An example of the exchange wrapper code is provided below. This contract only allows swap operations on Trader Joe V1 pools or any other Uniswap V2-like contracts.

**Walkthrough**:

- The wrapper contract receives the payload via the `receiveTokens` function.
- The wrapper contract transfers the tokens to itself.
- The wrapper contract gets a quote from the exchange.
- The wrapper contract casts `payload` into `SwapOptions` struct.
- The wrapper contract checks if the received `amountOut` is greater than the `minAmountOut` requested when the contract was called from the source chain.
- The wrapper contract executes the swap operation and transfers the received asset to caller, depending on the preferred asset (wrapped token or native token).

_Disclaimer: The avalanche-interchain-token-transfer contracts used in this tutorial are under active development and are not yet intended for production deployments. Use at your own risk._

```solidity  title="src/interchain-token-transfer/4-send-and-call/DexERC20Wrapper.sol"
// (c) 2024, Ava Labs, Inc. All rights reserved.
// See the file LICENSE for licensing terms.

// SPDX-License-Identifier: Ecosystem

pragma solidity 0.8.18;

import {IERC20SendAndCallReceiver} from "../interfaces/IERC20SendAndCallReceiver.sol";
import {SafeERC20TransferFrom} from "../utils/SafeERC20TransferFrom.sol";
import {SafeERC20} from "@openzeppelin/contracts@4.8.1/token/ERC20/utils/SafeERC20.sol";
import {IERC20} from "@openzeppelin/contracts@4.8.1/token/ERC20/IERC20.sol";
import {Context} from "@openzeppelin/contracts@4.8.1/utils/Context.sol";

import {IWAVAX} from "./interface/IWAVAX.sol";
import {IUniswapFactory} from "./interface/IUniswapFactory.sol";
import {IUniswapPair} from "./interface/IUniswapPair.sol";

/**
 * THIS IS AN EXAMPLE CONTRACT THAT USES UN-AUDITED CODE.
 * DO NOT USE THIS CODE IN PRODUCTION.
 */

contract DexERC20Wrapper is Context, IERC20SendAndCallReceiver {
    using SafeERC20 for IERC20;

    address public immutable WNATIVE;
    address public immutable factory;

    struct SwapOptions {
        address tokenOut;
        uint256 minAmountOut;
    }

    constructor(
        address wrappedNativeAddress,
        address dexFactoryAddress
    ) {
        WNATIVE = wrappedNativeAddress;
        factory = dexFactoryAddress;
    }

    event TokensReceived(
        bytes32 indexed sourceBlockchainID,
        address indexed originTokenTransferrerAddress,
        address indexed originSenderAddress,
        address token,
        uint256 amount,
        bytes payload
    );

    // To receive native when another contract called.
    receive() external payable {}

    function getAmountOut(
        uint256 amountIn,
        uint256 reserveIn,
        uint256 reserveOut
    ) internal pure returns (uint256 amountOut) {
        uint256 amountInWithFee = amountIn * 997;
        uint256 numerator = amountInWithFee * reserveOut;
        uint256 denominator = reserveIn * 1e3 + amountInWithFee;
        amountOut = numerator / denominator;
    }

    function query(
        uint256 amountIn,
        address tokenIn,
        address tokenOut
    ) internal view returns (uint256 amountOut) {
        if (tokenIn == tokenOut || amountIn == 0) {
            return 0;
        }
        address pair = IUniswapFactory(factory).getPair(tokenIn, tokenOut);
        if (pair == address(0)) {
            return 0;
        }
        (uint256 r0, uint256 r1, ) = IUniswapPair(pair).getReserves();
        (uint256 reserveIn, uint256 reserveOut) = tokenIn < tokenOut ? (r0, r1) : (r1, r0);
        if (reserveIn > 0 && reserveOut > 0) {
            amountOut = getAmountOut(amountIn, reserveIn, reserveOut);
        }
    }

    function swap(
        uint256 amountIn,
        uint256 amountOut,
        address tokenIn,
        address tokenOut,
        address to
    ) internal {
        address pair = IUniswapFactory(factory).getPair(tokenIn, tokenOut);
        (uint256 amount0Out, uint256 amount1Out) = (tokenIn < tokenOut)
            ? (uint256(0), amountOut) : (amountOut, uint256(0));
        IERC20(tokenIn).safeTransfer(pair, amountIn);
        IUniswapPair(pair).swap(amount0Out, amount1Out, to, new bytes(0));
    }

    function receiveTokens(
        bytes32 sourceBlockchainID,
        address originTokenTransferrerAddress,
        address originSenderAddress,
        address token,
        uint256 amount,
        bytes calldata payload
    ) external {
        emit TokensReceived({
            sourceBlockchainID: sourceBlockchainID,
            originTokenTransferrerAddress: originTokenTransferrerAddress,
            originSenderAddress: originSenderAddress,
            token: token,
            amount: amount,
            payload: payload
        });

        require(payload.length > 0, "DexERC20Wrapper: empty payload");

        IERC20 _token = IERC20(token);
        // Receives teleported assets to be used for different purposes.
        SafeERC20TransferFrom.safeTransferFrom(_token, _msgSender(), amount);

        // Requests a quote from the Uniswap V2-like contract.
        uint256 amountOut = query(amount, token, WNATIVE);
        require(amountOut > 0, "DexERC20Wrapper: insufficient liquidity");

        // Parses the payload of the message.
        SwapOptions memory swapOptions = abi.decode(payload, (SwapOptions));
        // Checks if the target swap price is still valid.
        require(amountOut >= swapOptions.minAmountOut, "DexERC20Wrapper: slippage exceeded");
        
        // Verifies if the desired tokenOut is a native or wrapped asset.
        if (swapOptions.tokenOut == address(0)) {
            swap(amount, amountOut, token, WNATIVE, address(this));
            IWAVAX(WNATIVE).withdraw(amountOut);
            payable(originSenderAddress).transfer(amountOut);
        } else {
            swap(amount, amountOut, token, WNATIVE, originSenderAddress);
        }
    }

}
```

# Deploy Wrapped Exchange Contract (/academy/interchain-token-transfer/13-cross-chain-token-swaps/08-deploy-wrapped-exchange-contract)

---
title: Deploy Wrapped Exchange Contract
description: Deploy the DexERC20Wrapper on your own blockchain
updated: 2024-08-23
authors: [0xstt]
icon: Terminal
---

import { Step, Steps } from 'fumadocs-ui/components/steps';
import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';

Let's deploy our wrapper for the exchange contract on your own blockchain. 

<Steps>
<Step>
### Wrapper Deployment

While deploying the wrapped exchange contract, you will need to send two constructor arguments to the contract.

- The first argument is the wrapped native token (WAVAX) address on the destination chain (Fuji), which is: [`0xd00ae08403B9bbb9124bB305C09058E32C39A48c`](https://testnet.snowtrace.io/address/0xd00ae08403B9bbb9124bB305C09058E32C39A48c).
- The second argument is the Trader Joe's (or any other Uniswap V2-like dapp) Factory V1 contract address on the destination chain (Fuji), which is: [`0xF5c7d9733e5f53abCC1695820c4818C59B457C2C`](https://testnet.snowtrace.io/address/0xF5c7d9733e5f53abCC1695820c4818C59B457C2C). Deployed contracts of TraderJoe can be found [here](https://docs.traderjoexyz.com/deployment-addresses/fuji).

```bash
forge create --rpc-url local-c --private-key $PK --broadcast --constructor-args 0xd00ae08403B9bbb9124bB305C09058E32C39A48c 0xF5c7d9733e5f53abCC1695820c4818C59B457C2C contracts/interchain-token-transfer/cross-chain-token-swaps/DexERC20Wrapper.sol:DexERC20Wrapper
```

```bash 
[⠊] Compiling...
No files changed, compilation skipped
Deployer: 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC
Deployed to: 0x4Ac1d98D9cEF99EC6546dEd4Bd550b0b287aaD6D
Transaction hash: 0x5494b02a0278a113137f0ec9e2d31cc220d7276aa9bfd1a1438e61f2e85ca562
```
</Step>

<Step>
### Save the Wrapper Address
<Callout title="Note" type="info">
The address `0x4Ac1d98D9cEF99EC6546dEd4Bd550b0b287aaD6D` is your receiver contract address.
</Callout>

```bash
export WRAPPED_EXCHANGE_ADDRESS=...
```

In case you skipped the deployment phase mentioned on the previous page, you can use a wrapper contract, that is already deployed at [`0x38B097d95B96CD17966Cf617A71b7B20F61ba85B`](https://testnet.snowtrace.io/address/0x38B097d95B96CD17966Cf617A71b7B20F61ba85B).

```bash
export WRAPPED_EXCHANGE_ADDRESS=0x38B097d95B96CD17966Cf617A71b7B20F61ba85B
```
</Step>

<Step>
### Initiate the Cross-Chain Swap

Now that the wrapped exchange contract has been deployed, send an ERC20 token to execute a swap for WAVAX or AVAX from your Avalanche L1 to Fuji using the [`cast send`](https://book.getfoundry.sh/reference/cast/cast-send) command in foundry.

```bash
cast send --rpc-url echo --private-key $PK $ERC20_HOME_C_CHAIN "sendAndCall((bytes32, address, address, bytes, uint256, uint256, address, address, address, uint256, uint256), uint256)" "(${C_CHAIN_BLOCKCHAIN_ID_HEX}, ${ERC20_TOKEN_REMOTE_L1}, ${WRAPPED_EXCHANGE_ADDRESS}, 0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000, 2500000, 2000000, 0x0000000000000000000000000000000000000000, ${FUNDED_ADDRESS}, ${ERC20_HOME_C_CHAIN}, 0, 0)" 100000000000000000000
```

<Accordions>
<Accordion title="Generate Payload">
The ```payload``` parameter that we sent can be generated via following JavaScript file:

```typescript
const { ethers } = require("ethers");

function encode() {

    const struct = {
        tokenOut: "0xd00ae08403B9bbb9124bB305C09058E32C39A48c",
        minAmountOut: 0
    };

    const types = ["address", "uint256"];
    const encoded = ethers.AbiCoder.defaultAbiCoder().encode(types, [ struct.tokenOut, struct.minAmountOut ]);

    console.log(encoded);

}

encode();
```
</Accordion>
</Accordions>
</Step>

<Step>
### Verify the Results

To verify that your cross-chain swap was successful, you'll need to check the balance of your address on the destination chain (Fuji). You can use Foundry's cast command to check both native AVAX and WAVAX balances.

**Check WAVAX Balance**: Since the swap involves WAVAX (the wrapped version of AVAX), use the following command to check the WAVAX token balance:

```bash
cast call --rpc-url local-c 0xd00ae08403B9bbb9124bB305C09058E32C39A48c "balanceOf(address)" ${FUNDED_ADDRESS}
```

This calls the `balanceOf` function on the WAVAX token contract to check your balance.

**Check Native AVAX Balance**: If you chose to receive native AVAX instead of WAVAX, check your native balance:

```bash
cast balance --rpc-url local-c ${FUNDED_ADDRESS}
```

```bash
cast balance --rpc-url local-c ${FUNDED_ADDRESS} --ether
```
</Step>
</Steps>


# Scaling with TokenRemote (/academy/interchain-token-transfer/14-scaling-decimals/01-math-example)

---
title: Scaling with TokenRemote
description: Learn how to handle token scaling with TokenRemote contracts when bridging assets with different decimal systems.
updated: 2024-10-04
authors: [owenwahlgren]
icon: Calculator
---

## Math Example

Token scaling is a crucial part of cross-chain token transfers, especially when dealing with varying decimal denominations between the home and remote assets. This chapter will provide a math example to demonstrate how the scaling works with `TokenRemote` contracts.

In this example, let's assume we are bridging an ERC-20 token from a home chain where the token uses 6 decimal places to a remote chain as the native token that uses 18 decimal places (e.g., USDC on Avalanche). 

The key variables here are:
- `_homeTokenDecimals = 6`
- `_tokenDecimals = 18`
- `_tokenMultiplier` is calculated as:

<Mermaid chart={`
sequenceDiagram
    participant Home as TokenHome.sol (_homeTokenDecimals)
    participant Remote as TokenRemote.sol (_tokenDecimals)
    participant Multiplier as Token Multiplier (_tokenMultiplier)
    
    Home->>Remote: Calculate _tokenDecimals - _homeTokenDecimals
    Remote->>Multiplier: 18 - 6 = 12
    Multiplier-->>Multiplier: 10^12
`} />

This multiplier helps scale the token amounts when transferring between chains.

### Scenario 1: Transferring from Home (6 decimals) to Remote (18 decimals)

When transferring tokens from the home chain (6 decimals) to the remote chain (18 decimals), the token amount is multiplied by `_tokenMultiplier` to normalize the denomination. If `multiplyOnRemote = true`, we perform the following:

For example, if we transfer **100 USDC** (which is represented as `100 × 10^6` in the 6-decimal system), it will be scaled as follows on the remote chain:

```
100 × 10^6 × 10^{12} = 100 × 10^{18}
```
Thus, the value on the remote chain would be 100 × 10^{18}, equivalent to 100 USDC in 18 decimals.

### Scenario 2: Transferring from Remote (18 decimals) to Home (6 decimals)

When transferring tokens back from the remote chain (18 decimals) to the home chain (6 decimals), the token amount is divided by `_tokenMultiplier`. If `multiplyOnRemote = true`, the reverse scaling applies:

For example, transferring `100 × 10^{18}` (which is 100 USDC in the 18-decimal system) back to the home chain would scale down:

```
100 × 10^{18} ÷ 10^{12} = 100 × 10^6
```

This results in 100 × 10^6 USDC, which correctly represents 100 USDC in the 6-decimal system.

By applying this multiplier, tokens retain their value across chains with different decimal systems.

<Quiz quizId="126" />


# Example USDC as Native Token (DIY) (/academy/interchain-token-transfer/14-scaling-decimals/02-example)

---
title: Example USDC as Native Token (DIY)
description: Learn how to transfer USDC to a new Avalanche L1 and use it as a native token via ICTT.
updated: 2024-09-03
authors: [owenwahlgren]
icon: Terminal
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

In this section, you will learn how to transfer USDC from Avalanche’s C-Chain to a new Avalanche L1 using Interchain Token Transfers (ICTT) and set it up to act as the **native token** on the new L1. This guide will take you through the steps of configuring a local network environment, deploying the necessary contracts, and transferring tokens.


<Steps>
<Step>
### Create a new blockchain and Deploy on Local Network

Use the **Avalanche CLI** to create a new blockchain where you will deploy USDC as the native token.


```bash
avalanche blockchain create myblockchain  
```
```bash
avalanche blockchain deploy myblockchain
```
</Step>
<Step>
### Acquire USDC On Fuji C-Chain

The address for USDC on Fuji C-Chain is [`0x5425890298aed601595a70ab815c96711a31bc65`](https://testnet.snowtrace.io/token/0x5425890298aed601595a70ab815c96711a31bc65).
For convience we have already deployed a `TokenHome` to the C-Chain for USDC with the address [`0x546526F786115af1FE7c11aa8Ac5682b8c181E3A`](https://testnet.snowtrace.io/address/0x546526F786115af1FE7c11aa8Ac5682b8c181E3A)

You can use the [Core Faucet to get some USDC](https://core.app/en/tools/testnet-faucet/?subnet=c&token=usdcc) on Fuji. 

```bash
export USDC=0x5425890298aed601595a70ab815c96711a31bc65
export USDC_HOME_C_CHAIN=0x546526F786115af1FE7c11aa8Ac5682b8c181E3A
```
</Step>
<Step>
### Deploy Interchain Token Transfer Contracts
Set up the remote transferer contracts for transferring tokens between the C-Chain and the newly created L1.
   
- `NativeTokenRemote` Contract on `myblockchain` 
```bash 
forge create --rpc-url myblockchain --private-key $PK --broadcast --optimize --optimizer-runs 200 --constructor-args "($TELEPORTER_REGISTRY_L1, $FUNDED_ADDRESS, "1", $C_CHAIN_BLOCKCHAIN_ID_HEX, $USDC_HOME_C_CHAIN, 6)" "USDC" 100000000000000000000 0 lib/icm-contracts/contracts/ictt/TokenRemote/NativeTokenRemote.sol:NativeTokenRemote
```

_Note: When deploying the `NativeTokenRemote` contract on the L1, ensure that the **initial amount** matches the native token amount that was minted when the blockchain was created. This ensures consistency between the native token supply and the remote token counterpart._

```
[⠊] Compiling...
[⠊] Compiling 34 files with Solc 0.8.25
[⠒] Solc 0.8.25 finished in 2.00s
Compiler run successful!
Deployer: 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC
Deployed to: 0xe17bDC68168d07c1776c362d596adaa5d52A1De7
Transaction hash: 0x26326b925a210e99e274739dc2ca017ff19447b6e6b1dfb875740d55d5031ad6
```

<Callout title="Note" type="info">
The address `0xe17bDC68168d07c1776c362d596adaa5d52A1De7` is your receiver contract address.
</Callout>

```bash
export NATIVE_TOKEN_REMOTE_L1=0x...
```
</Step>
<Step>
### Granting Native Minting Rights to NativeTokenRemote Contract
To ensure that the `NativeTokenRemote` contract can mint native tokens on the L1 when USDC tokens are transferred from the `C-Chain`, the contract must be granted **minting rights**. This is done by adding the `NativeTokenRemote contract` address to the `Native Minter Precompile`.

1. You will need to interact with the `Native Minter Precompile`, which resides at a fixed address on all Avalanche L1s:  
**Native Minter Precompile Address**: `0x0200000000000000000000000000000000000001`
     
2. Use the following command to grant the `NativeTokenRemote` contract minting rights by setting it as an **enabled** address on the Native Minter Precompile:
  
```bash
cast send --rpc-url myblockchain --private-key $PK 0x0200000000000000000000000000000000000001 "setEnabled(address)" $NATIVE_TOKEN_REMOTE_L1
```

- `$NATIVE_TOKEN_REMOTE_L1`: The deployed address of the `NativeTokenRemote` contract on your L1.

Once this step is completed, the `NativeTokenRemote` contract will have the necessary permissions to mint native tokens when USDC tokens are transferred from the C-Chain.
</Step>
<Step>
### Register Remote Token with Home Transferer
Register the remote token on the home chain so that it recognizes the transferer contracts.

```bash 
cast send --rpc-url myblockchain --private-key $PK $NATIVE_TOKEN_REMOTE_L1 "registerWithHome((address, uint256))" "(0x0000000000000000000000000000000000000000, 0)"
```
</Step>
<Step>
### Collateralize and Transfer Tokens
Add collateral to the transferer contract on the home chain, and then send the USDC tokens across chains.

<Accordions>
<Accordion title="What is Collateral?">
Collateral in this context refers to the amount of the token that is locked in the `Home Transferer contract` on the source chain (`C-Chain`) to back the value of the token on the destination chain (`myblockchain`). This ensures that for every token minted on the remote chain, there’s an equivalent token locked as collateral on the home chain.
</Accordion>
<Accordion title="Why is Collateral Important?">
Collateralization ensures that the total supply of the token remains consistent across both chains. When tokens are sent from the `home chain`, they are locked as collateral, and a corresponding number of tokens is minted on the remote chain. If tokens are sent back to the home chain, the collateral is unlocked, and the minted tokens on the remote chain are burned.
</Accordion>
</Accordions>

- **Approve Tokens for Transfer**  
Approve a certain number of tokens to be used by the Home Transferer. 

```bash  
cast send --rpc-url local-c --private-key $PK $USDC "approve(address, uint256)" $USDC_HOME_C_CHAIN 2000000000000000000000
```

- **Add Collateral and Send Tokens**  
Add collateral to the transferer contract.
```bash 
cast send --rpc-url local-c --private-key $PK $USDC_HOME_C_CHAIN "addCollateral(bytes32, address, uint256)" $L1_BLOCKCHAIN_ID_HEX $NATIVE_TOKEN_REMOTE_L1 100000000000000000000
```
You can also confirm whether the Transferer is collateralized now by running the below command:

```bash
cast call --rpc-url myblockchain $NATIVE_TOKEN_REMOTE_L1 "isCollateralized()(bool)"
```
Send tokens to the L1
```bash 
cast send --rpc-url local-c --private-key $PK $USDC_HOME_C_CHAIN "send((bytes32, address, address, address, uint256, uint256, uint256, address), uint256)" "(${L1_BLOCKCHAIN_ID_HEX}, ${NATIVE_TOKEN_REMOTE_L1}, ${FUNDED_ADDRESS}, ${USDC}, 0, 0, 250000, 0x0000000000000000000000000000000000000000)" 1000000000000000000000
```
</Step>

<Step>
Check Balance
```bash
cast balance --rpc-url myblockchain $FUNDED_ADDRESS
```
</Step>
</Steps>

---

### Conclusion

Follow the steps above to transfer a USDC token from the C-Chain to your custom Avalanche L1 and use it as the native token. This exercise will demonstrate how Avalanche’s **Interchain Token Transfer (ICTT)** system works, ensuring that tokens are properly locked, transferred, and minted across multiple chains.

For more detailed information, refer to the [official Avalanche ICTT documentation](/academy/interchain-token-transfer).


# Avalanche Starter Kit (/academy/multi-chain-architecture/03-avalanche-starter-kit/01-avalanche-starter-kit)

---
title: Avalanche Starter Kit
description: Learn about the basics of Avalanche.
updated: 2024-05-31
authors: [martineckardt]
icon: Book
---

To make easier your journey through this course, we have prepared a Starter Kit repo consisting of everything you will need to start developing your own custom blockchains on Avalanche. This repo will provide a self-contained environment with Avalanche-CLI, and Foundry so you can follow the course without the need of installing anything else other than launching the environment.

# What You Will Learn

In this section, you will go through the following topics:

- How to launch your own Codespace
- Create your own Avalanche Interchain Messaging enabled custom blockchain
- Foundry configuration

At the end of this section, you will have your environment ready to follow with the Cross-Chain development with Avalanche Interchain Messaging. 


# Set Up Avalanche Starter Kit (/academy/multi-chain-architecture/03-avalanche-starter-kit/02-set-up)

---
title: Set Up Avalanche Starter Kit
description: Learn about the basics of Avalanche.
updated: 2024-05-31
authors: [martineckardt]
icon: Terminal
---

import SetUp from "@/content/common/avalanche-starter-kit/set-up.mdx";

import defaultMdxComponents from "fumadocs-ui/mdx";

<SetUp components={defaultMdxComponents}/>

# Create Blockchain (/academy/multi-chain-architecture/03-avalanche-starter-kit/03-create-blockchain)

---
title: Create Blockchain
description: Deploy a new Avalanche L1 on local network.
updated: 2024-05-31
authors: [martineckardt]
icon: Terminal
---

import CreateDefaultBlockchain from "@/content/common/avalanche-starter-kit/create-default-blockchain.mdx";

import defaultMdxComponents from "fumadocs-ui/mdx";

<CreateDefaultBlockchain components={defaultMdxComponents}/>

# Add Blockchain to Wallet (/academy/multi-chain-architecture/03-avalanche-starter-kit/04-add-blockchain-to-wallet)

---
title: Add Blockchain to Wallet
description: Add the newly created Avalanche L1 to Core.
updated: 2024-05-31
authors: [martineckardt]
icon: Terminal
---

import AddBlockchainToWallet from "@/content/common/core-wallet/add-blockchain-to-wallet.mdx";

import defaultMdxComponents from "fumadocs-ui/mdx";

<AddBlockchainToWallet components={defaultMdxComponents}/>

# Import EWOQ Account (/academy/multi-chain-architecture/03-avalanche-starter-kit/05-add-ewoq-account)

---
title: Import EWOQ Account
description: Import the private keys of EWOQ account to Core.
updated: 2024-05-31
authors: [martineckardt]
icon: Terminal
---

import ImportEWOQAccount from "@/content/common/core-wallet/import-ewoq-account.mdx";

<ImportEWOQAccount/>

# Different Types of Networks (/academy/multi-chain-architecture/03-avalanche-starter-kit/06-networks)

---
title: Different Types of Networks
description: Learn about different types of networks.
updated: 2024-05-31
authors: [martineckardt]
icon: Terminal
---

import Networks from "@/content/common/avalanche-starter-kit/networks.mdx";

You just deployed and interacted with your first local network. But what does that mean? You can interact with your network, but you will notice that no one else can. Therefore, we have to understand what different Networks are in Avalanche.

<Networks />


# Pause and Resume (/academy/multi-chain-architecture/03-avalanche-starter-kit/07-pause-and-resume)

---
title: Pause and Resume
description: If you've deployed an Avalanche L1, you can preserve and restore the state of your deployed Avalanche L1s.
updated: 2024-10-07
authors: [0xstt]
icon: BookOpen
---

import PauseAndResume from "@/content/common/avalanche-starter-kit/pause-and-resume.mdx";

import defaultMdxComponents from "fumadocs-ui/mdx";

<PauseAndResume components={defaultMdxComponents}/>


# P-Chain (/academy/permissioned-l1s/01-introduction/01-pchain-review)

---
title: P-Chain
description: A review of the Platform Chain.
updated: 2025-03-13
authors: [nicolasarnedo]
icon: Book
---

import { Callout } from 'fumadocs-ui/components/callout';

## Validators in a Multi-Chain Network

Validators are nodes of a blockchain that secure the network by validating the transactions.
Each L1 in the Avalanche network has it's own set of validators that is running the `AvalancheGo` client.

![multi-chain-architecture](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/l1s.png)

All validators are registered on the P-Chain with a unique node ID, public key, and stake weight, mapped to the blockchain they are validating.

![P-Chain Ledger View](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/PchainLedger.png)

## Platform Chain (P-Chain)

The Platform Chain is the backbone for the native interoperability of the Avalanche network. It is a
registry of all validators in the Avalanche network. This includes the validators of the Primary
Network (including the X-, C- and P-Chain), as well as all L1s and legacy Subnet validators. The
following graphic shows a simplified data model of the P-Chain:

<img src="/common-images/permissioned-l1s/PchainValidators.png" alt="P-Chain Architecture" />

Builders can create new L1 blockchains in the Avalanche Network by issuing transactions on the
P-Chain. The P-Chain runs a special-purpose virtual machine called the
[platformvm](https://github.com/ava-labs/avalanchego/tree/master/vms/platformvm). 

<Callout type="info">
**It is not EVM-based and therefore to interact with it you need a compatible wallet like Core wallet.**
</Callout> 

Creating new records for L1 blockchains on the P-Chain is done by issuing transactions like the `CreateSubnetTx` and `CreateChainTx`.

The P-Chain is secured by the Primary Network validators. L1 validators are syncing the P-Chain,
meaning they always have the latest view of the validator set of all blockchains in the Avalanche
network, but are not participating in the consensus of the P-Chain.




# Multi-Chain Architecture (/academy/permissioned-l1s/01-introduction/02-multi-chain-review)

---
title: Multi-Chain Architecture
description: A review of Avalanche's Multi-Chain Architecture
updated: 2025-03-13
authors: [nicolasarnedo]
icon: BookOpen
---

## Subnets/L1s vs Chains

It's important to understand that a **Subnet or L1** is a validator set, while a **chain** is an individual blockchain instance:

- **Subnet/L1**: A group of validators that can validate multiple blockchains
- **Chain**: A single blockchain validated by exactly one Subnet

While technically one Subnet can validate multiple chains (like the Primary Network validating P-Chain, C-Chain, and X-Chain), **in production it's almost always a 1:1 relationship**, and we strongly recommend keeping it as such for:
- **Simpler management**
- **Resource isolation**: Each application gets dedicated validator resources, and in the scenario that multiple validators go down, at least only one chain will be affected.  

## Subnets

Subnets are blockchains validated by a *subset of Primary Network validators*. 

Key technical characteristics:
- Validators must be Primary Network validators (2,000 AVAX stake requirement)
- Validators sync and validate the entire Primary Network (X, P, C chains) - takes longer to sync
- Validator set is constrained to existing Primary Network participants

<img src="https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/l1-validator-management/primary-network-3Xv3evd1fOAVXXEZ69mmrBI5AFt7AX.png" alt="Primary Network
Architecture" />

## L1s

L1s are blockchains with *sovereign validator sets* independent of the Primary Network.

Key technical characteristics:
- Validators form their own independent validator set
- Validators pay continuous fees (~1.33 AVAX/month)
- Validators only sync the P-Chain, not the entire Primary Network (faster synce time)
- No dependency on Primary Network validator participation

In the [Subnet Creation](/academy/permissioned-l1s/03-create-an-L1/01-create-subnet) section we will cover how to create a Subnet using [Avalanche's Developer Console](/console/layer-1/create). To learn more about this architecture transition and the ACPs that enabled it, check out the [ETNA upgrade](/academy/permissioned-l1s/02-proof-of-authority/04-etna-upgrade).

# ICM for Validator Manager (/academy/permissioned-l1s/01-introduction/03-interop)

---
title: ICM for Validator Manager
description: How Avalanche's Interchain Messaging (ICM) works with Validator Manager Contracts (VMC)
updated: 2025-03-13
authors: [nicolasarnedo]
icon: BookOpen
---

Interchain Messaging (ICM) is the foundation that enables secure communication between blockchains in the Avalanche ecosystem. While ICM is commonly used for cross-chain applications leveraging ICM contracts & Relayers, the Validator Manager Contract (VMC) uses ICM in a unique way. 

## ICM Architecture Layers

Revisiting the diagram we saw in the [Interoperability](/academy/avalanche-fundamentals/05-interoperability/03-icm-icmContracts-and-ictt) section of the Avalanche Fundamentals course, the Validator Manager is placed at the same level as the ICM contracts are.

![ICM Layers with VMC](/common-images/permissioned-l1s/ICMLayersVMC.png)

We place the Validator Manager Contract (VMC) here because it has:

- **Direct ICM Access**: VMC can interact directly with the ICM (Warp precompile)
- **Native Integration**: VMC is designed specifically for validator operations

### User-Driven Message Relaying

In typical ICM use cases for cross-chain applications:
- A relayer monitors for messages
- The relayer collects validator signatures
- The relayer submits the message to the destination chain

However, **validator management works differently**:
- The user directly submits transactions
- The user signs and manages their own message flow
- No third-party relayer service is involved

![VMC & P-Chain Communication Flow](/common-images/permissioned-l1s/VmcPchainFlow.png)

## How ICM Enables Validator Management

The power of ICM in validator management comes from its ability to securely coordinate changes between:
- **The L1**: Where validator operations are initiated
- **The P-Chain**: Where validators are officially registered
- **Back to the L1**: Where the validator set changes are confirmed to the Validator Manager Contract

It's crucial to understand that **the P-Chain serves as the single source of truth** for all validator registrations across the Avalanche network. While your Validator Manager contract initiates operations and tracks state changes, the P-Chain ultimately determines which validators are active and recognized by the network. This architecture ensures that no matter where your Validator Manager is deployed or how it operates, all validator changes must be validated and recorded by the P-Chain to be considered official.

### Message Security Through Signatures

Just like in other ICM use cases, messages in validator management are secured through BLS signatures:

The key difference is that in validator management:
- The user initiates the signature collection process
- The signatures prove the L1's validator set agrees on the operation
- The user then includes these signatures when submitting to the P-Chain

### Message Verification

The P-Chain verifies incoming validator management messages just like any ICM message:

This verification ensures that:
- The message truly came from the specified L1
- The L1's validators have approved the operation

In the next section we will learn about common Proxy Patterns.




# Proxy Patterns (/academy/permissioned-l1s/01-introduction/04-proxy-pattern)

---
title: Proxy Patterns
description: Understanding proxy patterns in blockchain - their importance, advantages, and risks.
updated: 2025-07-08
authors: [nicolasarnedo]
icon: BookOpen
---

In blockchain development smart contracts are **immutable by design**, this can be beneficial for users to trust the software they are using will not be altered, but can represent challenges for developers to improve existing software or fix bugs.

Proxy patterns offer a solution to this dilemma by separating contract logic from data storage, enabling upgrades while maintaining the same contract address.

## How Proxy Patterns Work

At its core, a proxy pattern involves two main components:

1. **Proxy Contract**: Holds the permanent address and stores all contract state
2. **Implementation Contract**: Contains the actual business logic that can be upgraded

When users interact with the proxy contract, it delegates all calls to the implementation contract using the `delegatecall` opcode, executing the implementation's code in the proxy's storage context.

When the owner/admin of the proxy wants to upgrade

![Proxy Pattern Basic Flow](/common-images/permissioned-l1s/ProxyBasic.png)

## Common Proxy Patterns

### 1. Transparent Proxy Pattern

The Transparent Proxy pattern, developed by OpenZeppelin, ensures clear separation between admin and user interactions:

- Admin calls are handled by the proxy itself
- User calls are delegated to the implementation
- Prevents function selector clashes between proxy and implementation

### 2. UUPS (Universal Upgradeable Proxy Standard)

UUPS moves the upgrade logic to the implementation contract itself:

- More gas-efficient than transparent proxies
- Implementation controls its own upgradeability
- Requires careful implementation to avoid locking upgrades

### 3. Beacon Proxy Pattern

Beacon proxies enable multiple proxy instances to share the same implementation:

- All proxies point to a single beacon contract
- Beacon contract holds the implementation address
- Upgrading the beacon updates all proxy instances simultaneously

## Advantages of Proxy Patterns

1. **Upgradability Without Address Changes** - Users and integrations can continue using the same contract address even after upgrades, preserving user interfaces, exchange listings, and historical transaction references.
2. **Bug Fixes and Security Patches** - Critical vulnerabilities can be addressed without requiring users to migrate to a new contract, enabling rapid response to security incidents with minimal disruption.
3. **Feature Addition and Optimization** - New functionality can be added over time including gas optimization improvements, new features based on user feedback, and integration with newer protocols.

## Risks and Considerations

1. **Centralization Risk** - Upgrade capabilities rest with a single admin or small group, creating a single point of failure and potential for malicious upgrades.
2. **Function Selector Clashes** - Proxy and implementation functions can have matching selectors, causing unexpected behavior, security vulnerabilities, and upgrade failures.
3. **Complexity** - Proxy patterns add complexity through additional gas costs for delegatecall operations and make contracts harder to audit and verify.

# Blockchain Permissioning (/academy/permissioned-l1s/02-proof-of-authority/01-blockchain-permissioning)

---
title: Blockchain Permissioning
description: Understanding the fundamental differences between blockchain permission models
updated: 2025-07-31
authors: [nicolasarnedo]
icon: Book
---

Before diving into what Proof of Authority is, it's crucial to understand the fundamental differences between how blockchains control access, and how we name them according to it. 

*What is the difference between a Private and a Permissioned Blockchain?* 

If you know the difference, you can skip this section. However, if you doubted, it is important you know what seperates them. These distinctions form the foundation for choosing the right blockchain architecture for your use case.

## Permissioned (Private) Blockchains

A permissioned **private blockchain** is the most restrictive model. Think of it as a closed network where:

- **Read access**: Restricted - Only network participants can view transactions and state
- **Write access**: Restricted - Only authorized members can submit transactions
- **Validator management model**: Fixed set - Predetermined group of validators that rarely changes
- **Governance**: Centralized - Single entity or small group controls all decisions

**Two Types of Privacy**: It's important to understand that "private" can mean two different things in blockchain contexts:

1. **Access Privacy (Walled Garden)**: The blockchain itself is hidden from the public - only authorized participants can access the RPC endpoints to read any data. This is what we mean by "private blockchain" and is natively supported on Avalanche.

2. **Data Privacy (Encryption)**: The blockchain is publicly accessible, but the actual transaction data is encrypted. Anyone can see that transactions occurred, but the contents are encrypted and only readable by authorized parties. 
Examples include [Zama's FHE-based confidential smart contracts](https://www.zama.ai/) and [Avalanche's EncryptedERC implementation](https://github.com/ava-labs/EncryptedERC) using zero-knowledge proofs.

Most private blockchains use access privacy, while some public blockchains add data privacy through encryption.

## Permissioned (Public) Blockchains

A **permissioned blockchain** offers a middle ground:

- **Read access**: Public - Transaction data is visible to everyone
- **Write access**: Configurable - Only authorized entities can submit transactions or deploy contracts
- **Validator management model**: Permission-based - Validators need approval to join, but the set can change
- **Governance**: Hybrid - Rules-based system determines participation and changes


## Permissionless Blockchains

A **permissionless blockchain** is completely open:

- **Read access**: Public - Anyone can view all transactions and state
- **Write access**: Open - Anyone can submit transactions (paying gas fees)
- **Validator management model**: Open participation - Anyone can validate (usually with staking requirements)
- **Governance**: Decentralized - Token holders or validators vote on changes

## Key Differences

![Private vs Permissioned vs Permissionless Blockchain Spectrum](/common-images/permissioned-l1s/PrivateVsPermissionedVsPermissionless.png)

| Aspect | Permissioned Private | Permissioned Public | Permissionless |
|--------|---------|--------------|----------------|
| **RPC Access** | Restricted endpoints | Public endpoints | Public endpoints |
| **Data Visibility** | Only authorized participants | Anyone | Anyone |
| **Transaction Submission** | Authorized users | Authorized users / Anyone | Anyone |
| **Contract Deployment** | Authorized users | Authorized users / Anyone | Anyone |
| **Validator Entry** | Permission required | Permission required | Anyone (with stake) |
| **Performance** | High | High | Medium |
| **Governance** | Centralized/Hybrid | Centralized/Hybrid | Decentralized |

> **Note**: Permissioned Private refers to "Walled Garden" approach where data visibility is restricted.

## Avalanche L1s: Flexible by Design

What makes Avalanche L1s powerful is their flexibility to implement any of these models:

- **Permissioned Private L1**: Configure validator manager with a fixed set of validators and restrict RPC access
- **Permissioned Public L1**: Use Proof of Authority with controlled validator additions
- **Permissionless L1**: Implement Proof of Stake where anyone can become a validator by staking

The ValidatorManager contract you'll learn about in this course is the key component that enables this flexibility.

## Choosing the Right Model

When deciding between these models, consider:

1. **Regulatory Requirements**: Do you need to comply with KYC/AML regulations?
2. **Performance Needs**: Private/permissioned typically offer higher throughput
3. **Trust Model**: Can you trust a closed set of validators, or do you need economic security?
4. **Transparency Requirements**: Does your use case require public auditability?
5. **Participant Control**: Do you need to control who can interact with your blockchain?

<Quiz quizId="411"/>


# Proof of Authority (/academy/permissioned-l1s/02-proof-of-authority/02-proof-of-authority)

---
title: Proof of Authority
description: Understanding Proof of Authority as a sybil protection mechanism
updated: 2025-07-29
authors: ["nicolasarnedo"]
icon: BookOpen
---

## What is Proof of Authority?

Proof of Authority (PoA) is a sybil protection mechanism that centralizes the power of controlling who can validate the network to one account (EoA or multi-sig). 

Instead of requiring validators to stake tokens (like in Proof of Stake) or solve computational puzzles (like in Proof of Work), PoA leverages the real-world identity and reputation of validators.

<Callout type="info">
**Consensus & Sybil Protection Differences** 

Sybil protection mechanisms (like PoA, PoW, PoS) determine *who* can participate in validation, while consensus mechanisms (like Nakamoto consensus, Snowman) determine *how* validators agree on the blockchain state. 

They work together - PoA decides who validates, then those validators use a consensus mechanism to agree.
</Callout>

Using Proof of Authority as your sybil protection mechanism will lead to creating, what we know as, private or permissioned blockchains. They are particularly suitable for creating enterprise environments for regulated industries where validators are known entities.

## How Validators Work in PoA

In PoA, validators are selected based on their identity and reputation rather than their economic stake. This fundamental difference creates a unique dynamic:

1. **Known Entities**: Validators are either operated by the company that created the blockchain or by trusted third-party organizations participating in the network.
2. **Reputation-Based Accountability**: While the blockchain protocol doesn't enforce penalties (like slashing), validators risk damaging their real-world reputation and business relationships if they misbehave.

PoA validators perform the same duties as validators in any other blockchain (producing blocks, validating transactions, maintaining state, and participating in consensus) - they just don't receive rewards or face on-chain penalties for their behavior.

### Weight-Based Influence

In Avalanche's PoA implementation, validators can have different weights:
- Higher weight = more influence in consensus decisions
- Admin can adjust weights based on validator performance or trust level
- Enables flexible governance within the PoA framework

## When to Use PoA

PoA is the ideal sybil protection mechanism when:

- **Known Participants**: All validators can be identified and vetted
- **Trust Exists**: There's an existing trust relationship or legal framework
- **Regulatory Compliance**: Regulations require known validator identities
- **Private Networks**: The blockchain serves a specific consortium or organization
- **Performance Matters**: High throughput is more important than decentralization

PoA trades decentralization for efficiency and compliance. It's not suitable for public, permissionless networks where trustless operation is required.

<Quiz quizId="412"/>

# Validator Manager Contract (/academy/permissioned-l1s/02-proof-of-authority/03-validator-manager-contract)

---
title: Validator Manager Contract 
description: Understanding PoA validator management contracts
updated: 2025-07-28
authors: [nicolasarnedo]
icon: BookOpen
---
import { Steps, Step } from 'fumadocs-ui/components/steps';

The contracts in the [`validator-manager`](https://github.com/ava-labs/icm-contracts/tree/main/contracts/validator-manager) branch define the Validator Manager used to manage Subnet-only Validators. 

For this section we have blurred out some of the contracts, as these are not relevant to the Proof of Authority hierarchy used to create a **permissioned L1**:

<div style={{ display: 'flex', justifyContent: 'center', margin: '2rem 0' }}>
  <Mermaid
    chart="
classDiagram
class ACP99Manager {
    +initializeValidatorSet()
    +completeValidatorRegistration()
    +completeValidatorRemoval()
    +completeValidatorWeightUpdate()
    -_initiateValidatorRegistration()
    -_initiateValidatorRemoval()
    -_initiateValidatorWeightUpdate()
}
<<Abstract>> ACP99Manager

class ValidatorManager {
    +initializeValidatorSet()
    +completeValidatorRegistration() onlyOwner
    +completeValidatorRemoval() onlyOwner
    +completeValidatorWeightUpdate() onlyOwner
    +initiateValidatorRegistration() onlyOwner
    +initiateValidatorRemoval() onlyOwner
    +initiateValidatorWeightUpdate() onlyOwner
}

ACP99Manager <|-- ValidatorManager
"
  />
</div>


## Understanding Contract Hierarchy

The validator management system follows a layered architecture, with each level adding specific functionality:

### ACP99Manager (Abstract Foundation)

The `ACP99Manager` is the foundational abstract contract that standardizes validator management for EVM-based L1s, as defined in ACP-99. This standard emerged after ACP-77 introduced the protocol-level capability for L1s to manage their own validators. ACP99Manager provides four essential functions that all validator managers must implement:

- **`initializeValidatorSet()`**: Establishes the initial validator set when converting an existing Subnet to an L1
- **`completeValidatorRegistration()`**: Finalizes validator addition after P-Chain confirmation
- **`completeValidatorRemoval()`**: Finalizes validator removal after P-Chain confirmation
- **`completeValidatorWeightUpdate()`**: Finalizes weight changes after P-Chain confirmation

These functions handle the critical interactions with the P-Chain through Warp messages, forming the backbone of cross-chain validator management.

### ValidatorManager (Concrete Implementation)

The `ValidatorManager` extends `ACP99Manager` and adds the complete validator lifecycle management:

**Core Additions:**
- **`initiateValidatorRegistration()`** (onlyOwner): Starts the process of adding a new validator
- **`initiateValidatorRemoval()`** (onlyOwner): Begins removing a validator from the active set
- **`initiateValidatorWeightUpdate()`** (onlyOwner): Initiates changes to a validator's voting weight

**Key Features:**
- All state-changing functions are protected with `onlyOwner` modifier
- Implements the two-phase commit pattern: initiate → complete
- Manages churn rate limiting to prevent rapid validator set changes
- Tracks validator states throughout their lifecycle
- Handles Warp message construction and verification

<Quiz quizId="413" />


# Etna Upgrade (optional) (/academy/permissioned-l1s/02-proof-of-authority/04-etna-upgrade)

---
title: Etna Upgrade (optional)
description: Understanding ACP77 & ACP99
updated: 2025-07-28
authors: [nicolasarnedo]
icon: BookOpen
---

This section is **not necessary for understanding and running permissioned L1s** but provides an insight on the improvements and evolution of Avalanche, *feel free to skip if not interested*.

## Etna Upgrade: Making L1s More Accessible

The Etna upgrade, implemented through [ACP-77](https://github.com/avalanche-foundation/ACPs/tree/main/ACPs/77-reinventing-subnets), represents a fundamental shift in how Avalanche approaches network creation and validation costs.

### Why Etna Was Necessary

Before Etna, launching a Subnet (now called L1) was prohibitively expensive:
- **High Capital Requirements**: Each validator needed to stake 2,000 AVAX (approximately $70,000 at the time)
- **Minimum Validator Costs**: With at least 8 validators recommended, projects needed $560,000+ just to launch
- **Primary Network Burden**: Validators had to sync and validate the entire Primary Network (X-Chain, P-Chain, and C-Chain), requiring substantial hardware resources
- **Regulatory Barriers**: Organizations that couldn't validate permissionless chains were completely blocked from participating

![Post Etna Upgrade](/common-images/permissioned-l1s/PostEtnaUpgrade.png)

### What Etna Changed

The upgrade introduced a continuous fee model that dramatically reduces costs:
- **Reduced Running Costs**: Validators now pay approximately 1.33 AVAX per month instead of staking 2,000 AVAX
- **No Primary Network Validation**: L1 validators only need to sync the P-Chain, significantly reducing hardware requirements
- **Pay-As-You-Go**: The continuous fee adjusts based on network usage, similar to cloud services
- **Regulatory Flexibility**: Organizations can now run L1s without validating the permissionless C-Chain

This transformation makes it feasible for startups, enterprises, and institutions to launch their own sovereign blockchains on Avalanche, opening the door to a new wave of innovation in permissioned and regulated blockchain applications.

## Evolution: From ACP-77 to ACP-99

While ACP-77 revolutionized how L1s work at the protocol level, it left one important question unanswered: How should smart contracts actually implement validator management? This is where ACP-99 comes in.

### The Gap ACP-77 Left

ACP-77 provided:
- **Protocol-level capabilities**: New P-Chain transactions and Warp message formats
- **The mechanism**: How L1s can send messages to update their validator sets
- **The foundation**: Basic rules for validator management

But it didn't specify:
- How to structure the smart contracts
- What functions and events to expose
- How to handle the complexity in a standardized way

### ACP-99: The Standardization Layer

ACP-99 fills this gap by defining a standard Solidity contract specification:

**Why Standardization Matters:**
- **Reduced Development Time**: L1 creators don't need to design from scratch
- **Security**: One audited implementation can benefit many L1s
- **Interoperability**: Tools and services can work with any ACP-99 compliant L1
- **Best Practices**: Encodes lessons learned into a reusable standard

**The Three-Layer Architecture:**
1. **ACP99Manager**: Abstract contract defining the standard interface
2. **ValidatorManager**: Concrete implementation with owner controls
3. **Access Control Layer** (like PoAManager): Defines who can manage validators

This progression from ACP-77 (protocol capability) to ACP-99 (standardized implementation) mirrors successful patterns in blockchain development.

# Subnet Creation (/academy/permissioned-l1s/03-create-an-L1/01-create-subnet)

---
title: Subnet Creation
description: A quick review of creating a Subnet on Avalanche - the foundation for our permissioned L1
updated: 2025-03-19
authors: [nicolasarnedo]
icon: Terminal
---

import { Step, Steps } from 'fumadocs-ui/components/steps';
import { Button } from '@/components/ui/button';
import ToolboxMdxWrapper from "@/components/toolbox/academy/wrapper/ToolboxMdxWrapper.tsx";
import AvalancheGoDocker from "@/components/toolbox/console/layer-1/AvalancheGoDockerL1";
import CreateChain from "@/components/toolbox/console/layer-1/create/CreateChain";

In the [Avalanche Fundamentals course](/academy/avalanche-fundamentals), you learned how to quickly set up an L1 using the [Developer Console](https://build.avax.network/tools/l1-toolbox). This section provides an in depth review of that flow, understanding what comes pre-configured in our genesis, and laying the foundation for what we will need for our Permissioned L1.

## Creating a Subnet

Let's create a fresh new Subnet that we can use during this course to test all of the tools and flows for managing Permissioned L1s.

<Steps>
<Step>

### Create Builder Account & Fund Wallet

Before creating your Subnet, we recommend setting up an Avalanche Builder Account for easier access to testnet resources.

<Button target="_blank" href="/login">Create Avalanche Builder Account</Button>

**Benefits of a Builder Account:**
- **Faucet**: C-Chain and P-Chain Testnet AVAX directly sent to your account without needing to claim
- **Free Managed Testnet Infrastructure**: Access free managed testnet nodes and ICM relayers for your L1
- **No Docker Required**: Launch and manage nodes directly from the Builder Console without local setup

After creating your account:
1. [Download Core Wallet](https://core.app/) if not already installed
2. Set Core to Testnet mode (upper-right toggle button)
3. Visit the [Builder Console](/console) to claim test AVAX on both C-Chain and P-Chain

</Step>
<Step>

### Create Subnet and Blockchain Records

Create the Subnet by issuing two transactions on the P-Chain (hence the need for test AVAX on the P-chain).

These transactions are:
1. `CreateSubnetTx` - Creates a Subnet identified by the transaction hash
2. `CreateChainTx` - Adds a blockchain to the Subnet

For this guide, we will create our blockchain as an **uncustomized EVM** so you just need to rename it (if you want). 

On **Step 2: Create a Chain** select the *Genesis JSON* tab to the right and skim through it. No need to understand it all but good to get familiar with it before the next section.

<ToolboxMdxWrapper walletMode="c-chain">
    <CreateChain embedded={true} />
</ToolboxMdxWrapper>

**Key Parameters:**
- **Subnet Owner**: P-chain address of your connected wallet
- **Chain Name**: Your blockchain's name
- **VM ID**: Default value `srEX...Dy` when creating with an uncustomized VM
- **Genesis Data**: Initial blockchain configuration

</Step>
<Step>

### Set Up Validator Node

Launch a node to track your Subnet. This node will become a validator for your Subnet, and later will be managed by the Validator Manager contract when we convert to L1.

Use our *free managed testnet infrastructure* - no Docker installation or AWS account required:

<ToolboxMdxWrapper walletMode="testnet-mainnet">
    <CreateManagedTestnetNode />
</ToolboxMdxWrapper>

**Managing Your Nodes**

After creating nodes, you can view and manage them at the [Testnet Infrastructure Console](/console/testnet-infra/nodes).

<Callout type="warning">
Managed nodes automatically shut down after 3 days. For production or extended testing, see the self-hosted option below.
</Callout>

### Production & Extended Testing Environments

For production environments or extended testing periods, you should use Docker to run your nodes.

**Docker Setup Guide:**

<ToolboxMdxWrapper walletMode="testnet-mainnet">
    <AvalancheGoDocker />
</ToolboxMdxWrapper>

</Step>
</Steps>

## Key Takeaways

- **P-Chain Registry**: All validators and blockchains are registered on the P-Chain
- **Subnet Foundation**: Your Subnet provides the blockchain infrastructure necessary for this course
- **Managed Infrastructure or Self-Hosted**: Builder Hub provides free managed testnet nodes,
  eliminating the need for Docker or AWS setup - you can also choose to run it yourself.

## Optional Alternative: Self-Hosted Infrastructure

The free managed testnet nodes are a great option for playing around with Avalanche L1s, but are not
intended for running on production environments. They are shut down automatically after 3 days. If you want to test out your production environment, running beyond 3 days, or anything more complex you should run nodes on your own infrastructure
using Docker:

<ToolboxMdxWrapper walletMode="testnet-mainnet">
    <AvalancheGoDocker />
</ToolboxMdxWrapper>



# Transparent Proxy (/academy/permissioned-l1s/03-create-an-L1/02-transparent-proxy)

---
title: Transparent Proxy
description: In-depth guide of the Transparent Proxy smart contract structure flows
updated: 2025-01-10
authors: [nicolasarnedo]
icon: BookOpen
---

Before we get into understanding the *genesis.json* we have deployed, it is important we fully understand this proxy pattern, as it plays an important role in updating and using the **Validator Manager contract**.

### Key Components
- **TransparentUpgradeableProxy**: Main proxy with immutable admin address for gas efficiency
- **ProxyAdmin**: Administrative contract managing upgrades through ownership transfer capability
- **Implementation**: Contains actual business logic, upgradeable via ProxyAdmin

## Admin Flow

Admins can only call upgrade functions. All other calls are blocked to prevent selector clashes.

<Mermaid
  chart="
sequenceDiagram
    participant Admin
    participant ProxyAdmin
    participant TransparentProxy
    participant NewImplementation

    Admin->>ProxyAdmin: upgradeAndCall(proxy, newImpl, data)
    ProxyAdmin->>TransparentProxy: upgradeToAndCall(newImpl, data)
    TransparentProxy->>TransparentProxy: _dispatchUpgradeToAndCall()
    TransparentProxy->>NewImplementation: delegatecall(data) [if data provided]
"
/>

## User Flow

Regular users can call any function except upgrade functions, which are delegated to the implementation contract.

<Mermaid
  chart="
sequenceDiagram
    participant User
    participant TransparentProxy
    participant Implementation

    User->>TransparentProxy: call someFunction()
    Note over TransparentProxy: msg.sender != admin
    TransparentProxy->>Implementation: delegatecall(someFunction())
    Implementation-->>TransparentProxy: return result
    TransparentProxy-->>User: return result
"
/>


# Genesis Breakdown (/academy/permissioned-l1s/03-create-an-L1/03-genesis-breakdown)

---
title: Genesis Breakdown
description: Deep dive into the genesis file structure & why we need to initialize the chain with predeployed contracts
updated: 2025-03-19
authors: [nicolasarnedo]
icon: BookOpen
---

### What is a genesis file?

The genesis file defines the very first block of your Subnet-EVM chain and its initial state. It enables EVM features, sets economic parameters (fees and gas), fixes the start time, etc...

Additionally, in the context of Avalanche, it is **set by default to pre-deploy well-known contracts**. Lets take a look at which ones:

## Predeployed Contracts & Allocation

The `alloc` section seeds balances and deploys bytecode at fixed addresses before block 0, so they exist from the first block. 

- **BLOCKCHAIN_DEPLOYER_ADDRESS** - Subnet Owner Balance: `0xd3c21bcecceda1000000` wei = 1,000,000 native tokens (1e6 × 1e18) useful for funded deployer/faucet account

- **TransparentUpgradeableProxy** *(0xfacade00...00)* — Proxy bytecode that delegates calls to an implementation and is controlled by an admin. Storage slots (EIP‑1967) predefined in the contract:
    - `0x3608…bbc` (implementation): `0x1212121212121212121212121212121212121212` (placeholder implementation address)
    - `0xb531…103` (admin): `0xdad0000000000000000000000000000000000000` (the Proxy Admin address below).

- **Proxy Admin** *(0xdad00...00)* — Owns and manages upgrades of the proxy at `0xfacade…`

<div style={{ display: 'flex', justifyContent: 'center', margin: '2rem 0' }}>
  <img src="/common-images/permissioned-l1s/VMCGenesis.png" alt="VMC Proxy Deployment" style={{ width: '60%', height: 'auto' }} />
</div>

Additional contracts are also deployed by default (*multicall3, create2, wrapped native tokens...*), but we will not dive into them in this guide as they are not essential for understanding permissioned L1s.

## Why Pre-Deploy Proxy Contracts

Deploying the proxy contract in genesis provides three critical benefits:

#### 1. Known Address Requirement

By deploying in genesis, we can set an arbitrary contract address (`0xfacade…`). This is essential because the `convertSubnetToL1` transaction requires the Validator Manager address as a parameter:

```solidity
type ConvertSubnetToL1Tx struct {
    // ...other fields...
    // Address of the Subnet manager (the proxy at 0xfacade...)
    Address types.JSONByteSlice `serialize:"true" json:"address"`
}
```

#### 2. P-Chain Transaction Size Limits

Contracts are pre-deployed by including their bytecode in the genesis file, which is recorded as part of the `CreateChainTx` on the P-Chain. All P-Chain transactions have a size limit (to prevent DoS attacks) making space precious. 

While we could deploy the full Validator Manager directly in genesis, it would consume significant space. The proxy contract is much smaller, leaving room for other essential contracts.

#### 3. Upgradability

The proxy pattern enables updating the Validator Manager implementation if bugs are discovered. Since the subnet owner address on the P-Chain cannot be changed after conversion, using a proxy is the only way to update the implementation without requiring a full network upgrade.

The proxy will later be upgraded to point to the actual VMC implementation after conversion—more on this in the [Validator Manager Deployment](/academy/permissioned-l1s/04-validator-manager-deployment/01-vmc-deployment-intro) section.

### Appendix: Predeployed Contracts Structure

Here you can see the contracts we just mentioned and how they relate:

<div style={{ display: 'flex', justifyContent: 'center', margin: '2rem 0', width: '100%' }}>
  <div style={{ width: '90%', maxWidth: '1200px' }}>
    <Mermaid
      chart="
graph TD
  A[facade - TransparentUpgradeableProxy] --> B[0x1212... implementation placeholder]
  C[dad... ProxyAdmin] --> A
  G[CREATE2 Deployer] --> H[User contracts]
  I[Multicall3] --> H
  J[WNT] <--> K[Native token]
  
  A -.->|delegatecall| B
  C -.->|admin-of| A
  G -.->|deterministic deploys| H
  I -.->|batch read/exec| H
"
    />
  </div>
</div>



# Convert Subnet to L1 (/academy/permissioned-l1s/03-create-an-L1/04-convert-subnet-to-l1)

---
title: Convert Subnet to L1
description: Transform your Subnet into a sovereign L1 with Validator Manager contract integration
updated: 2025-07-31
authors: [nicolasarnedo]
icon: Terminal
---

Now that you understand where to deploy your Validator Manager Contract (VMC), and you [created a Subnet](/academy/permissioned-l1s/03-create-an-L1/01-create-subnet) with at least one validator node, it's time to convert your Subnet into a sovereign L1. 

This process establishes the VMC as the authority for validator management on your blockchain and is **irreversible**, once converted to L1, you cannot revert to Subnet status.

## Conversion Process

The conversion from Subnet to L1 is a one-time, irreversible process that:

- **Establishes Sovereignty**: Your blockchain becomes independent with its own validator set
- **Transfers Authority**: Validator management shifts from P-Chain to your VMC

## Key Parameters

1. **Subnet ID**: The unique identifier of your Subnet (from the `CreateSubnetTx` transaction hash)

2. **Validator Manager Blockchain ID**: The blockchain where your VMC will be deployed (Your L1, C-Chain, Another L1)

3. **Validator Manager Address**: The address of the validator manager contract (or proxy) that will manage the L1's validator set. Chains created with Developer Console have a pre-deployed proxy at `0xfacade0000000000000000000000000000000000`.

4. **Initial Validators**: The validators that will form your L1's initial validator set. Add the validator we just spun up in the Create a Subnet section.

<ToolboxMdxWrapper walletMode="c-chain">
    <ConvertToL1 />
</ToolboxMdxWrapper>

You just converted your Subnet to an L1  - **Congratulations!** The following sections will guide you through deploying and configuring your Validator Manager Contract.

## Appendix: Conversion Flow

<Mermaid
  chart="
sequenceDiagram
    participant User
    participant PChain as P-Chain
    participant VMC as VMC Chain
    participant PChainState as P-Chain State

    User->>PChain: ConvertSubnetToL1Tx<br/>Contains: SubnetID, ChainID, Address, Validators, SubnetAuth
    PChain->>PChain: SyntacticVerify()
    PChain->>PChain: Verify subnet authorization
    PChain->>PChain: Calculate fees & validate balance
    PChain->>VMC: Create L1Validators<br/>For each validator: ValidationID, NodeID, Weight, Balance, etc.
    VMC->>PChain: SetSubnetToL1Conversion()
    PChain->>PChainState: Store ConversionID, ChainID, Address mapping
    PChain->>PChain: Generate ConversionID<br/>Hash of SubnetToL1ConversionData
    Note right of PChain: No direct call - VMC reads P-Chain state
    VMC->>PChainState: VMC can query conversion data via P-Chain APIs
"
/>

 

# Query L1 Details (/academy/permissioned-l1s/03-create-an-L1/05-query-l1-details)

---
title: Query L1 Details
description: Learn how to query L1 details on the P-Chain.
updated: 2025-03-13
authors: [owenwahlgren]
icon: Terminal
---

import QueryL1Details from "@/components/toolbox/academy/permissioned-l1s/QueryL1Details.tsx"
import ToolboxMdxWrapper from "@/components/toolbox/academy/wrapper/ToolboxMdxWrapper.tsx"

<ToolboxMdxWrapper walletMode="C-chain">
    <QueryL1Details />
</ToolboxMdxWrapper>

To query the L1 details, you can use the [Data API from AvaCloud](https://developers.avacloud.io/data-api/primary-network/get-subnet-details-by-id).


# Introduction (/academy/permissioned-l1s/04-validator-manager-deployment/01-vmc-deployment-intro)

---
title: Introduction
description: Learn the deployment flow and understand the logic behind it
updated: 2025-07-31
authors: [nicolasarnedo]
icon: Book
---

## Current Infrastructure State

By now, we have:
- **Created a Subnet-EVM L1** with its genesis file
- **Pre-deployed proxy infrastructure** at addresses `0xfacade...` (proxy) and `0xdad...` (admin)
- **Placeholder implementation** at `0x1212...` waiting to be upgraded

If we were to look at our L1, it would like something like this:

![Validator Manager Deployment Layout](/common-images/permissioned-l1s/VMCDeploy1.png)

## Deployment Flow

The deployment process follows a specific sequence designed for safety and clarity:

1. **Deploy the Validator Manager implementation** - Create the actual contract with validation logic
2. **Upgrade the proxy** - Point `0xfacade...` to our new implementation via the admin at `0xdad...`
3. **Initialize the configuration** - Set up the initial validator set and permissions
4. **Activate validation** - Enable the contract to start managing validators on the P-Chain

# Deploy Validator Manager (/academy/permissioned-l1s/04-validator-manager-deployment/02-deploy-validator-manager)

---
title: Deploy Validator Manager
description: Deploy and configure the Validator Manager implementation contract
updated: 2025-07-31
authors: [nicolasarnedo]
icon: Terminal
---

import ToolboxMdxWrapper from "@/components/toolbox/academy/wrapper/ToolboxMdxWrapper.tsx"
import DeployValidatorManager from "@/components/toolbox/console/permissioned-l1s/validator-manager-setup/DeployValidatorManager.tsx"

First you will need to deploy the actual Validator Manager implementation that contains the logic for managing validators. 

Building on the image shown in the introduction, now our L1 will have these contracts deployed:

![Validator Manager Deployment](/common-images/permissioned-l1s/VMCDeploy2.png)

## Implementation Contract

The Validator Manager implementation:
- Contains all validator management logic
- Implements the ACP99Manager standard
- Handles P-Chain communication
- Can be upgraded without losing state

## Validator Messages Library

The ValidatorManager contract requires a separate library contract called **ValidatorMessages** to be deployed first. This library handles all the message encoding and decoding for communication with the P-Chain.

**Why a separate library?**
- Solidity requires libraries to be deployed independently before they can be linked
- The ValidatorManager bytecode contains placeholders that get replaced with the library's deployed address
- This allows multiple validator managers to share the same message handling code

**What it does:**
- Packs validator registration messages for the P-Chain
- Unpacks responses from the P-Chain 
- Handles weight updates and conversion messages
- Ensures consistent message formatting across all validator operations

<Callout type="info">
The library deployment is a one-time operation - once deployed, multiple validator manager contracts can reference the same library instance.
</Callout>

## Deploy the Implementation

<ToolboxMdxWrapper walletMode="l1">
    <DeployValidatorManager />
</ToolboxMdxWrapper>


# Upgrade Proxy (/academy/permissioned-l1s/04-validator-manager-deployment/03-upgrade-proxy)

---
title: Upgrade Proxy
description: Learn how to point your proxy contract to the Validator Manager implementation
updated: 2025-07-31
authors: [nicolasarnedo]
icon: Terminal
---

import UpgradeProxy from "@/components/toolbox/console/permissioned-l1s/validator-manager-setup/UpgradeProxy.tsx"

After deploying both the validator manager contract, we will need to link them by upgrading the proxy to point to your Validator Manager implementation.

Since the **ProxyAdmin** contract was deployed through the genesis with the deployer address set to the owner of the contract, we will call the *upgradeToAndCall()* function.

![Validator Manager Deployment Upgrade Proxy Part 1](/common-images/permissioned-l1s/VMCDeploy3.png)

This will cause the **TransparentUpgradeableProxy** contract to (via *delegatecall*) call our newly deployed **Validator Manager** contract, instead of the empty contract it previously had set by default.

![Validator Manager Deployment Upgrade Proxy Part 2](/common-images/permissioned-l1s/VMCDeploy4.png)

## Perform the Upgrade

- **Proxy Address**: set to 0xfacade...
- **ProxyAdmin Address**: set to 0xdad....
- **Desired Implementation**: set to address of deployed Validator Manager contract on your L1
- **Current Implementation**: set to 0x121212...212

<Callout type="info">
Make sure you have your L1 selected in the wallet component below
</Callout>

<UpgradeProxy />


# Set Initial Configuration (/academy/permissioned-l1s/04-validator-manager-deployment/04-set-initial-configuration)

---
title: Set Initial Configuration
description: Configure your Validator Manager with initial parameters
updated: 2025-07-31
authors: [nicolasarnedo]
icon: Terminal
---
import ToolboxMdxWrapper from "@/components/toolbox/academy/wrapper/ToolboxMdxWrapper.tsx"
import Initialize from "@/components/toolbox/console/permissioned-l1s/validator-manager-setup/Initialize.tsx"

Setting the initial configuration is a critical step that establishes how your Validator Manager will operate. 

This process involves calling the `initialize` function through the **TransparentUpgradeableProxy**, which forwards the call to your ValidatorManager implementation.

![Validator Manager Deployment Initialize](/common-images/permissioned-l1s/VMCDeploy5.png)

## How Initialization Works

### The Initialize Function

The configuration is set by calling `initialize()` with a `ValidatorManagerSettings` struct. This call:
- Goes through the proxy at `0xfacade...` (not directly to the implementation)
- Can only be called once due to OpenZeppelin's `initializer` modifier
- Sets up the ownership structure and operational parameters

## Configuration Parameters

The `ValidatorManagerSettings` struct contains four essential parameters:

1. **Admin Address**: The account that controls validator management operations (your connected wallet). Can be changed through ownership transfer.
2. **Subnet ID**: Links the Validator Manager to your specific L1 & can't be changed after initialization.
3. **Churn Period Seconds**:Time window for tracking validator set changes (must be ≤ 86400 seconds)
4. **Maximum Churn Percentage**: Limits how much validator weight can change per period (1-20% protocol maximum). 
*Example*: 20% means max 1/5 of total weight can change

## Set Configuration

<ToolboxMdxWrapper walletMode="l1">
    <Initialize />
</ToolboxMdxWrapper>


# Initialize Validator Set (/academy/permissioned-l1s/04-validator-manager-deployment/05-initialize-validator-set)

---
title: Initialize Validator Set
description: Set up the initial validator set when converting a subnet to an L1
updated: 2025-07-31
authors: [nicolasarnedo]
icon: Terminal
---
import ToolboxMdxWrapper from "@/components/toolbox/academy/wrapper/ToolboxMdxWrapper.tsx"
import InitValidatorSet from "@/components/toolbox/console/permissioned-l1s/validator-manager-setup/InitValidatorSet.tsx"

When converting an existing subnet to an L1 with sovereign validator management, you need to initialize the Validator Manager with the current validator set. This one-time operation bridges P-Chain subnet creation with L1 validator management using cryptographically verified conversion data.

![Validator Manager Deployment Initialize Validator Set](/common-images/permissioned-l1s/VMCDeploy6.png)

## How initializeValidatorSet Works

### Function Implementation

You can view the full source code of the `initializeValidatorSet` function here: [ValidatorManager.sol#L211](https://github.com/ava-labs/icm-contracts/blob/ce85313c71f90282b390e685cb652e9b0150a4ae/contracts/validator-manager/ValidatorManager.sol#L211)

Here you will find pseudo-code that covers the main logic in the function:
```
initializeValidatorSet(conversionData, messageIndex):
    // 1. Validation Checks
    CHECK validator set not already initialized
    VERIFY blockchain ID matches current chain
    VERIFY validator manager address is correct
    
    // 2. P-Chain Message Verification
    GET conversion ID from P-Chain Warp message at messageIndex
    COMPUTE hash of provided conversion data
    VERIFY hashes match (ensures data integrity)
    
    // 3. Process Initial Validators
    totalWeight = 0
    FOR each validator in conversionData.initialValidators:
        validationID = sha256(subnetID + validator_index)
        
        VALIDATE node ID format and check for duplicates
        REGISTER validator with "Active" status
        STORE validation period data (weight, start time, etc.)
        ADD to total weight
        EMIT registration event
    
    // 4. Final Validation
    ENSURE total weight meets minimum churn requirements
    
    // 5. Complete Initialization
    MARK validator set as initialized (permanent flag)
```

### P-Chain Integration & Aggregated Signatures

The initialization leverages Avalanche Warp Messaging for security:

1. **P-Chain Validators Sign** - The subnet's validators collectively sign the conversion data
2. **Aggregated Signature** - Creates a threshold signature proving consensus
3. **Warp Precompile Verifies** - The signature is verified before the contract receives it
4. **Contract Validates** - Additional checks ensure data integrity

The conversion ID is derived through:
```solidity
bytes32 conversionID = keccak256(abi.encode(conversionData));
```

This ID must match the one in the P-Chain signed message, ensuring data hasn't been tampered with.

## Understanding Conversion Data

The conversion data structure used by the function:

```solidity
struct ConversionData {
    bytes32 subnetID;                      // Your L1's subnet identifier
    bytes32 validatorManagerBlockchainID;  // Blockchain ID where VM is deployed  
    address validatorManagerAddress;       // This validator manager contract (0xfacade...)
    InitialValidator[] initialValidators;  // Array of current validators
}

struct InitialValidator {
    bytes nodeID;        // Validator's P-Chain node ID (e.g., "NodeID-...")
    bytes blsPublicKey;  // BLS public key for signature verification
    uint64 weight;       // Validator's voting weight
}
```

### Required Information

To initialize, you'll need:
- **Conversion Data**: Current validator information from P-Chain
- **Message Index**: Position in the Warp message queue
- **Proper Timing**: Must be done before other operations

<Callout type="warning">
Initialization can only be done once! Make sure you have the correct validator data before proceeding.
</Callout>

## Initialize Validator Set

<ToolboxMdxWrapper walletMode="l1">
    <InitValidatorSet />
</ToolboxMdxWrapper>

## Next Steps

Congratulations! You just set up your first **Permissioned L1**! In the next chapter you will learn how to manage this validator set:
1. Query the validator set to verify state
2. Add, Chnage Weight & Remove Validators


# Read Deployed VMC (/academy/permissioned-l1s/04-validator-manager-deployment/06-check-contract)

---
title: Read Deployed VMC
description: Check the Validator Manager Contract.
updated: 2025-03-13
authors: [owenwahlgren]
icon: Terminal
---

import ToolboxMdxWrapper from "@/components/toolbox/academy/wrapper/ToolboxMdxWrapper.tsx"
import ReadContract from "@/components/toolbox/console/permissioned-l1s/validator-manager-setup/ReadContract.tsx"

Here you can double check that the `ValidatorManager` contract has been deployed and initialized correctly.

Specifically, you can check the `totalWeight`, `admin`, `subnetID`, `churnPeriodSeconds`, and `maximumChurnPercentage` variables.

<ToolboxMdxWrapper  walletMode="l1">
    <ReadContract />
</ToolboxMdxWrapper>


# Introduction (/academy/permissioned-l1s/05-validator-manager-operations/01-introduction)

---
title: Introduction
description: Outline of chapter contents
updated: 2025-03-19
authors: [nicolasarnedo]
icon: Book
---

This chapters covers the end-to-end validator lifecycle on a permissioned L1 managed by the `ValidatorManager` contract. For this, we will learn all of the operations available, understand the theory and demo it using the [Toolbox](https://build.avax.network/tools/l1-toolbox):

- Add a validator (initiate on L1, register on P-Chain, complete on L1)
- Change validator weight (churn-aware updates)
- Remove a validator (initiate on L1, remove on P-Chain, complete on L1)
- Disable on P-Chain for emergency/operational purposes

In order to fully understand these operations, it is a good reminder to see this diagram again, from the [ICM for Validator Manager Contracts](/academy/permissioned-l1s/01-introduction/02-interop), as we will dive deep into why and how these communication flows actually work/

![VMC & P-Chain Communication Flow](/common-images/permissioned-l1s/VmcPchainFlow.png)

## Key Concept Reminder

The **P-Chain** serves as the **single source of truth for all validator** operations across the Avalanche network. While your Validator Manager contract initiates operations and tracks state changes, the P-Chain ultimately determines which validators are active and recognized by the network. 


# Query the Validator Set (/academy/permissioned-l1s/05-validator-manager-operations/02-query-validator-set)

---
title: Query the Validator Set
description: Get info on validators for an L1.
updated: 2025-03-13
authors: [owenwahlgren]
icon: Terminal
---


### Query the Validator Set

Before getting into understanding and executing validator manager operations, let's take a look at our current Validator set.

Feel free to come back to this step after [adding a validator](/academy/permissioned-l1s/05-validator-manager-operations/04-add-validator-demo), [changing weight](/academy/permissioned-l1s/05-validator-manager-operations/04-add-validator-demo) or [removing it](content/academy/permissioned-l1s/05-validator-manager-operations/08-remove-validator-demo) to verify the changes have applied.

import ToolboxMdxWrapper from "@/components/toolbox/academy/wrapper/ToolboxMdxWrapper.tsx"
import QueryL1ValidatorSet from "@/components/toolbox/console/permissioned-l1s/QueryL1ValidatorSet.tsx"

<ToolboxMdxWrapper walletMode="C-chain">
    <QueryL1ValidatorSet />
</ToolboxMdxWrapper>


# Add Validator (/academy/permissioned-l1s/05-validator-manager-operations/03-add-validator)

---
title: Add Validator
description: Theory walkthrough of adding a validator with ValidatorManager
updated: 2025-03-19
authors: [nicolasarnedo]
icon: BookOpen
---

## Adding a Validator

We’re adding a validator in a PoA setup where the `ValidatorManager` contract is owned by your connected wallet and deployed on your L1. The process has two L1 calls with a P-Chain registration in between.

### Phase 1: Initiation (L1)

First we will call [`initiateValidatorRegistration(nodeID, blsPublicKey, remainingBalanceOwner, disableOwner, weight)`](https://github.com/ava-labs/icm-contracts/blob/ce85313c71f90282b390e685cb652e9b0150a4ae/contracts/validator-manager/ValidatorManager.sol#L328) on `ValidatorManager`.

Under the hood, the contract:
- Validates sizes and formats (20-byte `nodeID`, 48-byte `blsPublicKey`, owners, churn limits)
- Builds a `RegisterL1ValidatorMessage` with a bounded expiry
- Computes a unique `validationID`
- Stores pending state mapping `nodeID → validationID`
- Interacts with ICOM to create a warp message that can be submitted to the P-Chain

### Phase 2: P-Chain Processing

We then will sign and submit the `RegisterL1ValidatorMessage` warped response we got from the last step to the P-Chain, this executes a `RegisterL1ValidatorTx`, and upon success signs and returns an `L1ValidatorRegistrationMessage` warped response.

The P-Chain processes the following message structure:

```go
// RegisterL1Validator adds a validator to the subnet.
type RegisterL1Validator struct {
	payload

	SubnetID              ids.ID                 `serialize:"true" json:"subnetID"`
	NodeID                types.JSONByteSlice    `serialize:"true" json:"nodeID"`
	BLSPublicKey          [bls.PublicKeyLen]byte `serialize:"true" json:"blsPublicKey"`
	Expiry                uint64                 `serialize:"true" json:"expiry"`
	RemainingBalanceOwner PChainOwner            `serialize:"true" json:"remainingBalanceOwner"`
	DisableOwner          PChainOwner            `serialize:"true" json:"disableOwner"`
	Weight                uint64                 `serialize:"true" json:"weight"`
}
```

### Phase 3: Completion (L1)

We finally will call the [`completeValidatorRegistration(messageIndex)`](https://github.com/ava-labs/icm-contracts/blob/ce85313c71f90282b390e685cb652e9b0150a4ae/contracts/validator-manager/ValidatorManager.sol#L425), where we will pass the message index of the response we received in step 2. The contract verifies it, activates the validator, sets the start time, and emits `CompletedValidatorRegistration`.

Anyone can call `completeValidatorRegistration(messageIndex)` with the signed message.

## Validator Registration Expiry

When registering validators, it's important to understand the **expiry field**:

- **Default Expiry**: Validator registrations expire after **24 hours** by default
- **Completion Required**: If a validator registration is not completed before the expiry time, the registration becomes invalid
- **Pending State**: Expired registrations remain in the pending registrations list in the Validator Manager contracts
- **Cleanup Required**: Expired registrations must be manually removed to keep your validator management system clean

### What Happens When Registrations Expire?

Expired validator registrations can occur due to various reasons:
- **Network connectivity issues** preventing P-Chain registration
- **Configuration errors** in validator node setup
- **Delayed validator setup** taking longer than 24 hours
- **Manual errors** in the registration process

These expired registrations remain in the pending list indefinitely, which can:
- Clutter your validator management interface
- Make it difficult to identify valid pending registrations
- Skew validator count and status reporting

### Managing Expired Registrations

At the end of this chapter, you'll learn how to identify and clean up expired validator registrations using the [Remove Expired Validator Registration tool](/academy/permissioned-l1s/05-validator-manager-operations/09-expired-validator-registration). This tool helps maintain a clean and organized validator management system.

## Appendix: Adding Validator Flow

<Mermaid
  chart="
sequenceDiagram
    participant EOA_Owner as EOA Owner
    participant ValidatorManager as ValidatorManager
    participant WarpMessenger as WarpMessenger (precompile)
    participant PChain as P-Chain

    %% Phase 1: Initiation
    EOA_Owner->>ValidatorManager: initiateValidatorRegistration(nodeID, blsPublicKey, remainingBalanceOwner, disableOwner, weight)

    ValidatorManager->>ValidatorManager: _initiateValidatorRegistration()

    ValidatorManager->>ValidatorManager: Validate parameters<br/>(BLS key, nodeID, owner structs, weight, churn limits)

    ValidatorManager->>ValidatorManager: Create RegisterL1ValidatorMessage<br/>+ registration expiry

    ValidatorManager->>ValidatorManager: Compute validationID

    ValidatorManager->>ValidatorManager: Update internal state<br/>(_validationPeriods, _registeredValidators,<br/>_pendingRegisterValidationMessages)

    ValidatorManager->>WarpMessenger: sendWarpMessage(message)

    %% Phase 2: P-Chain Processing
    WarpMessenger->>PChain: Deliver RegisterL1ValidatorMessage

    PChain-->>WarpMessenger: L1ValidatorRegistrationMessage (signed)

    %% Phase 3: Completion
    participant AnyCaller as Any Caller

    AnyCaller->>ValidatorManager: completeValidatorRegistration(message)

    ValidatorManager->>ValidatorManager: Verify Warp message signature

    ValidatorManager->>ValidatorManager: Update validator status to Active<br/>Set start time

    ValidatorManager-->>AnyCaller: emit CompletedValidatorRegistration
"
/>




# Add Validator Demo (/academy/permissioned-l1s/05-validator-manager-operations/04-add-validator-demo)

---
title: Add Validator Demo
description: Practical - initiate, register on P-Chain, and complete validator registration using the Toolbox.
updated: 2025-03-19
authors: [nicolasarnedo]
icon: Terminal
---

import ToolboxMdxWrapper from "@/components/toolbox/academy/wrapper/ToolboxMdxWrapper.tsx"
import AddValidator from "@/components/toolbox/console/permissioned-l1s/AddValidator.tsx"

<ToolboxMdxWrapper walletMode="l1">
  <AddValidator />
</ToolboxMdxWrapper>

You can view the changes applied to the Validator Set [re-running the query in section 2](/academy/permissioned-l1s/05-validator-manager-operations/02-query-validator-set).


# Changing Weight (/academy/permissioned-l1s/05-validator-manager-operations/05-change-weight)

---
title: Changing Weight
description: Theory walkthrough of changing a validator's weight with ValidatorManager owned by an EOA, including L1 and P-Chain calls.
updated: 2025-03-19
authors: [nicolasarnedo]
icon: BookOpen
---

## Changing a Validator’s Weight

You’re changing an existing validator’s weight in a PoA setup where the `ValidatorManager` contract is owned by an EOA. The process mirrors registration: initiation on L1, processing on the P-Chain, and completion on L1.

### Phase 1: Initiation (L1)

The owner calls [`initiateValidatorWeightUpdate(validationID, newWeight)`](https://github.com/ava-labs/icm-contracts/blob/ce85313c71f90282b390e685cb652e9b0150a4ae/contracts/validator-manager/ValidatorManager.sol#L658) on `ValidatorManager`.

Under the hood, the contract:
- Ensures the validator is currently Active
- Enforces churn constraints so the delta does not exceed the configured maximum churn percentage
- Increments the validator's sent nonce
- Updates the pending weight in storage and constructs a weight message
- Sends a Warp message to the P-Chain

### Phase 2: P-Chain Processing

We then will sign and submit the `L1ValidatorWeightMessage` warped response we got from the last step to the P-Chain, this executes a `SetL1ValidatorWeightTx`, and upon success signs and returns an `L1ValidatorWeightMessage` warped response.

The P-Chain processes the following message structure:

```go
type L1ValidatorWeight struct {
	payload

	ValidationID ids.ID `serialize:"true" json:"validationID"`
	Nonce        uint64 `serialize:"true" json:"nonce"`
	Weight       uint64 `serialize:"true" json:"weight"`
}
```

### Phase 3: Completion (L1)

We finally will call the [`completeValidatorWeightUpdate(messageIndex)`](https://github.com/ava-labs/icm-contracts/blob/ce85313c71f90282b390e685cb652e9b0150a4ae/contracts/validator-manager/ValidatorManager.sol#L690), where we will pass the message index of the response we received in step 2. The contract verifies the Warp message and nonce correspondence, updates the received nonce, and emits `CompletedValidatorWeightUpdate`.

Anyone can call the `completeValidatorWeightUpdate(messageIndex)` with the signed message.

### Sequence Diagram

<Mermaid
  chart="
sequenceDiagram
    participant EOA_Owner as EOA Owner
    participant ValidatorManager as ValidatorManager
    participant WarpMessenger as WarpMessenger (precompile)
    participant PChain as P-Chain

    %% Phase 1: Initiation
    EOA_Owner->>ValidatorManager: initiateValidatorWeightUpdate(validationID, newWeight)

    ValidatorManager->>ValidatorManager: _initiateValidatorWeightUpdate()

    ValidatorManager->>ValidatorManager: Validate: isActive + churn rate

    ValidatorManager->>ValidatorManager: Increment sent nonce

    ValidatorManager->>ValidatorManager: Update weight in storage

    ValidatorManager->>WarpMessenger: sendWarpMessage(packL1ValidatorWeightMessage)

    %% Phase 2: P-Chain Processing
    WarpMessenger->>PChain: Deliver L1ValidatorWeightMessage

    PChain-->>WarpMessenger: Signed L1ValidatorWeightMessage (ack)

    %% Phase 3: Completion
    participant AnyCaller as Any Caller

    AnyCaller->>ValidatorManager: completeValidatorWeightUpdate(message)

    ValidatorManager->>ValidatorManager: Verify Warp message + nonce match

    ValidatorManager->>ValidatorManager: Update received nonce

    ValidatorManager-->>AnyCaller: emit CompletedValidatorWeightUpdate
"
/>



# Change Weight Demo (/academy/permissioned-l1s/05-validator-manager-operations/06-change-weight-demo)

---
title: Change Weight Demo
description: Practical - change a validator's weight using the Toolbox.
updated: 2025-03-19
authors: [nicolasarnedo]
icon: Terminal
---

import ToolboxMdxWrapper from "@/components/toolbox/academy/wrapper/ToolboxMdxWrapper.tsx"
import ChangeWeight from "@/components/toolbox/console/permissioned-l1s/ChangeWeight.tsx"

<ToolboxMdxWrapper walletMode="l1">
  <ChangeWeight />
</ToolboxMdxWrapper>

You can view the changes applied to the Validator Set [re-running the query in section 2](/academy/permissioned-l1s/05-validator-manager-operations/02-query-validator-set).


# Removing Validator (/academy/permissioned-l1s/05-validator-manager-operations/07-remove-validator)

---
title: Removing Validator
description: Theory walkthrough of removing a validator with ValidatorManager owned by an EOA, including L1 and P-Chain calls.
updated: 2025-03-19
authors: [nicolasarnedo]
icon: BookOpen
---

## Removing a Validator

You're removing an existing Active validator in a PoA setup where the `ValidatorManager` contract is owned by an EOA. The flow has two L1 calls with P-Chain processing in between.

### Phase 1: Initiation (L1)

The owner calls [`initiateValidatorRemoval(validationID)`](https://github.com/ava-labs/icm-contracts/blob/ce85313c71f90282b390e685cb652e9b0150a4ae/contracts/validator-manager/ValidatorManager.sol#L518) on `ValidatorManager`.

Under the hood, the contract:
- Ensures the validator is currently Active
- Sets the validator status to `PendingRemoved`
- Sets the end time of the current validation period to the current timestamp
- Persists updates and constructs a weight message with `weight = 0`
- Sends a Warp message to the P-Chain (removal is encoded as a weight update to zero)

### Phase 2: P-Chain Processing

We then will sign and submit the `L1ValidatorWeightMessage` warped response we got from the last step to the P-Chain, this executes a `SetL1ValidatorWeightTx`. Upon successful processing, it acknowledges the validator exit by signing and returns an `L1ValidatorRegistrationMessage` with `valid = 0` warped response.

The P-Chain processes the weight message (with weight set to 0 for removal):

```go
type L1ValidatorWeight struct {
	payload

	ValidationID ids.ID `serialize:"true" json:"validationID"`
	Nonce        uint64 `serialize:"true" json:"nonce"`
	Weight       uint64 `serialize:"true" json:"weight"` // Set to 0 for removal
}
```

And returns a registration message acknowledging the removal:

```go
type L1ValidatorRegistrationMessage struct {
	payload

	ValidationID ids.ID `serialize:"true" json:"validationID"`
	Valid        bool   `serialize:"true" json:"valid"` // Set to false for removal
}
```

### Phase 3: Completion (L1)

We finally will call the [`completeValidatorRemoval(messageIndex)`](https://github.com/ava-labs/icm-contracts/blob/ce85313c71f90282b390e685cb652e9b0150a4ae/contracts/validator-manager/ValidatorManager.sol#L573), where we will pass the message index of the response we received in step 2. The contract verifies the Warp message, confirms the registration status is false, updates the validator's status to Completed (if previously `PendingRemoved`), removes the node from the registered mapping, persists updates, and emits `CompletedValidatorRemoval`.

Anyone can call the `completeValidatorRemoval(messageIndex)` with the signed message.

### Sequence Diagram

<Mermaid
  chart="
sequenceDiagram
    participant EOA_Owner as EOA Owner
    participant ValidatorManager as ValidatorManager
    participant WarpMessenger as WarpMessenger (precompile)
    participant PChain as P-Chain

    %% Phase 1: Initiation
    EOA_Owner->>ValidatorManager: initiateValidatorRemoval(validationID)

    ValidatorManager->>ValidatorManager: _initiateValidatorRemoval()

    ValidatorManager->>ValidatorManager: Validate Active status

    ValidatorManager->>ValidatorManager: Set status = PendingRemoved<br/>Set validation end time

    ValidatorManager->>ValidatorManager: Save validator updates

    ValidatorManager->>WarpMessenger: sendWarpMessage(weightMessage(weight=0))

    %% Phase 2: P-Chain Processing
    WarpMessenger->>PChain: Deliver L1ValidatorWeightMessage(weight=0)

    PChain-->>WarpMessenger: Signed L1ValidatorRegistrationMessage(valid=0)

    %% Phase 3: Completion
    participant AnyCaller as Any Caller

    AnyCaller->>ValidatorManager: completeValidatorRemoval(message)

    ValidatorManager->>ValidatorManager: Verify Warp message<br/>Check valid == false

    ValidatorManager->>ValidatorManager: Set status = Completed<br/>Remove from registered validators

    ValidatorManager-->>AnyCaller: emit CompletedValidatorRemoval

    %% Optional: Resend
    EOA_Owner-->>ValidatorManager: resendValidatorRemovalMessage(validationID)
"
/>

# Remove Validator Demo (/academy/permissioned-l1s/05-validator-manager-operations/08-remove-validator-demo)

---
title: Remove Validator Demo
description: Practical - remove a validator using the Toolbox.
updated: 2025-03-19
authors: [nicolasarnedo]
icon: Terminal
---

import ToolboxMdxWrapper from "@/components/toolbox/academy/wrapper/ToolboxMdxWrapper.tsx"
import RemoveValidator from "@/components/toolbox/console/permissioned-l1s/RemoveValidator.tsx"

<ToolboxMdxWrapper walletMode="l1">
  <RemoveValidator />
</ToolboxMdxWrapper>

You can view the changes applied to the Validator Set [re-running the query in section 2](/academy/permissioned-l1s/05-validator-manager-operations/02-query-validator-set).


# Remove Expired Validator Registration (/academy/permissioned-l1s/05-validator-manager-operations/09-expired-validator-registration)

---
title: Remove Expired Validator Registration
description: Learn how to identify and remove expired validator registrations that were not completed within the 24-hour window.
updated: 2025-03-19
authors: [nicolasarnedo]
icon: Terminal
---

import ToolboxMdxWrapper from "@/components/toolbox/academy/wrapper/ToolboxMdxWrapper.tsx"
import RemoveExpiredValidatorRegistration from "@/components/toolbox/console/permissioned-l1s/RemoveExpiredValidatorRegistration/RemoveExpiredValidatorRegistration.tsx"

## Understanding Expired Validator Registrations

When validators are registered through the Validator Manager contract, they are given a **24-hour window** to complete their registration on the P-Chain. If this window expires without completion, the registration becomes invalid but remains in the pending registrations list.

Expired validator registrations typically occur due to configuration errors or manual mistakes during the registration process that prevent proper P-Chain registration.

These registrations create contract clutter by remaining in the pending list indefinitely, making it difficult to identify valid pending registrations.

## Removing Expired Registrations

This tool automatically identifies registrations past their expiry time and removes them from the pending list to keep your validator management system organized.

When removing an expired registration, the tool builds the required justification for P-Chain removal, signs the removal message using the appropriate signing mechanism, executes the `completeValidatorRemoval` function, and updates the contract state to remove the expired registration from the pending list.

<ToolboxMdxWrapper walletMode="l1">
  <RemoveExpiredValidatorRegistration />
</ToolboxMdxWrapper>



# P-Chain Disable Validator (/academy/permissioned-l1s/05-validator-manager-operations/10-pchain-disable-validator)

---
title: P-Chain Disable Validator
description: Practical - disable a validator at the P-Chain level.
updated: 2025-03-19
authors: [nicolasarnedo]
icon: BookOpen
---

We can directly disable a validator on the P-Chain using the `DisableL1ValidatorTx` transaction and without needing to go through the VMC flow.

### Why Direct P-Chain Disabling Exists

The direct disable flow is crucial for possible emergency situations like:
- The L1 goes down or becomes unreachable
- The Validator Manager Contract (VMC) is down or malfunctioning
- Something in the system is malfunctioning and immediate action is needed

These issues all become critical when the owner of the validators needs to retrieve their validator P-Chain AVAX used to keep it running (e.g; they deposited 1000 AVAX to never have to worry about topping up balances and now can't get it back)

### How It Works

**Direct P-Chain Transaction**: You can issue a `DisableL1ValidatorTx` directly on the P-Chain to disable any validator without interacting with the L1's Validator Manager contract at all.

**Weight Preservation**: When a validator is disabled this way, their weight still counts towards the L1's total weight - they're just inactive.

**Re-activation**: Disabled validators can be re-activated at any time by increasing their balance with an `IncreaseBalanceTx`. Anyone can call this transaction for any validator on the P-Chain.

**Key Management**: When a validator is disabled, the keys are no longer stored on disk, providing additional security.

**Permanent Removal Requires Contract**: To completely and permanently remove a validator from the set, you still need to call `initiateValidatorRemoval()` through the contract flow


### Chapter Conclusion

Throughout this chapter, we've explored the complete validator lifecycle - from adding validators through the VMC, modifying their weights, removing them properly, and handling emergency situations with direct P-Chain disabling.

This is all you will need to know in order to **manage the validator set of your permissioned L1**. 

## Appendix: Direct P-Chain Disable Flow

<Mermaid chart={`sequenceDiagram
    participant User as User/Admin
    participant PChain as P-Chain
    participant L1Validator as L1 Validator

    User->>PChain: IssueDisableL1ValidatorTx(validationID)
    PChain->>PChain: Process DisableL1ValidatorTx<br/>Remove keys from disk
    PChain->>L1Validator: Disable validator

    Note left of L1Validator: Validator becomes inactive<br/>Weight still counts toward total<br/>Keys no longer on disk
    Note over User,L1Validator: 2. Optional: Re-activation

    User->>PChain: IncreaseBalanceTx(validationID, amount)
    Note right of User: Anyone can call this<br/>for any validator

    PChain->>PChain: Process IncreaseBalanceTx

    PChain->>L1Validator: Re-activate validator`} />




# Read Validator Manager Contract (/academy/permissioned-l1s/XX-poa-manager-deployment/01-read-validator-manager)

---
title: Read Validator Manager Contract
description: Learn how to query and read data from the Validator Manager
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---


import ToolboxMdxWrapper from "@/components/toolbox/academy/wrapper/ToolboxMdxWrapper.tsx"
import ReadContract from "@/components/toolbox/console/permissioned-l1s/validator-manager-setup/ReadContract.tsx"

## Overview

Reading data from the Validator Manager contract is essential for monitoring your L1's validator set and understanding the current state of the system.

## Query Contract State



<ToolboxMdxWrapper walletMode="l1">
    <ReadContract />
</ToolboxMdxWrapper>

## Key Read Functions

### Configuration Data

#### `subnetID()`
Returns your L1's unique identifier:
```solidity
function subnetID() external view returns (bytes32)
```

#### `owner()`
Returns the current contract owner:
```solidity
function owner() external view returns (address)
```

#### Churn Parameters
Get the churn configuration:
```solidity
function churnPeriodSeconds() external view returns (uint64)
function maximumChurnPercentage() external view returns (uint8)
```

### Validator Information

#### `getValidator(bytes32 validationID)`
Get detailed information about a specific validator:
```solidity
struct Validator {
    ValidatorStatus status;  // Current status
    bytes nodeID;           // Node identifier
    uint64 weight;          // Voting weight
    uint64 startedAt;       // Start timestamp
    uint64 endedAt;         // End timestamp
}
```

#### `getWeight(bytes32 validationID)`
Get a validator's current weight:
```solidity
function getWeight(bytes32 validationID) external view returns (uint64)
```

### Aggregate Data

#### `totalWeight()`
Get the total weight of all active validators:
```solidity
function totalWeight() external view returns (uint64)
```

#### `activeValidatorCount()`
Get the number of active validators:
```solidity
function activeValidatorCount() external view returns (uint256)
```

## Understanding Validator Status

Validators can have different statuses:

1. **Active**: Currently validating
2. **PendingAdded**: Registration initiated, not yet complete
3. **PendingRemoved**: Removal initiated, not yet complete
4. **Completed**: No longer active

## Churn Tracker State

Monitor churn consumption:

```solidity
function getCurrentChurnPeriod() external view returns (
    uint256 startTime,
    uint64 initialWeight,
    uint64 totalWeight,
    uint64 churnAmount
)
```

### Interpreting Churn Data

- **startTime**: When current period began
- **initialWeight**: Total weight at period start
- **totalWeight**: Current total weight
- **churnAmount**: Amount changed this period

## Common Queries

### List All Validators
While there's no built-in function to list all validators, you can:
1. Listen to events from contract creation
2. Track `ValidatorRegistered` events
3. Build an off-chain index

### Check Validator Eligibility
Before adding a validator, check:
```javascript
// Get current churn usage
const churn = await validatorManager.getCurrentChurnPeriod();
const maxChange = (churn.totalWeight * maxChurnPercentage) / 100;
const remainingChurn = maxChange - churn.churnAmount;

// Check if new validator weight fits
if (newValidatorWeight <= remainingChurn) {
    console.log("Can add validator");
} else {
    console.log("Must wait for new churn period");
}
```

### Monitor Pending Operations
Check for pending validator operations:
```javascript
// Check if validator has pending operation
const validator = await validatorManager.getValidator(validationID);
if (validator.status === "PendingAdded") {
    console.log("Registration pending completion");
}
```

## Event Monitoring

Subscribe to contract events for real-time updates:

```javascript
// Listen for new validators
validatorManager.on("ValidatorRegistered", (nodeID, weight) => {
    console.log(`New validator: ${nodeID}, weight: ${weight}`);
});

// Listen for removals
validatorManager.on("ValidatorRemoved", (nodeID) => {
    console.log(`Validator removed: ${nodeID}`);
});

// Listen for weight updates
validatorManager.on("ValidatorWeightUpdated", (nodeID, newWeight) => {
    console.log(`Weight updated: ${nodeID}, new weight: ${newWeight}`);
});
```

## Best Practices

1. **Regular Monitoring**: Check validator states periodically
2. **Event Tracking**: Use events for real-time updates
3. **Churn Planning**: Monitor churn usage before operations
4. **State Verification**: Verify state after operations

## Troubleshooting

### Reading Issues

1. **Wrong Network**: Ensure connected to correct chain
2. **Invalid Address**: Verify contract address
3. **ABI Mismatch**: Use correct contract ABI

### Data Interpretation

1. **Timestamps**: All times are Unix timestamps
2. **Weights**: Understand weight units for your system
3. **Status Codes**: Map numeric status to names

## Next Steps

After understanding how to read the contract:
1. Initialize the validator set with existing validators
2. Query and verify the initial state
3. Begin active validator management


# Query Validator Set (/academy/permissioned-l1s/XX-poa-manager-deployment/02-query-validator-set)

---
title: Query Validator Set
description: Learn how to query and monitor your L1's validator set
updated: 2025-07-31
authors: [nicolasarnedo]
icon: BookOpen
---

import ToolboxMdxWrapper from "@/components/toolbox/academy/wrapper/ToolboxMdxWrapper.tsx"
import QueryL1ValidatorSet from "@/components/toolbox/console/permissioned-l1s/QueryL1ValidatorSet.tsx"

## Overview

Querying the validator set is essential for monitoring your L1's health, planning changes, and ensuring proper operation. This section covers how to effectively query and interpret validator data.

## Query Tools



<ToolboxMdxWrapper walletMode="l1">
    <QueryL1ValidatorSet />
</ToolboxMdxWrapper>

## Query Methods

### Individual Validator Queries

#### Get Validator by ID
```javascript
const validator = await validatorManager.getValidator(validationID);
console.log({
    status: validator.status,
    nodeID: validator.nodeID,
    weight: validator.weight,
    startedAt: new Date(validator.startedAt * 1000),
    endedAt: validator.endedAt > 0 ? new Date(validator.endedAt * 1000) : "Active"
});
```

#### Get Validator Weight
```javascript
const weight = await validatorManager.getWeight(validationID);
console.log(`Validator weight: ${weight}`);
```

### Aggregate Queries

#### Total Network Weight
```javascript
const totalWeight = await validatorManager.totalWeight();
console.log(`Total network weight: ${totalWeight}`);
```

#### Active Validator Count
```javascript
const count = await validatorManager.activeValidatorCount();
console.log(`Active validators: ${count}`);
```

## Building a Validator Registry

Since the contract doesn't provide a built-in list function, you can build a registry by:

### 1. Event-Based Approach

```javascript
// Get all historical events
const registeredEvents = await validatorManager.queryFilter(
    validatorManager.filters.ValidatorRegistered()
);

const removedEvents = await validatorManager.queryFilter(
    validatorManager.filters.ValidatorRemoved()
);

// Build active validator list
const validators = new Map();

registeredEvents.forEach(event => {
    validators.set(event.args.nodeID, {
        nodeID: event.args.nodeID,
        weight: event.args.weight,
        registeredAt: event.blockNumber
    });
});

removedEvents.forEach(event => {
    validators.delete(event.args.nodeID);
});
```

### 2. Off-Chain Index

Maintain a database that tracks:
- Validator additions
- Validator removals  
- Weight updates
- Current state

## Monitoring Validator Status

### Status Types

```javascript
enum ValidatorStatus {
    Active = 0,        // Currently validating
    PendingAdded = 1,  // Addition initiated
    PendingRemoved = 2, // Removal initiated
    Completed = 3      // No longer active
}
```

### Check Pending Operations

```javascript
async function checkPendingOperations(validationID) {
    const validator = await validatorManager.getValidator(validationID);
    
    switch(validator.status) {
        case 1: // PendingAdded
            console.log("Waiting for registration completion");
            break;
        case 2: // PendingRemoved
            console.log("Waiting for removal completion");
            break;
        case 0: // Active
            console.log("Validator is active");
            break;
        case 3: // Completed
            console.log("Validator has been removed");
            break;
    }
}
```

## Churn Analysis

### Current Churn Status
```javascript
const churn = await validatorManager.getCurrentChurnPeriod();

const churnPercentageUsed = (churn.churnAmount * 100) / 
    (churn.totalWeight * maximumChurnPercentage / 100);

console.log(`Churn used: ${churnPercentageUsed.toFixed(2)}%`);
console.log(`Churn resets at: ${new Date(churn.startTime + churnPeriodSeconds * 1000)}`);
```

### Available Churn Capacity
```javascript
function calculateAvailableChurn(churnData, maxPercentage) {
    const maxChurn = (churnData.totalWeight * maxPercentage) / 100;
    const usedChurn = churnData.churnAmount;
    const availableChurn = maxChurn - usedChurn;
    
    return {
        max: maxChurn,
        used: usedChurn,
        available: availableChurn,
        canAddWeight: availableChurn
    };
}
```

## Creating a Validator Dashboard

Build a comprehensive view:

```javascript
async function getValidatorSetInfo() {
    const [totalWeight, activeCount, churn] = await Promise.all([
        validatorManager.totalWeight(),
        validatorManager.activeValidatorCount(),
        validatorManager.getCurrentChurnPeriod()
    ]);
    
    return {
        summary: {
            totalWeight,
            activeValidators: activeCount,
            averageWeight: totalWeight / activeCount
        },
        churn: {
            periodStart: new Date(churn.startTime * 1000),
            used: churn.churnAmount,
            remaining: calculateAvailableChurn(churn, maxChurnPercentage).available
        }
    };
}
```

## Query Patterns

### Regular Health Checks
```javascript
setInterval(async () => {
    const health = await getValidatorSetInfo();
    console.log("Network health:", health);
    
    // Alert if validators drop below threshold
    if (health.summary.activeValidators < MIN_VALIDATORS) {
        console.warn("Low validator count!");
    }
}, 60000); // Check every minute
```

### Pre-Operation Checks
```javascript
async function canAddValidator(weight) {
    const churn = await validatorManager.getCurrentChurnPeriod();
    const available = calculateAvailableChurn(churn, maxChurnPercentage);
    
    return weight <= available.available;
}
```

## Best Practices

1. **Cache Results**: Don't query repeatedly for static data
2. **Batch Queries**: Use multicall for multiple reads
3. **Event Monitoring**: Subscribe to events for real-time updates
4. **Error Handling**: Handle query failures gracefully

## Common Issues

### Query Failures
- **Network Issues**: Check RPC connection
- **Contract Address**: Verify correct address
- **ABI Mismatch**: Ensure using correct ABI

### Data Interpretation
- **Weight Units**: Understand your weight denomination
- **Timestamps**: Convert Unix timestamps properly
- **Status Codes**: Map numeric status correctly

## Next Steps

With query capabilities established:
1. Set up regular monitoring
2. Build dashboards for visibility
3. Plan validator management operations
4. Implement alerting for critical changes


# Deploy PoA Manager (/academy/permissioned-l1s/XX-poa-manager-deployment/03-deploy-poa-manager)

---
title: Deploy PoA Manager
description: Deploy the Proof of Authority Manager contract for simplified validator management
updated: 2025-07-31
authors: [nicolasarnedo]
icon: Terminal
---

import ToolboxMdxWrapper from "@/components/toolbox/academy/wrapper/ToolboxMdxWrapper.tsx"
import DeployPoAManager from "@/components/toolbox/console/permissioned-l1s/multisig-setup/DeployPoAManager.tsx"

## Overview

The Proof of Authority (PoA) Manager is a simplified validator management contract that provides an easier interface for managing validators on your L1. It acts as a wrapper around the core Validator Manager contract, offering streamlined operations for PoA-based L1s.

## PoA Manager Benefits

The PoA Manager provides several advantages:

1. **Simplified Interface**: Easier validator management compared to the core Validator Manager
2. **Owner-Based Control**: Single owner can manage all validator operations
3. **Streamlined Operations**: Reduced complexity for adding/removing validators
4. **Integration Ready**: Works seamlessly with your existing Validator Manager setup

## Prerequisites

Before deploying the PoA Manager, ensure you have:

1. **Completed L1 Conversion**: Your Subnet must be converted to L1
2. **Deployed Validator Manager**: Core Validator Manager contract must be deployed and initialized
3. **Proper Permissions**: Owner access to the Validator Manager contract
4. **Network Selection**: Connected to the correct blockchain (where your Validator Manager is deployed)

## Deploy PoA Manager

<ToolboxMdxWrapper walletMode="l1">
    <DeployPoAManager />
</ToolboxMdxWrapper>

## Deployment Parameters

When deploying the PoA Manager, you'll need to configure:

1. **Validator Manager Address**: The address of your deployed Validator Manager contract
2. **Owner Address**: The address that will have control over the PoA Manager
3. **Subnet ID**: Your L1's Subnet ID for validator operations
4. **Network Configuration**: Ensure you're deploying on the correct chain

## Post-Deployment Configuration

After successful deployment:

1. **Verify Deployment**: Confirm the PoA Manager address and configuration
2. **Test Connection**: Ensure the PoA Manager can communicate with your Validator Manager
3. **Set Permissions**: Configure any additional access controls if needed
4. **Document Address**: Save the PoA Manager address for future operations

## PoA Manager Functions

The PoA Manager provides simplified functions for:

### Validator Operations
- **Add Validator**: Simplified validator registration process
- **Remove Validator**: Streamlined validator removal
- **Update Validator**: Modify validator parameters

### Administrative Functions
- **Owner Management**: Transfer ownership if needed
- **Configuration Updates**: Modify PoA Manager settings
- **Emergency Controls**: Safety mechanisms for critical situations

## Security Considerations

When using the PoA Manager:

1. **Owner Security**: Protect the owner private key carefully
2. **Access Control**: Limit who has access to owner functions
3. **Regular Monitoring**: Monitor validator operations and contract state
4. **Backup Plans**: Have procedures for emergency situations

## Common Use Cases

The PoA Manager is ideal for:

- **Private L1s**: Organizations running permissioned blockchains
- **Development Networks**: Testing and development environments  
- **Consortium Chains**: Multi-party controlled networks
- **Simplified Operations**: Teams wanting reduced operational complexity

## Troubleshooting

### Deployment Issues
- **Permission Errors**: Verify you have owner access to the Validator Manager
- **Network Mismatch**: Ensure you're on the correct blockchain
- **Gas Issues**: Check you have sufficient gas for deployment

### Operation Issues
- **Function Failures**: Verify the PoA Manager has proper permissions
- **State Inconsistencies**: Check synchronization with the Validator Manager
- **Access Denied**: Confirm you're using the correct owner address

## Next Steps

With the PoA Manager deployed, you can:

1. **Start Managing Validators**: Use the simplified interface to add/remove validators
2. **Monitor Operations**: Track validator changes and system health
3. **Scale Your Network**: Add more validators as your L1 grows
4. **Integrate Systems**: Connect the PoA Manager to your operational tools

The PoA Manager provides a powerful yet simple way to manage your L1's validator set while maintaining the security and reliability of the underlying Validator Manager system.


# VMC Deployed Structure (/academy/permissioned-l1s/XX-poa-manager-deployment/04-vmc-deployed-structure)

---
title: VMC Deployed Structure
description: Summary of deployed smart contract structure up until this point
updated: 2025-01-01
authors: [nicolasarnedo]
icon: FileCode
---

## Overview

Understanding the ValidatorManager contract structure is essential for proper initialization and operation. This section covers the contract's architecture, state variables, and initialization process.

## Contract Inheritance

The ValidatorManager follows a structured inheritance pattern:

```solidity
contract ValidatorManager is 
    IValidatorManager, 
    Initializable, 
    OwnableUpgradeable, 
    ACP99Manager 
{
    // Implementation
}
```

### Inherited Contracts

1. **IValidatorManager**: Defines the interface
2. **Initializable**: Enables proxy-safe initialization
3. **OwnableUpgradeable**: Provides access control
4. **ACP99Manager**: Implements ACP-99 standard

## State Variables

### Core Configuration

```solidity
struct ValidatorManagerSettings {
    address admin;           // Initial owner address
    bytes32 subnetID;       // Your L1's subnet ID
    uint64 churnPeriodSeconds;      // Time window for changes
    uint8 maximumChurnPercentage;   // Max change per period
}
```

### Validator Tracking

```solidity
struct Validator {
    ValidatorStatus status;  // Active, Pending, Removed
    bytes nodeID;           // Validator's node ID
    uint64 weight;          // Voting weight
    uint64 startedAt;       // Registration timestamp
    uint64 endedAt;         // Removal timestamp
}
```

## Initialization Function

The `initialize` function sets up the ValidatorManager:

```solidity
function initialize(
    ValidatorManagerSettings calldata settings
) external initializer {
    // Set up ownership
    __Ownable_init(settings.admin);
    
    // Store configuration
    _subnetID = settings.subnetID;
    _churnPeriodSeconds = settings.churnPeriodSeconds;
    _maximumChurnPercentage = settings.maximumChurnPercentage;
}
```

### Initialization Parameters

1. **admin**: Address that will own the contract
2. **subnetID**: Your L1's unique identifier
3. **churnPeriodSeconds**: Anti-spam protection period
4. **maximumChurnPercentage**: Limits rapid validator changes

<Callout type="info">
The churn mechanism prevents rapid validator set changes that could destabilize the network. It limits how much stake can be added or removed within a time window.
</Callout>

## Churn Protection

### How Churn Works

The churn mechanism tracks validator changes over time:

```solidity
struct ValidatorChurnPeriod {
    uint256 startTime;      // Period start
    uint64 initialWeight;   // Weight at start
    uint64 totalWeight;     // Current total weight
    uint64 churnAmount;     // Amount changed
}
```

### Churn Calculation

- Tracks changes within `churnPeriodSeconds`
- Limits changes to `maximumChurnPercentage` of total weight
- Resets after period expires
- Prevents network instability

## Key Functions Overview

### Owner Functions

Only the contract owner can call:
- `initiateValidatorRegistration()`: Add new validator
- `initiateValidatorRemoval()`: Remove validator
- `initiateValidatorWeightUpdate()`: Change voting weight

### Public Functions

Anyone can call these to complete pending operations:
- `completeValidatorRegistration()`: Finalize addition
- `completeValidatorRemoval()`: Finalize removal
- `completeValidatorWeightUpdate()`: Finalize weight change

### Query Functions

Read-only functions for information:
- `getValidator()`: Get validator details
- `getWeight()`: Get total or individual weight
- `subnetID()`: Get the L1's ID
- `owner()`: Get contract owner

## Storage Layout

Understanding storage is crucial for upgrades:

1. **Proxy Storage**: State variables live here
2. **Implementation Logic**: Functions live here
3. **Storage Slots**: Must maintain order in upgrades

## Events

The contract emits events for tracking:

```solidity
event ValidatorRegistered(bytes nodeID, uint64 weight);
event ValidatorRemoved(bytes nodeID);
event ValidatorWeightUpdated(bytes nodeID, uint64 newWeight);
```

## Security Considerations

1. **Owner Privileges**: Owner has full control
2. **Churn Limits**: Prevents rapid changes
3. **Two-Phase Operations**: Prevents front-running
4. **Message Validation**: Verifies P-Chain messages

## Next Steps

With understanding of the contract structure:
1. Set initial configuration parameters
2. Initialize the ValidatorManager
3. Begin managing your validator set

# Registering Validators (/academy/permissioned-l1s/XX-registering-validator/registering-validator)

---
title: Registering Validators
description: Learn how validators are registered on the Avalanche network post-etna.
updated: 2024-10-14
authors: [owenwahlgren]
icon: Terminal
---

> How does it all work? I mean *actually* work.

### Sending Warp Messages

On the EVM, a warp message is simply an event log with `messageID = sha256(messagePayload)` Nothing is ever actually “sent” anywhere, which trips people up when first learning how Warp Messaging works.

The log event emitted is from the Warp precompile address (`0x0200000000000000000000000000000000000005`) The topic of the message will be `0x56600c567728a800c0aa927500f831cb451df66a7af570eb4df4dfbf4674887d` which is the output of 
```bash
cast keccak "SendWarpMessage(address,bytes32,bytes)"
```

To find a specific warp messageID, one must know the block number or block hash to retrieve the logs, or be monitoring all events, looking for and indexing messages. 

When a block is [accepted](https://github.com/ava-labs/coreth/blob/7242ae2d235593d2bb14e2496b6ed102aab14c3d/precompile/contracts/warp/config.go#L130) by the network, a precompile hook is called, and the EVM saves the warp message to a local database. The validator node will then be willing to sign any messages in that database upon request, typically via an `AppRequest` message over the p2p network.

### Receiving Warp Messages

On the EVM, any smart contract can call the precompile

which returns the warp message and verifies the attached signature. But what is `index`? Where does it get the warp message from?  The answer is, you!  When you send a tx to any contract that eventually calls `getVerifiedWarpMessage`, you **must** pass in the signed warp message as a “predicate”.  It’s called an AccessList, and typically this is an optional field that can be used by the EVM to pre-fetch storage slots that will be accessed, for efficiency and reducing gas costs. But Warp cleverly (ab)uses this feature of the EVM to verify the signature of the warp message, and then make the warp message available during the transactions lifetime, by calling `getVerifiedWarpMessage`. You can pass multiple warp messages which is where the `index` comes in.  (All of this is abstracted away by Teleporter for EVM to EVM comms)

Details: [Warp README](https://github.com/ava-labs/coreth/blob/7242ae2d235593d2bb14e2496b6ed102aab14c3d/precompile/contracts/warp/README.md)

### Teleporter

[Teleporter](https://github.com/ava-labs/teleporter) is a set of smart contracts that implements a rich messaging protocol on top of the Warp Messaging primitive, allowing for verified message passing between EVM chains. 

<Callout>
**Only (currently) supports EVM→EVM comms. Not used for EVM→P-Chain**
</Callout>

### Relayer

[Relayer](https://github.com/ava-labs/awm-relayer/blob/main/relayer/README.md) is an off-chain program that listens for warp messages on a source chain, and delivers them to a destination chain.  Messages can choose to be relayed by anyone, or by only privileged relayers. Messages can also pay fees to incentivize relayers and cover gas costs.

## Registering ValidatorManager

ACP-77 introduces L1-only Validators, that stake no AVAX, and do not validate the X/C chains. They must connect to the Primary Network and track the P-Chain, and also validate their own chain, and pay a small continuous fee in AVAX to the network.

User submits EVM tx to smart contract [NativeTokenStakingManager.sol](https://github.com/ava-labs/teleporter/blob/acp-77-updates/contracts/validator-manager/NativeTokenStakingManager.sol)

```solidity
function initializeValidatorRegistration(
        ValidatorRegistrationInput calldata registrationInput,
        uint16 delegationFeeBips,
        uint64 minStakeDuration) payable returns (bytes32 validationID)
```
Notably, this function will:

- Lock the native tokens in the contract
- `validationID`: bytes32 hash of an encoded `RegisterSubnetValidatorMessage`
- `messageID`: bytes32 hash of the warp message
- Store some data in the contract:


```solidity
$._pendingRegisterValidationMessages[validationID] = registerSubnetValidatorMessage;
$._registeredValidators[input.nodeID] = validationID;
bytes32 messageID = WARP_MESSENGER.sendWarpMessage(registerSubnetValidatorMessage);
$._validationPeriods[validationID] = Validator({
  status: ValidatorStatus.PendingAdded,
  nodeID: input.nodeID,
  startingWeight: weight,
  messageNonce: 0,
  weight: weight,
  startedAt: 0, // The validation period only starts once the registration is acknowledged.
  endedAt: 0
});
```

- Emit `ValidationPeriodCreated(validationID, nodeID, messageID, weight, registrationExpiry)`
- The `sendWarpMessage` precompile will emit a log with `sender`, `messageID`, `message`

At this point, we have submitted a transaction on the blockchain (C-Chain or L1, wherever the staking contract is deployed). All that has happened is we have stored some state in our contract and emitted some events. No changes to validators has occurred.

<Callout>
Nothing else will happen UNLESS an off-chain actor continues the process.
</Callout>


In our case, someone must be running a relayer that is configured with our staking contract as the source and the P-Chain as the destination.

<Callout>
At the moment, the relayer does not support the P-Chain, so messages must be signed and sent manually. The relayer will be updated soon to support the P-Chain.
</Callout>


So, to sign and send the message ourselves, we can use the Signature Aggregator server in the relayer project. This will use the p2p layer of the Avalanche network to connect to validators and send `AppRequest` messages to request each validator to sign a message.
```bash
curl --location 'http://localhost:8080/aggregate-signatures' \
--json '{"message": "<hex encoded unsigned message bytes retrieved from the logs>"}'
```
This will give us an aggregated BLS signature from at least 67% of the stake weighted validator set. Now we need to `POST` this to the P-Chain via the `RegisterSubnetValidatorTx` tx.

The P-Chain, if it accepts the tx, will “send” a Warp Message `SubnetValidatorRegistration` which acknowledges the change. Note that nothing is actually “sent”, instead the validator node will be willing to sign the unsigned message upon request.

So the next step is to use the Signature Aggregator service again, and provide the unsigned `SubnetValidatorRegistration` warp message, which the service will then ask validators to sign.

<Callout>
If your Validator Manager contract is on your L1 (instead of C-Chain), as an optimization, you only need to ask 67% of the stake weighted validators of your L1, not the entire P-Chain validator set.
</Callout>


Once an aggregate BLS signature is created, we need to submit the signed message to the C-Chain (or L1) by calling a function on the `ValidatorManager` contract.

```solidity
function completeValidatorRegistration(uint32 messageIndex)
```

Remember, this involves calling the function via `eth_sendTransaction` and encoding the signed warp message into the `AccessList`. (If you encode an array of 1 warp message, then `messageIndex` would be 0)

The function will adjust the state in the contract, including these bits:
```solidity
delete $._pendingRegisterValidationMessages[validationID];
$._validationPeriods[validationID].status = ValidatorStatus.Active;
$._validationPeriods[validationID].startedAt = uint64(block.timestamp);
```
And that’s it!

<Callout>
This doc is a WIP and we will eventually cover all the flows and add some diagrams.
</Callout>


# VMC Deployment Options (/academy/permissioned-l1s/XX-vmc-other-evms/03-deployment-options)

---
title: VMC Deployment Options
description: Understanding where to deploy the PoA Validator Manager contract
updated: 2025-07-31
authors: [nicolasarnedo]
icon: Book
---

While Validator Manager Contract's (VMC) location choice becomes more critical when transitioning to Proof of Stake (PoS) systems due to token staking considetations, it's important to understand these options now because **you'll need to specify the VMC location in the next section when converting your Subnet to an L1**.

## Why can it be located anywhere?

The PoA Validator Manager contract can be deployed on any EVM-compatible chain within the Avalanche ecosystem. Since the contract communicates with the P-Chain through Interchain Messaging (ICM), **the deployment location doesn't affect its core functionality** - validator management operations work the same regardless of where the contract resides.

The Validator Manager Contract and P-chain generally follow a **Request-Process-Confirm** flow. The VMC chain initiates cross-chain communication to interact with the P-Chain for all validator operations (e.g: *adding a validator*):

- **Request**: Sends `RegisterL1ValidatorMessage` to P-Chain
- **Process**: P-Chain verifies signatures and processes the operation  
- **Confirm**: Receives `L1ValidatorRegistrationMessage` confirmations

## Deployment Options

<Tabs items={['Your L1', 'C-Chain', 'Another L1']} collapsible="true">

<Tab value="Your L1">
Best for L1's that plan to remain always permissioned with PoA

**Advantages**
- Direct integration with your L1's operational setup
- Lower operational costs
- Can configure native token minting privileges for future PoS migration

**Considerations**
- Requires bootstrapping initial validators before contract deployment
</Tab>

<Tab value="C-Chain">
Best for L1s planning future decentralization (PoS) or DeFi integration

**Advantages**
- Highest security and decentralization (Avalanche's primary network)
- Can manage multiple L1s from one location
- **DeFi Composability**: Easy integration with existing DeFi ecosystem
- **Decentralization Path**: Ideal for transition to Proof of Stake

**Considerations**
- Higher gas costs compared to L1s
- Potential congestion during high network usage
</Tab>

<Tab value="Another L1">
Best for multi-chain architecture systems owned  by the same company

**Advantages**
- Centralized management across multiple L1s
- Can leverage a "hub" L1 for coordinated operations

**Considerations**
- Technically, the implementation of this architecture is the same as deploying on the C-chain
</Tab>

</Tabs>

## Proof of Authority Recommendation

If you plan to keep your L1 permissioned with PoA, **deploying VMC on it is recommended** for better operational alignment.



# P-Chain (/academy/permissionless-l1s/01-review/01-pchain-review)

---
title: P-Chain
description: A review of the Platform Chain.
updated: 2025-03-13
authors: [nicolasarnedo]
icon: Book
---

import PChainReview from '@/content/academy/permissioned-l1s/01-introduction/01-pchain-review.mdx';

<PChainReview />


# Multi-Chain Architecture (/academy/permissionless-l1s/01-review/02-multi-chain-review)

---
title: Multi-Chain Architecture
description: A review of Avalanche's Multi-Chain Architecture
updated: 2025-03-13
authors: [nicolasarnedo]
icon: BookOpen
---

import MultiChainReview from '@/content/academy/permissioned-l1s/01-introduction/02-multi-chain-review.mdx';

<MultiChainReview />


# Permissioned L1s Review (/academy/permissionless-l1s/01-review/03-permissioned-l1s-review)

---
title: Permissioned L1s Review
description: A review of permissioned Layer 1 blockchains
updated: 2025-03-13
authors: [nicolasarnedo]
icon: BookOpen
---

## What are Permissioned L1s?

Permissioned L1s are Layer 1 blockchains where validator participation is controlled by a central authority rather than being open to anyone. Unlike permissionless networks where anyone can become a validator by staking tokens, permissioned L1s use **Proof of Authority (PoA)** as their sybil protection mechanism.

## Proof of Authority (PoA)

**Proof of Authority** is a sybil protection mechanism that centralizes control over who can validate the network to one account (EoA or multi-sig). Instead of requiring validators to stake tokens (like Proof of Stake), PoA leverages real-world identity and reputation.

### Key Characteristics:
- **Known Entities**: Validators are operated by trusted organizations
- **Reputation-Based**: Validators risk damaging real-world reputation if they misbehave
- **Weight-Based Influence**: Validators can have different voting weights
- **No Economic Incentives**: Validators don't receive rewards or face on-chain penalties

### When to Use PoA:
- Known participants that can be identified and vetted
- Existing trust relationships or legal frameworks
- Regulatory compliance requiring known validator identities
- Private networks for specific consortia
- High throughput requirements over decentralization

## Validator Manager Contract

The **Validator Manager Contract** is the smart contract system that manages validator operations in permissioned L1s. It follows a two-phase commit pattern for all validator changes.

### Core Functions:

**Initialization:**
- `initializeValidatorSet()`: Establishes initial validator set when converting Subnet to L1

**Validator Lifecycle Management:**
- `initiateValidatorRegistration()`: Starts adding a new validator
- `completeValidatorRegistration()`: Finalizes validator addition after P-Chain confirmation
- `initiateValidatorRemoval()`: Begins removing a validator
- `completeValidatorRemoval()`: Finalizes removal after P-Chain confirmation
- `initiateValidatorWeightUpdate()`: Changes validator voting weight
- `completeValidatorWeightUpdate()`: Finalizes weight changes

### Key Features:
- All functions protected with `onlyOwner` modifier
- Two-phase commit pattern: initiate → complete
- Churn rate limiting to prevent rapid validator set changes
- Warp message construction and verification

## P-Chain Integration

The **Platform Chain (P-Chain)** is the backbone for Avalanche's native interoperability. It serves as a registry of all validators in the network, including L1 validators.

### How P-Chain Calls Work:

1. **Validator Registration**: When adding a validator, the contract initiates a P-Chain transaction
2. **Warp Messages**: Cross-chain communication uses Warp messages to interact with P-Chain
3. **Confirmation Process**: P-Chain processes the request and sends confirmation back
4. **State Updates**: The validator manager contract updates its state based on P-Chain confirmation

### P-Chain Transaction Types:
- `CreateSubnetTx`: Creates new subnet for L1
- `CreateChainTx`: Creates new blockchain within subnet
- Validator registration/removal transactions
- Weight update transactions

### Key Points:
- P-Chain is **not EVM-based** - requires compatible wallet like Core wallet
- L1 validators sync P-Chain but don't participate in its consensus
- All validator changes must be confirmed by P-Chain before taking effect
- P-Chain maintains the authoritative record of all validators across the network

# Native Tokenomics Review (/academy/permissionless-l1s/01-review/04-native-tokenomics-review)

---
title: Native Tokenomics Review
description: A review of native tokenomics in blockchain systems
updated: 2025-03-13
authors: [nicolasarnedo]
icon: BookOpen
---

## What are L1 Native Tokenomics?

L1 Native Tokenomics refers to the economic design and management of native tokens on Layer 1 blockchains. Unlike ERC20 tokens that exist on top of a blockchain, native tokens are the fundamental gas token of the blockchain itself, used for transaction fees and network security.

## Custom Native Token Capabilities

**Custom native tokens** give you complete control over your blockchain's economic model, offering several powerful capabilities:

### Economic Design Control:
- **Custom Tokenomics**: Design token distribution, inflation, and utility to match your project's needs
- **Fee Control**: Set predictable, isolated transaction costs independent of other chains' activity
- **Business Model Flexibility**: Create valueless gas tokens for gas-free experiences or design complex incentive structures

### Native Token Management:
- **Initial Allocation**: Specify how the initial token supply is distributed
- **Minting Rights**: Define who can mint new tokens (hard-capped vs. flexible supply)
- **Fee Configuration**: Configure how transaction fees are calculated and distributed

## Precompiles for Tokenomics

Avalanche L1s use **precompiles** (protocol-level smart contracts) to enable powerful tokenomics features:

### Native Minter Precompile:
- **Supply Management**: Control whether your blockchain has a fixed token supply or can mint additional tokens
- **Minting Rights**: Configure who can mint new tokens and under what conditions
- **Economic Flexibility**: Enable gas-free experiences by minting tokens as needed

### Fee Config Precompile:
- **Transaction Fees**: Configure how transaction fees are calculated
- **Fee Distribution**: Control where fees go (burn, treasury, validators)
- **Dynamic Pricing**: Implement complex fee structures based on network conditions

## Relevance to Proof of Stake

Custom native tokens are **essential for Proof of Stake (PoS) systems** because they provide the economic foundation for validator incentives:

### Staking Token Requirements:
- **Validator Rewards**: Native tokens are distributed as rewards to validators for securing the network
- **Slashing Mechanisms**: Validators can lose their staked native tokens for malicious behavior
- **Economic Security**: The value of the native token directly impacts network security

### PoS Integration:
- **Staking Logic**: Define how nodes become validators through token staking
- **Reward Distribution**: Configure how validator rewards are calculated and distributed
- **Governance Rights**: Native token holders can participate in network governance

# Introduction (/academy/permissionless-l1s/02-proof-of-stake/01-introduction)

---
title: Introduction
description: A review of Proof of Stake on Avalanche
updated: 2025-03-13
authors: [nicolasarnedo]
icon: Book
---

## Proof of Stake as Sybil Protection

Proof of Stake (PoS) is fundamentally a **Sybil protection mechanism** that secures blockchain networks by preventing malicious actors from gaining control through the creation of multiple fake identities. Sybil protection mechanisms serve three critical functions:

1. **Determine who gets to participate fairly** - Establish clear rules for network participation
2. **Ensure participation power is tied to scarce resources** - Link voting power to valuable assets like stake, computation, or verified identity
3. **Act as the gatekeeper** - Control who can participate in consensus or block production

In Avalanche's implementation, PoS ties participation power to economic stake (AVAX tokens), making it prohibitively expensive for attackers to gain majority control of the network.

## How Proof of Stake Works on Avalanche

Avalanche uses Proof of Stake with support for delegation to secure its network. Here's how it operates:

### Validator Staking

Validators must stake AVAX tokens to participate in consensus. The requirements include:
- **Minimum validator stake**: 2,000 AVAX on Mainnet
- **Staking duration**: Between 2 weeks and 1 year
- **Uptime requirement**: Default 80% uptime to receive rewards

### Delegation

Token holders who don't want to run a validator node can delegate their stake to existing validators:
- **Minimum delegator stake**: 25 AVAX on Mainnet
- **Delegation fees**: Validators charge a minimum 2% fee and share rewards with delegators
- **Flexible participation**: Anyone can delegate without running infrastructure

### Validator Weight

A validator's influence in consensus is determined by their **validator weight**, which is the sum of:
- Their own staked tokens
- All tokens delegated to them by others

This weight determines how much influence they have during the consensus polling process.

### Staking Lifecycle

1. **Submission**: Validators or delegators submit staking transactions with a specified duration
2. **Pending**: Stake enters a pending state until the start time
3. **Active**: Validators participate in consensus and earn rewards
4. **Completion**: At the end of the staking period, rewards are distributed and stake is unlocked

### Consensus Participation

Validators with sufficient stake participate in Avalanche's consensus mechanism by repeatedly polling small random samples of other validators, weighted by their stake. The consensus algorithm itself—including Snowman consensus for linear chains—is covered in detail in the [Avalanche Consensus section](/academy/avalanche-fundamentals/avalanche-consensus-intro).

Unlike traditional Delegated Proof of Stake (DPoS) systems where a fixed number of delegates are elected, Avalanche allows **anyone meeting the minimum stake requirement** to become a validator. There's no voting mechanism to elect validators—participation is purely stake-based, making it more permissionless and decentralized.



# Staking Token Selection (/academy/permissionless-l1s/02-proof-of-stake/02-staking-token)

---
title: Staking Token Selection
description: Learn about staking on Avalanche L1s
updated: 2025-03-13
authors: [nicolasarnedo]
icon: BookOpen
---

The Proof of Stake algorithm covered in the previous section is available for your own L1 if you decide to build a permissionless blockchain. One of the key design decisions you'll need to make is choosing which token will serve as your staking token.

## Separating Staking and Native Tokens

In many networks, such as Ethereum, the same token is used for both staking and paying for gas. However, **Avalanche L1s offer the flexibility to separate staking tokens from native (gas) tokens**, as they fulfill fundamentally different purposes:

- **Native Token (Gas Token)**: Used to pay for transaction fees and execute smart contracts on your L1
- **Staking Token**: Used to secure the network through the Proof of Stake mechanism

### Why Use the Same Token?

Using your native token as the staking token creates a unified economic model where:
- Validators have a direct stake in the L1's success
- Token utility is maximized (both for transactions and security)
- The economic security is directly tied to your L1's value

### Why Use a Different Token?

Alternatively, you might choose to use a separate staking token (such as AVAX or another established token) when:
- You want to bootstrap security from an existing liquid token
- Your native token is designed for specific use cases that don't align with staking economics
- You want to leverage an established validator set from another network

## Critical Design Consideration: Token Liquidity

If you decide to use an alternative token (rather than your native token) as your staking token, **you must choose a token with substantial liquidity and market depth**. This is a critical security consideration.

### The Liquidity Attack Vector

Using a low-liquidity token as your staking token exposes your L1 to a potentially devastating attack:

1. **Attack Scenario**: A malicious actor could take out a large loan or use existing capital to purchase a majority of the staking token
2. **Network Takeover**: With >51% of the staking token, they gain control of your network's consensus
3. **Exploitation**: They could halt the network, double-spend, censor transactions, or otherwise disrupt operations
4. **Exit**: After causing damage or extracting value, they could sell back the staking tokens (potentially at a profit if they shorted your native token)

### Liquidity Requirements

When selecting an alternative staking token, evaluate:
- **Market Capitalization**: Is it large enough that acquiring 51% would be prohibitively expensive?
- **Daily Trading Volume**: Can large amounts be bought without significantly moving the price?
- **Market Depth**: Are there sufficient orders on both sides of the order book?
- **Distribution**: Is the token widely distributed, or controlled by a few large holders?

# Liquid Staking (/academy/permissionless-l1s/02-proof-of-stake/03-liquid-staking)

---
title: Liquid Staking
description: Learn about Liquid Staking and its role in the Avalanche ecosystem.
updated: 2025-03-13
authors: [nicolasarnedo]
icon: BookOpen
---

**Liquid Staking** is an innovative mechanism in blockchain networks that allows users to stake their tokens to secure the network while maintaining liquidity. In the Avalanche ecosystem, liquid staking enables participants to earn staking rewards without locking up their assets entirely, providing flexibility and additional opportunities for yield.

---

## Understanding Liquid Staking

In traditional staking, users lock up their tokens to support network operations like block validation and consensus. While staked, these tokens are illiquid and cannot be used for other purposes until the staking period ends. Liquid staking addresses this limitation by issuing **staking derivatives** or **liquid tokens** that represent the staked assets.

### How It Works

- **Stake Tokens**: Users stake their AVAX or other supported tokens through a liquid staking provider.
- **Receive Liquid Tokens**: In return, they receive liquid tokens equivalent to their staked amount.
- **Earn Rewards**: Users continue to earn staking rewards over time.
- **Maintain Liquidity**: Liquid tokens can be traded, transferred, or used in decentralized finance (**DeFi**) applications.
- **Redeem Staked Assets**: At any time, users can redeem their liquid tokens for the original staked assets, subject to network protocols.

---

## Benefits of Liquid Staking

### Enhanced Liquidity

- **Flexibility**: Users can participate in staking without sacrificing access to their assets.
- **DeFi Integration**: Liquid tokens can be used in lending, borrowing, or yield farming platforms, maximizing potential returns.

### Increased Capital Efficiency

- **Dual Rewards**: Earn staking rewards and additional yields from DeFi activities simultaneously.
- **Portfolio Diversification**: Utilize staked assets in various financial strategies without unstaking.

### Network Security

- **Higher Participation**: Lower barriers encourage more users to stake, enhancing network security and decentralization.
- **Economic Incentives**: Aligns individual incentives with network health by rewarding active participation.

### Consensus Risk

- **Recursive Leverage**: Using liquid staking tokens as collateral to repeatedly borrow and stake can lead to outsized influence over network consensus, especially in smaller chains.
- **Mitigation**: Limit LTV ratios, apply rate limits, and promote validator decentralization.

---

## Liquid Staking Providers on Avalanche

### Gogopool

[Gogopool](https://gogopool.com) is a prominent liquid staking provider in the Avalanche ecosystem. It offers a user-friendly platform for staking AVAX tokens while retaining liquidity through their liquid staking token.

#### Features of Gogopool

- **Secure Staking**: Utilizes robust smart contracts audited for security.
- **Competitive Rewards**: Offers attractive staking yields.
- **Easy Integration**: Provides seamless integration with popular DeFi platforms on Avalanche.
- **Community Support**: Active support channels and resources for users.

---

## Considerations and Risks

While liquid staking offers numerous benefits, users should be aware of potential risks:

### Smart Contract Risk

- **Vulnerabilities**: Liquid staking relies on smart contracts that may have undiscovered bugs or vulnerabilities.
- **Mitigation**: Choose providers like Gogopool that have undergone thorough security audits.

### Market Risk

- **Price Volatility**: The value of liquid tokens may fluctuate based on market conditions.
- **Liquidity**: Ensure there is sufficient market liquidity to trade liquid tokens without significant slippage.

### Protocol Risk

- **Slashing Penalties**: In cases of validator misconduct, staked assets may be slashed, affecting the value of liquid tokens.
- **Validator Selection**: Use reputable providers that delegate stakes to trustworthy validators.

---

## Conclusion

Liquid staking enhances the staking experience on Avalanche by combining the benefits of network participation with the flexibility of liquidity. Providers like [Gogopool](https://gogopool.com) make it accessible and secure for users to maximize their asset utility.

By understanding the mechanics and benefits of liquid staking, participants can make informed decisions that align with their investment strategies and contribute to the overall health and decentralization of the Avalanche network.

---

# Staking Contract (post Etna Upgrade) (/academy/permissionless-l1s/06-staking-contract/03-staking-contract-post-etna)

---
title: Staking Contract (post Etna Upgrade)
description: How staking will work post Etna upgrade
updated: 2024-09-03
authors: [0xstt]
icon: Book
---
import { Steps, Step } from 'fumadocs-ui/components/steps';

The contracts in the [`validator-manager`](https://github.com/ava-labs/icm-contracts/tree/main/contracts/validator-manager) branch define the Validator Manager used to manage Subnet-only Validators, as defined in [ACP-77](https://github.com/avalanche-foundation/ACPs/tree/main/ACPs/77-reinventing-subnets). `ValidatorManager.sol` is the top-level abstract contract that provides the basic functionality. The other contracts are related as follows:

<Mermaid chart={`classDiagram
    class ValidatorManager {
        <<abstract>>
        initializeValidatorSet()
        initializeValidatorRegistration()*
        completeValidatorRegistration()
        initializeEndValidation()*
        completeEndValidation()
    }
    class PoSValidatorManager {
        <<abstract>>
        initializeEndValidation()
        completeDelegatorRegistration()
        initializeEndDelegation()
        completeEndDelegation()
    }
    class ERC20TokenStakingManager {
        initializeValidatorRegistration()
        initializeDelegatorRegistration()
    }
    class NativeTokenStakingManager {
        initializeValidatorRegistration() payable
        initializeDelegatorRegistration() payable
    }
    class PoAValidatorManager {
        initializeValidatorRegistration()
        initializeEndValidation()
    }

    ValidatorManager <|-- PoSValidatorManager
    ValidatorManager <|-- PoAValidatorManager
    PoSValidatorManager <|-- ERC20TokenStakingManager
    PoSValidatorManager <|-- NativeTokenStakingManager
`} />
## Deploying

Three concrete `ValidatorManager` contracts are provided - `PoAValidatorManager`, `NativeTokenStakingManager`, and `ERC20TokenStakingManager`. `NativeTokenStakingManager`, and `ERC20TokenStakingManager` implement `PoSValidatorManager`, which itself implements `ValidatorManager`. These are implemented as [upgradeable](https://github.com/OpenZeppelin/openzeppelin-contracts-upgradeable) contracts. There are numerous [guides](https://blog.chain.link/upgradable-smart-contracts/) for deploying upgradeable smart contracts, but the general steps are as follows:
<Steps>
<Step>
Deploy the implementation contract
</Step>
<Step>
Deploy the proxy contract
</Step>
<Step>
Call the implementation contract's `initialize` function
  - Each flavor of `ValidatorManager` requires different settings. For example, `ValidatorManagerSettings` specifies the churn parameters, while `PoSValidatorManagerSettings` specifies the staking and rewards parameters.
</Step>
<Step>
Initialize the Validator set by calling `initializeValidatorSet`
  - When a Subnet is first created on the P-Chain, it must be explicitly converted to a Subnet-only Validator compatible Subnet via [`ConvertSubnetTx`](https://github.com/avalanche-foundation/ACPs/tree/main/ACPs/77-reinventing-subnets#setting-a-subnet-manager). The resulting `SubnetConversionMessage` Warp message is provided in the call to `initializeValidatorSet` to specify the starting Validator set in the `ValidatorManager`. Regardless of the implementation, these initial Validators are treated as PoA and are not eligible for staking rewards.
</Step>
</Steps>
### PoAValidatorManager

Proof-of-Authority Validator management is provided via `PoAValidatorManager`, which restricts modification of the Validator set to an owner address. After deploying `PoAValidatorManager.sol` and a proxy, the `initialize` function takes the owner address, in addition to standard `ValidatorManagerSettings`.

### PoSValidatorManager

Proof-of-Stake Validator management is provided by the abstract contract `PoSValidatorManager`, which has two concrete implementations: `NativeTokenStakingManager` and `ERC20TokenStakingManager`. In addition to basic Validator management provided in `ValidatorManager`, `PoSValidatorManager` supports uptime-based Validation rewards, as well as Delegation to a Validator. This [state transition diagram](https://github.com/ava-labs/icm-contracts/blob/main/contracts/validator-manager/StateTransition.md) illustrates the relationship between Validators and Delegators.

#### NativeTokenStakingManager

`NativeTokenStakingManager` allows permissionless addition and removal of Validators that post the Subnet's native token as stake. Staking rewards are minted via the Native Minter Precompile, which is configured with a set of addresses with minting privileges. As such, the address that `NativeTokenStakingManager` is deployed to must be added as an admin to the precompile. This can be done by either calling the precompile's `setAdmin` method from an admin address, or setting the address in the Native Minter precompile settings in the chain's genesis (`config.contractNativeMinterConfig.adminAddresses`). There are a couple of methods to get this address: one is to calculate the resulting deployed address based on the deployer's address and account nonce: `keccak256(rlp.encode(address, nonce))`. The second method involves manually placing the `NativeTokenStakingManager` bytecode at a particular address in the genesis, then setting that address as an admin.

```
{
    "config" : {
        ...
        "contractNativeMinterConfig": {
            "blockTimestamp": 0,
            "adminAddresses": [
                "0xffffffffffffffffffffffffffffffffffffffff"
            ]
        }
    },
    "alloc": {
        "0xffffffffffffffffffffffffffffffffffffffff": {
            "balance": "0x0",
            "code": "<NativeTokenStakingManagerByteCode>",
            "nonce": 1
        }
    }
}
```

#### ERC20TokenStakingManager
`ERC20TokenStakingManager` allows permissionless addition and removal of Validators that post the an ERC20 token as stake. The ERC20 is specified in the call to `initialize`, and must implement [`IERC20Mintable`](https://github.com/ava-labs/icm-contracts/blob/prorated-rewards-v2/contracts/validator-manager/interfaces/IERC20Mintable.sol). Care should be taken to enforce that only authorized users are able to call `mint`.

### Convert PoA to PoS

A `PoAValidatorManager` can later be converted to a `PoSValidatorManager` by upgrading the implementation contract pointed to by the proxy. After performing the upgrade, the `PoSValidatorManager` contract should be initialized by calling `initialize` as described above. The Validator set contained in the `PoAValidatorManager` will be tracked by the `PoSValidatorManager` after the upgrade, but will not be eligible to earn staking rewards, nor are they able to be delegated to.

## Usage
### Register a Validator
Validator registration is initiated with a call to `initializeValidatorRegistration`. Churn limitations are checked - only a certain (configurable) percentage of the total weight is allowed to be added or removed in a (configurable) period of time. The `ValidatorManager` then constructs a [`RegisterSubnetValidatorMessage`](https://github.com/ava-labs/icm-contracts/blob/prorated-rewards-v2/contracts/validator-manager/MessageSpec.md#registersubnetvalidatormessage) Warp message to be sent to the P-Chain. Each Validator registration request includes all of the information needed to identify the Validator and its stake weight, as well as an `expiry` timestamp before which the `RegisterSubnetValidatorMessage` must be delivered to the P-Chain. If the Validator is not registered on the P-Chain before the `expiry`, then the Validator may be removed from the contract state by calling `completeEndValidation`.

The `RegisterSubnetValidatorMessage` is delivered to the P-Chain as the Warp message payload of a [`RegisterSubnetValidatorTx`](https://github.com/avalanche-foundation/ACPs/tree/main/ACPs/77-reinventing-subnets#registersubnetvalidatortx). Please see the transaction [specification](https://github.com/avalanche-foundation/ACPs/tree/main/ACPs/77-reinventing-subnets#step-2-issue-a-registersubnetvalidatortx-on-the-p-chain) for validity requirements. The P-Chain then signs a [`SubnetValidatorRegistrationMessage`](https://github.com/ava-labs/icm-contracts/blob/prorated-rewards-v2/contracts/validator-manager/MessageSpec.md#subnetvalidatorregistrationmessage) Warp message indicating that the specified Validator was successfully registered on the P-Chain.

The `SubnetValidatorRegistrationMessage` is delivered to the `ValidatorManager` via a call to `completeValidatorRegistration`. For PoS Validator Managers, staking rewards begin accruing at this time.

### Remove a Validator
Validator exit is initiated with a call to `initializeEndValidation` on the `ValidatorManager` , For `PoSValidatorManagers` a [`ValidationUptimeMessage`](https://github.com/ava-labs/icm-contracts/blob/prorated-rewards-v2/contracts/validator-manager/MessageSpec.md#validationuptimemessage) Warp message may optionally be provided in order to calculate the staking rewards; otherwise the latest received uptime will be used (see [(PoS only) Submit and Uptime Proof](#pos-only-submit-an-uptime-proof)). This proof may be requested directly from the Subnet Validators, which will provide it in a `ValidationUptimeMessage` Warp message. If the uptime is not sufficient to earn Validation rewards, the call to `initializeEndValidation` will fail. `forceInitializeEndValidation` acts the same as `initializeEndValidation`, but bypasses the uptime-based rewards check. Once `initializeEndValidation` or `forceInitializeEndValidation` is called, staking rewards cease accruing for `PoSValidatorManagers`. 

The `ValidatorManager` contructs a [`SetSubnetValidatorWeightMessage`](https://github.com/ava-labs/icm-contracts/blob/prorated-rewards-v2/contracts/validator-manager/MessageSpec.md#SubnetValidatorWeightMessage) Warp message with the weight set to `0`. This is delivered to the P-Chain as the payload of a [`SetSubnetValidatorWeightTx`](https://github.com/avalanche-foundation/ACPs/tree/main/ACPs/77-reinventing-subnets#setsubnetvalidatorweighttx). The P-Chain acknowledges Validator exit by signing a `SubnetValidatorRegistrationMessage` with `valid=0`, which is delivered to the `ValidatorManager` by calling `completeEndValidation`. The Validation is removed from the contract's state, and for `PoSValidatorManagers`, staking rewards are disbursed and stake is returned.

#### Disable a Validator Directly on the P-Chain

ACP-77 also provides a method to disable a Validator without interacting with the Subnet directly. The P-Chain transaction [`DisableValidatorTx`](https://github.com/avalanche-foundation/ACPs/tree/main/ACPs/77-reinventing-subnets#disablevalidatortx) disables the Validator on the P-Chain. The disabled Validator's weight will still count towards the Subnet's total weight. 

Disabled Subnet Validators can re-activate at any time by increasing their balance with an `IncreaseBalanceTx`. Anyone can call `IncreaseBalanceTx` for any Validator on the P-Chain. A disabled Validator can only be totally removed from the Validator set by a call to `initializeEndValidation`.

### (PoS only) Register a Delegator

`PoSValidatorManager` supports Delegation to an active Validator as a way for users to earn staking rewards without having to validate the chain. Delegators pay a configurable percentage fee on any earned staking rewards to the host Validator. A Delegator may be registered by calling `initializeDelegatorRegistration` and providing an amount to stake. The Delegator will be registered as long as churn restrictions are not violated. The Delegator is reflected on the P-Chain by adjusting the Validator's registered weight via a [`SetSubnetValidatorWeightTx`](https://github.com/avalanche-foundation/ACPs/tree/main/ACPs/77-reinventing-subnets#setsubnetvalidatorweighttx). The weight change acknowledgement is delivered to the `PoSValidatorManager` via a [`SubnetValidatorWeightMessage`](https://github.com/ava-labs/icm-contracts/blob/prorated-rewards-v2/contracts/validator-manager/MessageSpec.md#SubnetValidatorWeightMessage), which is provided by calling `completeDelegatorRegistration`.

> The P-Chain is only willing to sign a `SubnetValidatorWeightUpdateMessage` for an active Validator. Once Validator exit has been initiated (via a call to `initializeEndValidation`), the `PoSValidatorManager` must assume that the Validator has been deactivated on the P-Chain, and will therefore not sign any further weight updates. Therefore, it is invalid to _initiate_ adding or removing a Delegator when the Validator is in this state, though it _may be_ valid to _complete_ an already initiated Delegator action, depending on the order of delivery to the P-Chain. If the Delegator weight change was submitted (and a Warp signature on the acknowledgement retrieved) before the Validator was removed, then the Delegator action may be completed. Otherwise, the acknowledgement of the Validation end must first be delivered before completing the Delegator action. 

### (PoS only) Remove a Delegator

Delegators removal may be initiated by calling `initializeEndDelegation`, as long as churn restrictions are not violated. Similar to `initializeEndValidation`, an uptime proof may be provided to be used to determine Delegator rewards eligibility. If no proof is provided, the latest known uptime will be used (see [(PoS only) Submit and Uptime Proof](#pos-only-submit-an-uptime-proof)). The Validator's weight is updated on the P-Chain by the same mechanism used to register a Delegator. The `SubnetValidatorWeightUpdateMessage` from the P-Chain is delivered to the `PoSValidatorManager` in the call to `completeEndDelegation`.

### (PoS only) Submit an Uptime Proof

The [rewards calculater](https://github.com/ava-labs/icm-contracts/blob/prorated-rewards-v2/contracts/validator-manager/interfaces/IRewardCalculator.sol) is a function of uptime seconds since the Validator's start time. In addition to doing so in the calls to `initializeEndValidation` and `initializeEndDelegation` as described above, uptime proofs may also be supplied by calling `submitUptimeProof`. Unlike `initializeEndValidation` and `initializeEndDelegation`, `submitUptimeProof` may be called by anyone, decreasing the likelihood of a Validation or Delegation not being able to claim rewards that it deserved based on its actual uptime.

### (PoS only) Collect Staking Rewards
#### Validation Rewards

Validation rewards are distributed in the call to `completeEndValidation`.

#### Delegation Rewards

Delegation rewards are distributed in the call to `completeEndDelegation`.

#### Delegation Fees

Delegation fees owed to Validators are _not_ distributed when the Validation ends as to bound the amount of gas consumed in the call to `completeEndValidation`. Instead, `claimDelegationFees` may be called after the Validation is completed.

<Quiz quizId="210" />


# Registering PoS Validators (/academy/permissionless-l1s/07-staking-manager-operations/04-register-validators)

---
title: Registering PoS Validators
description: Learn how validators are registered on the Avalanche network post-etna.
updated: 2024-10-14
authors: [owenwahlgren]
icon: Terminal
---

> How does it all work? I mean *actually* work.

### Sending Warp Messages

On the EVM, a warp message is simply an event log with `messageID = sha256(messagePayload)` Nothing is ever actually “sent” anywhere, which trips people up when first learning how Warp Messaging works.

The log event emitted is from the Warp precompile address (`0x0200000000000000000000000000000000000005`) The topic of the message will be `0x56600c567728a800c0aa927500f831cb451df66a7af570eb4df4dfbf4674887d` which is the output of 
```bash
cast keccak "SendWarpMessage(address,bytes32,bytes)"
```

To find a specific warp messageID, one must know the block number or block hash to retrieve the logs, or be monitoring all events, looking for and indexing messages. 

When a block is [accepted](https://github.com/ava-labs/coreth/blob/7242ae2d235593d2bb14e2496b6ed102aab14c3d/precompile/contracts/warp/config.go#L130) by the network, a precompile hook is called, and the EVM saves the warp message to a local database. The validator node will then be willing to sign any messages in that database upon request, typically via an `AppRequest` message over the p2p network.

### Receiving Warp Messages

On the EVM, any smart contract can call the precompile

which returns the warp message and verifies the attached signature. But what is `index`? Where does it get the warp message from?  The answer is, you!  When you send a tx to any contract that eventually calls `getVerifiedWarpMessage`, you **must** pass in the signed warp message as a “predicate”.  It’s called an AccessList, and typically this is an optional field that can be used by the EVM to pre-fetch storage slots that will be accessed, for efficiency and reducing gas costs. But Warp cleverly (ab)uses this feature of the EVM to verify the signature of the warp message, and then make the warp message available during the transactions lifetime, by calling `getVerifiedWarpMessage`. You can pass multiple warp messages which is where the `index` comes in.  (All of this is abstracted away by ICM for EVM to EVM comms)

Details: [Warp README](https://github.com/ava-labs/coreth/blob/7242ae2d235593d2bb14e2496b6ed102aab14c3d/precompile/contracts/warp/README.md)

### Interchain Messaging Contracts (ICM)

[ICM](https://github.com/ava-labs/icm-contracts) is a set of smart contracts that implements a rich messaging protocol on top of the Warp Messaging primitive, allowing for verified message passing between EVM chains. 

<Callout>
**Only (currently) supports EVM→EVM comms. Not used for EVM→P-Chain**
</Callout>

### Relayer

[Relayer](https://github.com/ava-labs/awm-relayer/blob/main/relayer/README.md) is an off-chain program that listens for warp messages on a source chain, and delivers them to a destination chain.  Messages can choose to be relayed by anyone, or by only privileged relayers. Messages can also pay fees to incentivize relayers and cover gas costs.

## Registering ValidatorManager

ACP-77 introduces L1-only Validators, that stake no AVAX, and do not validate the X/C chains. They must connect to the Primary Network and track the P-Chain, and also validate their own chain, and pay a small continuous fee in AVAX to the network.

User submits EVM tx to smart contract [NativeTokenStakingManager.sol](https://github.com/ava-labs/icm-contracts/blob/main/contracts/validator-manager/NativeTokenStakingManager.sol)

```solidity
function initializeValidatorRegistration(
        ValidatorRegistrationInput calldata registrationInput,
        uint16 delegationFeeBips,
        uint64 minStakeDuration) payable returns (bytes32 validationID)
```
Notably, this function will:

- Lock the native tokens in the contract
- `validationID`: bytes32 hash of an encoded `RegisterSubnetValidatorMessage`
- `messageID`: bytes32 hash of the warp message
- Store some data in the contract:


```solidity
$._pendingRegisterValidationMessages[validationID] = registerSubnetValidatorMessage;
$._registeredValidators[input.nodeID] = validationID;
bytes32 messageID = WARP_MESSENGER.sendWarpMessage(registerSubnetValidatorMessage);
$._validationPeriods[validationID] = Validator({
  status: ValidatorStatus.PendingAdded,
  nodeID: input.nodeID,
  startingWeight: weight,
  messageNonce: 0,
  weight: weight,
  startedAt: 0, // The validation period only starts once the registration is acknowledged.
  endedAt: 0
});
```

- Emit `ValidationPeriodCreated(validationID, nodeID, messageID, weight, registrationExpiry)`
- The `sendWarpMessage` precompile will emit a log with `sender`, `messageID`, `message`

At this point, we have submitted a transaction on the blockchain (C-Chain or L1, wherever the staking contract is deployed). All that has happened is we have stored some state in our contract and emitted some events. No changes to validators has occurred.

<Callout>
Nothing else will happen UNLESS an off-chain actor continues the process.
</Callout>


In our case, someone must be running a relayer that is configured with our staking contract as the source and the P-Chain as the destination.

<Callout>
At the moment, the relayer does not support the P-Chain, so messages must be signed and sent manually. The relayer will be updated soon to support the P-Chain.
</Callout>


So, to sign and send the message ourselves, we can use the Signature Aggregator server in the relayer project. This will use the p2p layer of the Avalanche network to connect to validators and send `AppRequest` messages to request each validator to sign a message.
```bash
curl --location 'http://localhost:8080/aggregate-signatures' \
--json '{"message": "<hex encoded unsigned message bytes retrieved from the logs>"}'
```
This will give us an aggregated BLS signature from at least 67% of the stake weighted validator set. Now we need to `POST` this to the P-Chain via the `RegisterSubnetValidatorTx` tx.

The P-Chain, if it accepts the tx, will “send” a Warp Message `SubnetValidatorRegistration` which acknowledges the change. Note that nothing is actually “sent”, instead the validator node will be willing to sign the unsigned message upon request.

So the next step is to use the Signature Aggregator service again, and provide the unsigned `SubnetValidatorRegistration` warp message, which the service will then ask validators to sign.

<Callout>
If your Validator Manager contract is on your L1 (instead of C-Chain), as an optimization, you only need to ask 67% of the stake weighted validators of your L1, not the entire P-Chain validator set.
</Callout>


Once an aggregate BLS signature is created, we need to submit the signed message to the C-Chain (or L1) by calling a function on the `ValidatorManager` contract.

```solidity
function completeValidatorRegistration(uint32 messageIndex)
```

Remember, this involves calling the function via `eth_sendTransaction` and encoding the signed warp message into the `AccessList`. (If you encode an array of 1 warp message, then `messageIndex` would be 0)

The function will adjust the state in the contract, including these bits:
```solidity
delete $._pendingRegisterValidationMessages[validationID];
$._validationPeriods[validationID].status = ValidatorStatus.Active;
$._validationPeriods[validationID].startedAt = uint64(block.timestamp);
```
And that’s it!

<Callout>
This doc is a WIP and we will eventually cover all the flows and add some diagrams.
</Callout>


# Avalanche Starter Kit (/academy/solidity-foundry/02-avalanche-starter-kit/01-avalanche-starter-kit)

---
title: Avalanche Starter Kit
description: Environment Setup
updated: 2024-05-31
authors: [martineckardt]
icon: Book
---

To make easier your journey through this course, we have prepared a Starter Kit repo consisting of everything you will need to start developing your own dApps on Avalanche. This repo will provide a self-contained environment with Avalanche-CLI, and Foundry so you can follow the course without the need of installing anything else other than launching the environment.

## What You Will Learn

In this section, you will go through the following topics:

- How to launch your own Codespace
- Create your own Interchain Messaging Enabled Custom Blockchain
- Foundry configuration

At the end of this section, you will have your environment ready to follow with the Cross-Chain dApp development with Interchain Messaging

# Set Up Avalanche Starter Kit (/academy/solidity-foundry/02-avalanche-starter-kit/02-set-up)

---
title: Set Up Avalanche Starter Kit
description: Environment Setup
updated: 2024-05-31
authors: [martineckardt]
icon: Terminal
---

import SetUp from "@/content/common/avalanche-starter-kit/set-up.mdx";

<SetUp />

# Close and Reopen Codespace (/academy/solidity-foundry/02-avalanche-starter-kit/03-close-and-reopen-codespace)

---
title: Close and Reopen Codespace
description: Environment Setup
updated: 2024-05-31
authors: [martineckardt]
icon: Terminal
---

import CloseAndReopen from "@/content/common/codespaces/close-and-reopen-codespace.mdx";

<CloseAndReopen />

# Create a Blockchain (/academy/solidity-foundry/02-avalanche-starter-kit/03-create-blockchain)

---
title: Create a Blockchain
description: Environment Setup
updated: 2024-05-31
authors: [martineckardt]
icon: Terminal
---

import CreateDefaultBlockchain from "@/content/common/avalanche-starter-kit/create-default-blockchain.mdx";

In order to send messages between two chains, we need to create a blockchain. In this guide, we will spin up a local Avalanche network that has it's own Primary Network (C-, P- and X-Chain) using the Avalanche CLI. Furthermore, we will create a blockchain in that Avalanche network, so we can send messages between the C-Chain and the newly created blockchain in the next chapters.

<CreateDefaultBlockchain/>

# Networks (/academy/solidity-foundry/02-avalanche-starter-kit/04-networks)

---
title: Networks
description: Environment Setup
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

import Networks from "@/content/common/avalanche-starter-kit/networks.mdx";

You just deployed and interacted with your first local network. But what does that mean? You can interact with your Avalanche L1, but you will notice that no one else can. Therefore, we have to understand what different Networks are in Avalanche.

<Networks/>

# Pause and Resume (/academy/solidity-foundry/02-avalanche-starter-kit/05-pause-and-resume)

---
title: Pause and Resume
description: If you've deployed an Avalanche L1, you can preserve and restore the state of your deployed Avalanche L1s.
updated: 2024-10-07
authors: [0xstt]
icon: BookOpen
---

import PauseAndResume from "@/content/common/avalanche-starter-kit/pause-and-resume.mdx";

<PauseAndResume />


# Building Programs on Blockchain (/academy/solidity-foundry/03-smart-contracts/01-building-programs-on-blockchain)

---
title: Building Programs on Blockchain
description: Learn what a Smart Contract is
updated: 2024-06-28
authors: [Andrea Vargas, Ash]
icon: Book
---

First off, thank you for enrolling in this course! We assume that you are taking this course in order to learn how to write smart contracts. This begs the question - what are smart contracts?

From a high-level, you may have heard that smart contracts are just code that automate a process. Want to create a decentralized insurance protocol? You can build a smart contract for that. Want to create and distribute NFTs? You can also build a smart contract for that as well. So while we might understand the capabilities of a smart contract, this course will be focused on defining the actual code (and therefore, business logic) required for such intents.

## The EVM Model
In this course, we will learn Solidity, a high-level programming language that we will use to design smart contracts. Before we delve into learning Solidity, it is important to understand how our smart contracts operate in the grand scheme of things.

Smart contracts are defined by the following: their behaviors and their state. Focusing first on the behaviors of a smart contract, this is simply the functions that one can call on the smart contracts. Examples of such behaviors can be found below:

- __Tokens__: behaviors include creating tokens, transferring them, getting the balances of token holders
- __Decentralized Exchange__: behaviors include swapping tokens, adding liquidity to a pool, getting the adresses of both tokens of a liquidity pools
- __DAO__: behaviors include submitting a proposal, voting on a proposal, checking if someone is a governance member

We now focus on the state of a contract. Abstractly, we can define the state of a contract as being the values and stateful data structures that are associated with said contract. Examples of the state of a smart contract are listed below:

- __Tokens__: the name of the token, the symbol of the token, the balances of the users
- __Decentralized Exchange__: the number of tokens of a liquidity pool, the amount of tokens a liquidity provider is entitled to
- __DAO__: a list of all governance members, a list of all outstanding proposals

Understanding what a smart contract under the EVM model consists of, we are now ready to understand the relationship between Solidity and the underlying blockchain.

# What is Solidity (/academy/solidity-foundry/03-smart-contracts/02-what-is-solidity)

---
title: What is Solidity
description: Learn what a Smart Contract is
updated: 2024-06-28
authors: [Andrea Vargas, Ash]
icon: Book
---
Our objective throughout this course is to learn how to define the code required to implement a smart contract that matches our intent. The previous section, furthermore, told us that all smart contracts are defined by their state and their behaviors. Therefore, we claim the following:

> Solidity is a high-level programming language which allows us to define both the state and behaviors of a smart contract.

Although these behaviors can be almost anything, the majority of the time, such behaviors manipulate the state of the contract. 

## Solidity v.s. Other Programming Languages

The first question one might have when learning a new language is the following: what does the language even look like? To start, we consider the following code snippet:

```solidity
contract A {
    function getOne() public pure returns(uint) {
        return 1;
    }
}
```

In the above, we have a contract named A. Furthermore, we see that A contains a function getOne() that, when called, returns 1. Even though you might not understand everything that is going on in the code snippet, web developers may realize that the code snippet looks similar to JavaScript. The Solidity syntax, as a matter of fact, is actually inspired by JavaScript, and is a testament to the fact that Solidity itself is a high-level programming language.

Now that we have an idea of what both Solidity allows us to do and what the actually syntax of Solidity looks like, its time to learn the actual language itself.

# Foundry Quickstart (/academy/solidity-foundry/03-smart-contracts/03-foundry-quickstart)

---
title: Foundry Quickstart
description: Environment Setup
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

import FoundryQuickstart from "@/content/common/avalanche-starter-kit/foundry-quickstart.mdx";

In this chapter, we will look into the Foundry that will be used to deploy and interact with smart contracts on the Avalanche network in our Avalanche Starter kit.

<FoundryQuickstart/>

# Create a new Smart Contract (/academy/solidity-foundry/03-smart-contracts/04-create-new-smart-contract)

---
title: Create a new Smart Contract
description: Learn what a Smart Contract is
updated: 2024-06-28
authors: [Andrea Vargas, Ash]
icon: Book
---

Alright, let's create our first contract. Head to the Avalanche Starter Kit Codespace and create a new folder called my-contracts in the _src_ folder.

Now in there create a new file called HelloWorld.sol and paste the following contents:

```solidity
contract HelloWorld {
    function sayHello() public pure returns (string memory) {
        return "Hello World";
    }
}
```

Now let's deploy the contract:

```bash
forge create --rpc-url local-c --private-key $PK src/my-contracts/HelloWorld.sol:HelloWorld --broadcast
```

If deployed successfully we should see something like this:

```bash
[⠒]
Deployer: 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC
Deployed to: 0x52C84043CD9c865236f11d9Fc9F56aa003c1f922
Transaction hash: 0x28247e1292e9489c3b51456e2b848eeb6b82ccbcda18836a638f5d81605ac508
```

This means we have deployed our contract to the address 0x52C84043CD9c865236f11d9Fc9F56aa003c1f922. Using this address we can now call our contract:

```bash
cast call --rpc-url local-c 0x52C84043CD9c865236f11d9Fc9F56aa003c1f922 "sayHello()(string)"
```

Don't forget to replace the contract address with the one your contract was deployed to. The result should look like this:

```solidity
"Hello World"
```

# Hello World! Part 1 (/academy/solidity-foundry/04-hello-world-part-1/01-intro)

---
title: Hello World! Part 1
description: Learn about Solidity
updated: 2024-06-28
authors: [Andrea Vargas, Ash]
icon: Book
---
In this chapter, our main objective will be to learn about the necessary components require to compile and deploy a smart contract. In particular, we want to be able to:

- Properly create a new Solidity file
- Understand how to organize the business logic of our contract

After learning the two main points above, you will be tasked with building your first smart contract! With the above in mind, let's get started.

# Primitive Values and Types (/academy/solidity-foundry/04-hello-world-part-1/02-primitive-value-and-types)

---
title: Primitive Values and Types
description: Learn about Solidity
updated: 2024-06-28
authors: [Andrea Vargas, Ash, martineckardt]
icon: Book
---

All code, regardless of the language it is written in, can be described (in very very simple terms) as the manipulation of values. Therefore, if we want to learn a new language, we should start at the type of values we will be manipulating; this is where we will start our Solidity journey.

## Declaring Variable

We first note that Solidity is a statically-typed language; this means that for any variable that we declare, we must declare its type at the time of initialization. Therefore, the general syntax for declaring a variable is as follows:

```solidity
<type> <name>;
```

The following are examples of us declaring variables in Solidity:

```solidity
address addr;
uint256 num;
bool b;
```

For right now, we won't focus on what the types mentioned above actually mean. However, the biggest takeaway is that for any variable that we initialize, we must declare its type.

## Defining Variables

Now that we know how to declare a variable in Solidity, the other half of the puzzle that we want to solve for is actually assigning a value to these variables. The following code snippet is an example of how we would assign values to variables:

```solidity
addr = 0x7f610402ccc4CC1BEbcE9699819200f5f28ED6e3;
num = 0;
b = false;
```

Rather than having to take the two separate steps of declaring a variable and then defining said variable, we can do these two steps in just line; the following code shows how we would do this:

```solidity
address addr = 0x7f610402ccc4CC1BEbcE9699819200f5f28ED6e3;
uint256 num = 0;
bool b = false;
```

## Types

Now that we've discussed the process of both declaring and defining a variable, let's return to the topic of types. In Solidity, the following is a (non-exhaustive) list of elementary types that are available:

- Unsigned Integers: any value which is an unsigned integer is a nonnegative integer. Furthermore, the unsigned integer type is not a singular type, but rather a group of unsigned integers types differentiated by their bit size. Any unsigned integer type has a bit size that is a multiple of 8. So the following types are valid unsigned integer types: uint8, uint16, uint24, uint32, ..., uint256 (uint256 is the maximum unsigned integer bit size). Furthermore, for any unsigned integer uintx (where x is a multiple of 8 and between 0 and 256), we have that the range of uintx is from 0 up to (but not including) 2^(x).
- Signed Integers: any value which is a signed integer is a integer that can be either negative or positive. Like the unsigned integer type, the signed integer type is a group of signed integer types differentiated by their bit size. Any signed integer type has a bit size that is a multipe of 8. Examples of signed integer types are the following: int8, int16, int24, ..., int256 (int256 is the maximum signed integer size). Furthermore, for any signed integer intx (where x is a multiple of 8 and between 0 and 256), we have that the range of intx is from -2^(x - 1) up to (but not including) 2^(x - 1)
- Addresses: the address type consists of a 20-byte value. This type, as its name might suggest, represents the address of an EVM account.
- Booleans: can be either true or false. Treating booleans as integers, a true value is equal to 1 while a false value is equal to 0.


# Functions (/academy/solidity-foundry/04-hello-world-part-1/03-functions)

---
title: Functions
description: Learn about Solidity
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

In this section, we will look at functions. Recall from the beginning of this course that all smart contracts consist of a state and their behaviors. With regards to the latter, functions allow us to define the behavior of a smart contract. 
## Structure of a Function
Similar to other programming languages, all functions consist of two sections: their header and their body. An example of the following can be found below:

```solidity
function getOne() public pure returns(uint) {
    return 1; 
}
```
In the above, we have the code function getOne() public pure returns(uint) as the header of the function, while the code return 1; is the body of the function (the body of a function is always encapsulated by curly brackets). 

## Function Header
Focusing first on the header of a function, below is the required syntax that all function must have:

```solidity
function <function_name>(<args>) <visibility>
```

In the parentheses, we list the parameters of the function. In addition to having a name, each parameter of a function must also be marked with its type. The only concept that might be new for most developers is the visibility of a function. In Solidity, we can mark a function with the following visibility traits:

- Public
- Private
- Internal
- External

## Function Body
As of right now, the only thing we know what to do inside the body of a function is declaring/defining local variables. Inside the bodies of functions, we can also use regular mathematical operations like in other programming languages; the following code demonstrates this:

```solidity
function getSquare(uint num) public returns(uint) {
    uint square = num ** 2;
    return square;
}
```

# Contracts (/academy/solidity-foundry/04-hello-world-part-1/04-contracts)

---
title: Contracts
description: Learn about Solidity
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

As the halfway mark between knowing absolutely nothing about programming smart contracts and being able to deploy smart contracts, we arrive at the concept of defining contracts themselves. Recall that smart contracts consist of the following:

- A state
- A set of behaviors

We will first start by defining the general structure of a smart contract, before diving into defining each individual component that makes a smart contract what it is.

## General Contract Structure
Below is the general syntax for a smart contract in Solidity:

```solidity
contract <ContractName> {
 
  // State Variables go here
  
  // Contract functions go here
  
}
```

We declare a contract with the contract keyword, followed by the name of the smart contract (which usually follows CamelCase notation). Afterwards, we use curly brackets to encapsulate the body of the smart contract.

## State Variables

The same workflow and rules regarding the declaration and definition of variables apply to variables associated with the state of a smart contract. State variables, as they're called, are persistent between transactions and can only be modified in the following two scenarios:
- During the initialization of the smart contract itself
- By a function of the smart contract itself

No other account can modify the variables of a smart contract directly; only the contract itself can. An example of state variables with a smart contract is as follows:

```solidity
contract A {
 
    uint256 num = 5;
  
}
```

## State Variable Visibility

- Solidity is an object-oriented programming language (where contracts act as classes) and so as we will see soon, contracts are able to inherit other contracts. However, we still want to define the inheritance properties of the state variables of a contract. Therefore, we introduce state variable visibility. The following are the three possible type of state variable visibilities:
- Public: the state variable is found in the parent contract and all children contract. Furthermore, any state variable defined as public will contain a getter function of the same name
- Internal: this is the same as public, except a getter function is not created. Any state variable not annotated with a visibility is, by default, set as internal
- Private: the state variable is found only in the parent contract - children contract do not inherit the state variable

> In this context, the private visibility does not mean that the value of the associated variable is accessible only to the contract. Anyone with access to the blockchain can find the value of a private variable. 

Below are examples of explicitly declaring the visibility of state variable:

```solidity
contract A {
​
    address private addr;
    uint internal num;
    int public numTwo;
  
}
```

## Contract Functions

Having gone over the state of a contract, we now discuss about contract functions, the second property of smart contracts and the logic that allows us to modify state variables. The same manner in which we declared and defined functions earlier also apply here. The only new thing here, however, is that our contract functions can modify the state variables of the associated contract. As an example, below is a contract with a state variable, and associated functions to get/set the values of the variable:

```solidity
contract A {
 
    uint num;
  
    function setNum(uint _num) public {
        num = _num; 
    }
  
    function getNum() public view returns(uint) {
        return num; 
    }

}
```

# Solidity File Structure (/academy/solidity-foundry/04-hello-world-part-1/05-solidity-file-structure)

---
title: Solidity File Structure
description: Learn about Solidity
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

Now that we understand how to write (very basic) smart contracts in their entirety, we are certainly ready to deploy smart contracts onto the blockchain... right?

Unfortunately, we are not yet ready to do so. To understand why, consider the EVM, the virtual machine which will be executing the logic of your smart contract. The EVM does not execute Solidity code - rather, it executes opcodes in the form of bytes. Therefore, for any Solidity smart contract that we develop, we need a way to convert it into EVM bytecode that the EVM can then parse. 

Although the above sounds like a complex task, this is actually not the case! All we need to do is put our smart contract logic into a .sol file, which a Solidity compiler can then convert into EVM bytecode!

## Compiler and License
At the top of every Solidity file goes the SPDX-License-Identifier. This identifier specifies how you wish for the source code of your file to be used by other people. The most popular SPDX-License-Identifier is the MIT identifier. Afterwards, we will want to specify the version of Solidity that we want to use to compile our source code. This is usually in the format of the following:

```solidity
pragma solidity <version>;
```

For more information regarding which version of Solidity you should use, head over to the official Solidity [documentation](https://docs.soliditylang.org/en/v0.8.28/) where you can find more information about the details of each release version. Generally speaking though, the following can be observed about the age of release versions:

- Older release versions are less optimized and lack many features of newer Solidity versions, but they have been battle-tested over the years and are thus more secure
- Newer release versions bring much-desired features and are more optimized, but have had less time to be tested for security purposes

Sometimes, you might see the following inside a Solidity file:

```solidity
pragma solidity ^<version>;
```

The caret specifies that the source file is meant to be compiled with any version of Solidity that is compatible with version. As an example, consider the line:
pragma solidity ^0.6.4;

Then the source file can be compiled with any version of Solidity that has the prefix 0.6. However, any compiler whose prefix does not match that of 0.6 cannot compile the source file above.

## Tying Everything Together
The below is an example of a Solidity source file that can be compiled into bytecode:

```solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;
​
contract A {
 
    uint256 num;
  
    function getNum() public view returns(uint) {
        return num; 
    }
  
    function setNum(uint _num) public {
        num = _num;
    }
  
}
```

# Build Basic Smart Contract (/academy/solidity-foundry/04-hello-world-part-1/06-build-basic-smart-contract)

---
title: Build Basic Smart Contract
description: Learn about Solidity
updated: 2024-05-31
authors: [martineckardt]
icon: BookOpen
---

Let's create and interact with the basic smart contract. Create a new solidity file called NumberStorage.sol and fill it with the contract below:

```solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;
​
contract NumberStorage {
 
    uint256 num;
  
    function getNum() public view returns(uint) {
        return num; 
    }
  
    function setNum(uint _num) public {
        num = _num;
    }
  
}
```

Now let's deploy it:

```bash
forge create --rpc-url local-c --private-key $PK src/my-contracts/NumberStorage.sol:NumberStorage --broadcast
```

The result should look something like this:
```bash
[⠒] Compiling...
[⠢] Compiling 1 files with 0.8.18
[⠆] Solc 0.8.18 finished in 14.67ms
Compiler run successful!
Deployer: 0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC
Deployed to: 0x17aB05351fC94a1a67Bf3f56DdbB941aE6c63E25
Transaction hash: 0x5717e501e12f40d644c60030bc0ab9569ddb9f4cba968546ab597fb516eae09b
```

Next, let's store a number:

```bash
cast send --rpc-url local-c --private-key $PK 0x17aB05351fC94a1a67Bf3f56DdbB941aE6c63E25 "setNum(uint)" 42
```

Since we are now writing to and not just reading from the blockchain we will see the transaction details:
```bash
blockHash               0x02eb13d317a43976ea8ba21a76e5deb6d02d257a0b98c1a84734e0609b8a6fec
blockNumber             3
contractAddress         
cumulativeGasUsed       43516
effectiveGasPrice       28000000000
from                    0x8db97C7cEcE249c2b98bDC0226Cc4C2A57BF52FC
gasUsed                 43516
logs                    []
logsBloom               0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000
root                    
status                  1
transactionHash         0xd382101a4955f05f8a96e4ab4b62457700697930dc6ed84246a346e51d41d3cb
transactionIndex        0
type                    2
to                      0x17aB05351fC94a1a67Bf3f56DdbB941aE6c63E25
```

Next, let's get the number from the storage:

```bash
cast call --rpc-url local-c 0x17aB05351fC94a1a67Bf3f56DdbB941aE6c63E25 "getNum()(uint)"
```
As a result we should get the number we have stored earlier:

```bash
@martineckardt ➜ /workspaces/avalanche-starter-kit (main) $ cast call --rpc-url local-c 0x17aB05351fC94a1a67Bf3f56DdbB941aE6c63E25 "getNum()(uint)"
42
```

# Hello World Part. 2 (/academy/solidity-foundry/05-hello-world-part-2/01-intro)

---
title: Hello World Part. 2
description: More about Solidity
updated: 2024-06-28
authors: [Andrea Vargas, Ash, martineckardt]
icon: Book
---

If you've made it this far into the course, congratulations! At this point so far, you are now able to write very simple smart contracts which can be compiled down into EVM bytecode and deployed onto the blockchain! In this chapter, we will consider the following questions:

- How can we utilize Solidity's built-in data structures?
- How can we use control flow in our functions?
- How can we store data on the blockchain in a cheap manner?
- How can we utilize contract constructors?
- What does the Solidity inheritance model look like?

In this chapter, we will tackle the questions above. By looking into these questions, we will learn the skills necessary for taking our smart contracts from being simple programs to complex ones.

# Control Flow (/academy/solidity-foundry/05-hello-world-part-2/02-control-flow)

---
title: Control Flow
description: More about Solidity
updated: 2024-06-28
authors: [Andrea Vargas, Ash, martineckardt]
icon: Book
---

When first learning about how to write smart contract functions, we first focus on making sure that our syntax is correct before everything else. Therefore, if you have looked deeply into your starter code, you will notice that your code is purely sequential. That is, every single line of code inside of your functions are executed in a linear manner. While easy to write and understand, writing purely sequential code means that our contracts will behave the exact same way, regardless of the arguments passed in or the state of the contract. If we want our functions to behave differently based on the arguments passed in and the state of the contract, we will want to embrace control flow in our code
## If/Else Statements
The first type of control flow that we will examine is the if/else statement; below is an example of an if/else statement in Solidity:
```solidity
if (<boolean-statement>) {
    
} else {
  
}
```
If we wanted to add multiple branches to our if/else statement, we would do the following:

```solidity
if (<boolean-statement>) {
    
} else if (<boolean-statement>) {
       
} else {
  
}
```

## For Loops
The next type of control flow that we will examine are for-loops; for-loops allow us to iterate over a range of integers. Below is the general syntax for for-loops:

```solidity
for (<loop-variable>; <loop-condition>; <loop-incrementer>) {
  
}
```

Below is an implementation of the factorial algorithm, which uses for-loops:

```solidity
function factorial(uint256 num) public pure returns(uint256) {
    if (num == 0) {
      return 1;
    } else if (num == 1) {
      return 1;
    }
    uint256 result = num;
    for (uint i = 2; i < num; i++) {
      result = result * i;
    }
    return result;
}
```
Although not necessary, we usual set the type of the loop variable to type uint256 (uint) as this will become useful when indexing into arrays.
## While Loops
The last type of control flow that we will examine are while loops. Below is the general syntax of while loops in Solidity:
```solidity
while (<boolean-condition>) {
       
}
```

# Data Structures (/academy/solidity-foundry/05-hello-world-part-2/03-data-structures)

---
title: Data Structures
description: More about Solidity
updated: 2024-06-28
authors: [Andrea Vargas, Ash, martineckardt]
icon: BookOpen
---
Like with all programming languages, Solidity offers us a way to store multiple values in one location via built-in data structures. In this section, we will look at the following:
- Mappings
- Static Arrays
- Dynamic Arrays

Let's get started!

## Mappings

Mappings in Solidity are similar to data structures like dictionaries found in other programming languages (e.g. Python). At its most basic level, mappings allow us to store key-value pairs. Unlike the types we explored earlier in this course, mappings can only be instantiated as state variables (i.e. we cannot create a new mapping data structure within the body of a function). Furthermore, declaring a mapping and defining key-values of a pair must be done separately. Below is the general syntax for a mapping:
```solidity
mapping(<key-type> => (value-type)) <optional-visibility> <mapping-name>;
```

Below shows an example of how to define a key-value pair within a mapping:

```solidity
mapping(address => uint) map;
​
map[0xc0ffee254729296a45a3885639AC7E10F9d54979 = 5;
```
## Nested Mappings

Below are some restrictions regarding mappings:
- Keys can be any simple type (i.e. types associated with a singular value)
- Values can be any type
Since keys can be any type, and mappings are types by definition, this implies that we can map keys to mappings! Therefore, the following is legal syntax:

```solidity
mapping(uint => mapping(uint => address)) mapTwo;
```

To work with inner mappings, the following code snippet gives an idea as to how to access such values:

```solidity
address addr = mapTwo[5][6];
```

## Structs
The next type of data structure that we will examine are structs. For those who have worked with C++ or any other similar programming languages, structs in Solidity are the same concept. Structs, or structures, are data structures which allow us to group multiple values. We can think of structs as very basic classes, except that they lack any sort of behavior and are solely used to store information. Like mappings, we first must define the layout of a struct within the body of a smart contract; below is an example of how we would do so:

```solidity
struct Person {
    uint256 age;
    string name;
}
```
To create an instance of a struct as a state variable, we can use the following syntax:

```solidity
Person person = Person(5, "Rodrigo");
```

> If you try using the syntax above in the body of a function, you will get an error regarding the location of the person variable. Since structs are a grouping of values, we must explictly state where these values are stored (either in memory or in storage). Therefore, we would want to use the following:

```solidity
Person memory person = Person(5, "Rodrigo")
```

## Static Arrays
The majority of programming languages provide some built-in data structures similar to lists. Solidity is no different in that it provides two types of list-like data structures:

- Static arrays
- Dynamic Arrays
Focusing first on static arrays, these are lists whose length is fixed at the time of initialization. This means that once a static array has been initialized, its length will never change. Below is the syntax to declare a static array:

```solidity
<array-type>[<array-size>] <array-name>;
```
Below is an example of declaring a static array:
```solidity
uint[5] arr;
```
With regards to declaring the value of a static array, we have two options:
### Static Arrays in Memory
For a static array in memory, we first must declare it using the memory keyword:
```solidity
<array-type>[<array-size>] memory <array-name>;
```
Assuming this has been handled, we can declare individual values via indexing; an example of this can be found below:
```solidity
function test() public {
        uint[] memory arr;
        arr[7] = 4;
    }
```
If we want to both declare and define a static array in memory, we can use the following:

```solidity
uint8[5] memory arr = [1, 2, 3, 4, 5];
```

### Static Arrays in Storage

If we want to declare the value of a value in storage, we can again use array indexing. Likewise, as with static arrays declared in memory, we can also declare and define at the same time a static array in storage.

## Dynamic Arrays

Dynamic arrays differ from static arrays in that their size is not fixed. That is, once initialized, a dynamic array can vary in length throughout its lifetime. Due to the complexity of the underlying implementation of dynamic arrays, dynamic arrays can only be assigned to state variables. Below is an example of how we would declare a dynamic array in storage:

```solidity
<array-type>[] <array-name>;
```

By default, a dynamic array will be empty (in contrast with static arrays, which will be filled with the default value of the array type). Therefore, we can use the following associated methods to manipulate the state of a dynamic array:
- push: pushes an element to the end of the dynamic array
- pop: removes the last element of a dynamic array

Below is an example of the methods above in action:
```solidity
uint[] arr;
​
function test() public {
    arr.push(1);
    arr.pop();
}
```

# Contract Constructor (/academy/solidity-foundry/05-hello-world-part-2/04-contract-constructor)

---
title: Contract Constructor
description: More about Solidity
updated: 2024-06-28
authors: [Andrea Vargas, Ash, martineckardt]
icon: BookOpen
---
As a segue to learning about the object-oriented programming aspect of Solidity, we will touch upon contract constructors. Similar to class constructors in other languages, constructors in Solidity allow us to define the state of a contract at the time of initialization.
## Syntax
Below is the general syntax for a contract constructor:

```solidity
constructor(<arguments>) {      
}
```
## Example
Below is an example of a contract constructor in action:

```solidity
contract A {
    uint num;
  
    constructor(uint _num) {
        num = _num;
    }
}
```

# Modifiers (/academy/solidity-foundry/05-hello-world-part-2/05-modifiers)

---
title: Modifiers
description: More about Solidity
updated: 2024-06-28
authors: [Andrea Vargas, Ash, martineckardt]
icon: BookOpen
---
Before discussing the concept of modifiers, we will first start by talking about the limitations of the visibilities provided by Solidity

## Aside: Limitations of Visibility

Recall that with regards to functions, we have the following four visibilities available:
- Public
- Private
- Internal
- External
Let's now consider the following contract:

```solidity
contract Safe {
  
  function deposit() public {}
  
  function withdraw() public {}
​
}
```
Above, we have the outline of a very basic safe contract which is meant to be accessed only by the deployer of the Safe contract. Currently, this Safe contract does not maintain the invariant previously mentioned as both deposit and withdraw are marked as public. However, even if we were to modify the visibility of the following functions, we would have the following:
- The functions become inaccessible to all accounts except the contract itself
- The functions still remain accessible to all accounts

The scenario above outlines the following problem: for functions whose access we want to restrict to only authorized users, we cannot rely on visibility.

## Modifying the Behavior of Functions via Modifiers

To combat the problem previously mentioned, we now look at modifiers. Modifiers behave similarly to functions and they modify the logic of the functions they are attached to. The syntax for defining a modifier is as follows:
```solidity
modifier <modifier-name>(<arguments>) {}
```
To attach a modifier to a function, we have the following:
```solidity
function func() public <modifier>(<arguments>){}
```
To introduce the concept of modifiers to our Safe contract, let's first modify it to the following:
```solidity
contract Safe {
  
  address owner;
  
  constructor() {
    owner = msg.sender; 
  }
  
  function deposit() public {}
  
  function withdraw() public {}
​
}
```
With the above changes, we are setting the state variable owner equal to the contract deployer (i.e. msg.sender) and so we are now able to store the address of the contract deployer in our Safe contract. Let's now write a modifier to only allows for the owner of the Safe contract to call the function it is attached to:
```solidity
modifier onlyOwner() {
  require(msg.sender == owner, "You are not the owner"!);
  _;
}
```
Examining each line, we have:
- Line 2: we are using a require statement; the require statement has the following syntax: require(boolean condition, error message). If the boolean condition is true, we move onto the next line of code. Otherwise, we raise an error with the error message provided in the statement. In this context, we are requiring that any person calling the function onlyOwner is attached to is the owner of the Safe contract.
- Line 3: assuming that the owner of the Safe contract is calling the associated function, we now revert control back to the original function via the _; keyword. 
Incorporating the modifier into our Safe contract we now have:

```solidity
contract Safe {
  
  address owner;
  
  modifier onlyOwner() {
  require(msg.sender == owner, "You are not the owner"!);
  _;
  }
  
  constructor() {
    owner = msg.sender; 
  }
  
  function deposit() public onlyOwner() {}
  
  function withdraw() public onlyOwner() {}
​
}
```
For either deposit or withdraw, we now have the following execution flow:
- An account first calls either deposit or withdraw
- Since the onlyOwner modifier is attached to either function, onlyOwner is first executed
- If the account is the contract owner, we return the execution flow back to the parent function (in this case, either deposit or withdraw)

# Events (/academy/solidity-foundry/05-hello-world-part-2/06-events)

---
title: Events
description: More about Solidity
updated: 2024-06-28
authors: [Andrea Vargas, Ash, martineckardt]
icon: BookOpen
---

Throughout this course, we have seen smart contract data stored in two places:
- State Variables (i.e. in storage)
- Function Bodies (i.e. in memory)

Let's now look at the advantages and disadvantages of each data location:

-Storage: this data location is persistent between transactions and so we don't have to worry about state variables being lost. However, reading and writing to storage is computationally expensive and therefore, requires a substantial amount of gas to perform.
-Memory:  this data location is not persistent between transactions; therefore, values that you write in memory in one transaction will be lost after the transaction is finished executing. However, reading and writing to storage is computationally cheap and therefore, requires little gas. 

This brings up a good question: what if we wanted to permanently store data (and lets assume that this data is immutable) on the blockchain without having to use state variables? This leads us to the topic of this section: events.

## Defining Events

Events are data structures that we can then "emit." We first examine the syntax for defining events:
```solidity
event <event_name>(event_args)
```

The definition of an event goes in the body of a smart contract (but never within a function body). Below is a simple example of an event definition:

```solidity
event Transfer(address _from, address _to, uint256 _value);
```

## Emitting Events

Now that we understand how to define events, we will now explore how to emit an instance of an event. Consider the following function:

```solidity
function emitEvent() public {}
```

To emit the transfer event we defined earlier, we implement the following:

```solidity
function emitEvent() public {
    emit Transfer(address(0), address(0), 0);
}
```

where the arguments of the Transfer event are arbitrary. 

# Contract Standarization (/academy/solidity-foundry/06-contract-standarization/01-contract-standarization)

---
title: Contract Standarization
description: Learn how to reuse standard code
updated: 2024-06-28
authors: [Andrea Vargas, Ash, martineckardt]
icon: Book
---

Perhaps the most famous contract standard, the ERC-20 interface allows for users to develop their own tokens that other users/contracts are able to interact with. To understand what the ERC-20 is from a high-level and why it's almost necessary, let's first consider the following scenario:

## Aside: Lack of Information

The concept of a token contract, while intuitive at first, begins to become quite complex when we consider what the implementation of such a contract consists of. As an example, consider a car. We know that a car is a vehicle that takes us from point A to point B; furthermore, we can say that cars move via wheels and we can dictate the direction of a car via a steering wheel. However, consider the following:

- How many seats does a car have?
- Do all cars come with a retractable sunroof?
- How is the car powered (i.e. via gasoline, electric, hydrogen, etc)?

The questions above do not break down the concept of a car, but rather, they complicate any product meant to complement a car. Let's now focus on tokens. Abstractly, we can state the following:

- All accounts have a balance of the token (even if its zero)
- We can transfer tokens from one account to another
- The token contract does not allow for double-spending and related forms of manipulation

Let's now write a token smart contract which achieves the following:

```solidity
contract Token {
​
    mapping(address => uint) balances;
​
    function transfer(address to, uint amount) public {
        require(balances[msg.sender] >= amount);
        balances[msg.sender] -= amount;
        balances[to] += amount;
    }
}
```

Tying back to our car example, lets assume we have another Token contract with the following implementation:

```solidity
contract Token {
​
    mapping(address => uint) balances;
​
    function transferTokens(address to, uint amount) public {
        require(balances[msg.sender] >= amount);
        balances[msg.sender] -= amount;
        balances[to] += amount;
    }
}
```

The code block above, logically, does the exact same thing as the original Token contract before it. However, notice that the function name in this case changed - we went from transfer to transferTokens. The above demonstrates for a user to interact with the either Token contract, they would first need to find out the name of the function associated with transferring tokens. 

But why stop there? We can also name the transfer function the following:

```solidity
function transferSomeTokens() public {}
function doTransfer() public {}
function sendTokens() public {}
// ...
```

As it might have become obvious, for any user that wants to interact with a particular Token contract, they would need to somehow find a way to get the correct function name or risk their transaction reverting. Furthermore, consider the case of a smart contract trying to call a Token contract. We would need to hardcode every single possible function name into our contract - something which is practically impossible. 

This entire section leads us to the conclusion that for concepts like token contracts to work, there cannot be a lack of information regarding the behaviors (and their associated names). There needs to be consensus regarding a standard for token contracts which everyone can turn to. The ERC-20 contract, in essence, is this standard.

# Inheritance (/academy/solidity-foundry/06-contract-standarization/02-inheritance)

---
title: Inheritance
description: Learn how to reuse standard code
updated: 2024-06-28
authors: [Andrea Vargas, Ash, martineckardt]
icon: Book
---
In the previous section, we foreshadowed inheritance, a concept that Solidity shares with other object-oriented programming languages. In this section, we will go over how to inherit other smart contracts and introduce inheritance in the concept of contract constructors.

## B is A

At the most fundamental level, contract inheritance works as follows:

```solidity
contract A {}
​
contract B is A {}
```

In the code snippet above, we have an arbitrary contract A and a contract B which inherits A. Although simple, this doesn't really explain the full concept of inheritance. Let's consider a more sophisticated example:

```solidity
contract A {
  uint num;
  
  function square(uint base) public pure returns(uint) {
        return base ** 2;
  }
}
​
contract B is A {}
```

In the code above, we have two contract A and B. The definition of contract A is nothing new, but what about contract B? Well, since B is inheriting A, this implies that B has the following properties:

- B has the state variable num
- B has the function square

To really drive home the idea of inheritance, let's consider this final code snippet:

```solidity
contract A {
  
  uint private num1;
  string internal name;
  
  function getOne() private pure returns(uint) {
    return 1;
  }
  
  function getTwo() public pure returns(uint) {
    return 2;
  }
}
​
contract B is A {}
```

The code snippet above is more sophisticated in that we are explicitly introducing visibility in the context of inheritance. Again, the definition of A should be trivial. Focusing on B, we have the following:

- B does not have the state variable num1 and the function getOne, since these are marked as private and therefore, belong only to A
- B has the state variable name since it is marked as internal and therefore, able to be derived by B
- B has the function getTwo since it is marked as public

## Constructors and Inheritance

Just like we can inherit functions from parent functions, we can also inherit constructors from parent contracts. The syntax for inheriting parent functions is as follows:

```solidity
constructor() <parent-name>() {}

```

An example of constructor inheritance can be found below:

```solidity

contract A {
  uint numl;
  constructor() {
    num1 = 5;
  }
}
​
contract B is A {
  uint num2;
  constructor() A() {
    num2 = 7;
  }
}   
```

For contract A, we are setting num1 equal to 5 at the time of initialization. For contract B, we first call the constructor of A (which sets num1 in B to 5) and then sets num2 to 7. 

# Interfaces (/academy/solidity-foundry/06-contract-standarization/03-interfaces)

---
title: Interfaces
description: Understanding Smart Contract Interfaces and Their Role in Standardization
updated: 2025-01-24
authors: [Andrea Vargas, Ash, martineckardt]
icon: Book
---

# Interfaces in Smart Contracts

## Introduction

In smart contract development, **interfaces** play a crucial role in ensuring standardization and interoperability between different contracts. By defining a consistent structure that contracts must adhere to, interfaces enable seamless integration across various decentralized applications (dApps), wallets, and protocols.

Some contracts such as **ERC-20, ERC-721, and ERC-1155** that we will cover later, leverage interfaces to create widely accepted token standards. These standards help different smart contracts interact efficiently without needing to understand each contract's internal implementation.

In this lesson, we will explore how interfaces work in Solidity, why they are important, and how they contribute to the broader ecosystem of dApps.

---

## What Is an Interface?

In Solidity, an **interface** is a contract type that defines function signatures without implementing them. This means that an interface only specifies which functions must exist in a contract but does not provide their actual logic.

Here’s an example of a simple Solidity interface:

```solidity
interface IExample {
    function getValue() external view returns (uint256);
    function setValue(uint256 _value) external;
}
```

Any contract that implements `IExample` must provide concrete implementations for the `getValue` and `setValue` functions.

---

## Why Are Interfaces Important?

Interfaces provide several benefits in smart contract development:

### 1. **Standardization**
   - Interfaces ensure that different contracts follow a common structure.
   - Examples include **ERC-20** for fungible tokens and **ERC-721** for NFTs, allowing various dApps and protocols to interact with them effortlessly.

### 2. **Interoperability**
   - Contracts that adhere to a shared interface can seamlessly interact without knowing each other’s internal implementation.
   - This is essential for decentralized finance (DeFi) protocols, where lending, staking, and trading contracts often need to communicate.

### 3. **Security and Modularity**
   - Developers can create separate implementations for different use cases while ensuring compatibility with existing protocols.
   - Security audits become easier since standardized interfaces limit unexpected behaviors.

---

## Implementing an Interface

A contract that implements an interface **must** include all the functions defined in the interface. Here’s an example implementation:

```solidity
// Define the interface
interface IExample {
    function getValue() external view returns (uint256);
    function setValue(uint256 _value) external;
}

// Implement the interface in a contract
contract ExampleContract is IExample {
    uint256 private value;

    function getValue() external view override returns (uint256) {
        return value;
    }

    function setValue(uint256 _value) external override {
        value = _value;
    }
}
```

### Key Points:
- The `ExampleContract` explicitly states that it implements `IExample` using the `is` keyword.
- The `override` keyword is used to ensure the function implementations match the interface definitions.
- The contract **must** implement all functions declared in `IExample`; otherwise, it will fail to compile.

---

## Abstract Contracts vs. Interfaces

In Solidity, **abstract contracts** and **interfaces** serve similar purposes but have key differences:

| Feature            | Interface | Abstract Contract |
|-------------------|-----------|------------------|
| Function Implementation | No (only function signatures) | Yes (can have implementations) |
| State Variables | No | Yes |
| Constructor | No | Yes |
| Multiple Inheritance | Yes | No (only single inheritance) |

### When to Use Which?
- **Use an interface** when you only need to define a contract's required structure.
- **Use an abstract contract** when you need some reusable logic while leaving specific implementations for derived contracts.

---

## Conclusion

Interfaces are a foundational concept in Solidity that enable **standardization, interoperability, and security** in smart contract development. By enforcing a predefined structure, interfaces allow different contracts to communicate efficiently, fostering the seamless integration of protocols in Ethereum and beyond.

In the next section, we will explore **abstract contracts** and how they compare to interfaces when designing modular and reusable smart contract architectures.

---

By understanding and utilizing interfaces correctly, developers can ensure their smart contracts remain flexible, compatible, and scalable across the decentralized ecosystem.


# Abstract Contracts (/academy/solidity-foundry/06-contract-standarization/04-abstract)

---
title: Abstract Contracts
description: Understanding Abstract Contracts and Their Role in Smart Contract Inheritance
updated: 2025-01-24
authors: [Andrea Vargas, Ash, martineckardt]
icon: Book
---

# Abstract Contracts in Smart Contracts

## Introduction

When developing smart contracts on the EVM, developers often need to create reusable and modular contract structures. **Abstract contracts** provide a way to define base contract logic that other contracts can inherit while leaving certain details for implementation in derived contracts.

Abstract contracts are particularly useful when building **standardized contract templates**, **frameworks for protocols**, and **secure upgradeable contract architectures**. Unlike interfaces, abstract contracts can contain both **implemented and unimplemented (abstract) functions**, making them more flexible for **inheritance-based development**.

In this lesson, we will explore what abstract contracts are, how they work, and their role in designing scalable and maintainable smart contract architectures.

---

## What Is an Abstract Contract?

An **abstract contract** is a contract that **cannot be deployed on its own** because it contains at least one function without an implementation. Instead, it serves as a **base contract** that other contracts can inherit and extend.

Here's an example of an abstract contract:

```solidity
// Abstract contract defining a base structure
abstract contract BaseContract {
    function getValue() public view virtual returns (uint256);
}
```

Since `getValue()` is not implemented, `BaseContract` cannot be deployed directly. Any contract inheriting `BaseContract` **must provide an implementation** for `getValue()`.

---

## Why Are Abstract Contracts Important?

Abstract contracts offer several benefits for **EVM smart contract development**:

### 1. **Code Reusability**
   - Developers can define **common logic** in an abstract contract and extend it in multiple derived contracts.
   - This reduces code duplication and improves maintainability.

### 2. **Flexibility in Design**
   - Abstract contracts allow developers to create **modular architectures** where child contracts can implement logic differently based on specific needs.

### 3. **Secure Standardization**
   - By enforcing the implementation of required functions in child contracts, abstract contracts help prevent **inconsistent implementations**.
   - This is useful for **token standards, access control mechanisms, and governance contracts**.

---

## Implementing an Abstract Contract

To use an abstract contract, a child contract must **inherit** from it and implement its unimplemented functions. Here’s an example:

```solidity
// Abstract contract defining a required function
abstract contract BaseContract {
    function getValue() public view virtual returns (uint256);
}

// Concrete contract inheriting from BaseContract
contract DerivedContract is BaseContract {
    uint256 private value = 42;

    function getValue() public view override returns (uint256) {
        return value;
    }
}
```

### Key Points:
- `BaseContract` defines `getValue()` as a **virtual** function, meaning it must be overridden in a derived contract.
- `DerivedContract` **inherits** `BaseContract` and provides an implementation for `getValue()`, making it deployable.

---

## Abstract Contracts vs. Interfaces

Both **abstract contracts** and **interfaces** define required function structures, but they have key differences:

| Feature            | Abstract Contract | Interface |
|-------------------|------------------|-----------|
| Function Implementation | Yes (can have implementations) | No (only function signatures) |
| State Variables | Yes | No |
| Constructor | Yes | No |
| Multiple Inheritance | No (only single inheritance) | Yes |

### When to Use Which?
- **Use an abstract contract** when:
  - You need to provide **some** reusable logic alongside function definitions.
  - You want to define **shared state variables** that child contracts can inherit.
  - You are building **modular contract frameworks** with base functionality.

- **Use an interface** when:
  - You only need to **define function signatures** without implementation.
  - You want to ensure compatibility with **multiple unrelated contracts**.

---

## Abstract Contracts in Token Standards

Abstract contracts are frequently used in **EVM token standards** to provide **reusable logic**. For example, OpenZeppelin’s implementation of ERC-20 and ERC-721 uses abstract contracts to define **common functionality**:

```solidity
abstract contract ERC20 {
    function transfer(address recipient, uint256 amount) public virtual returns (bool);
}

contract MyToken is ERC20 {
    function transfer(address recipient, uint256 amount) public override returns (bool) {
        // Token transfer logic
        return true;
    }
}
```

By extending the abstract `ERC20` contract, `MyToken` **inherits** its structure while allowing specific implementations for token transfers.

---

## Using Abstract Contracts for Access Control

Another common use case for abstract contracts is **access control**. Developers can create a base contract that **enforces role-based permissions**, allowing child contracts to inherit this functionality.

Example of an **abstract access control contract**:

```solidity
abstract contract AccessControl {
    address public owner;

    constructor() {
        owner = msg.sender;
    }

    modifier onlyOwner() {
        require(msg.sender == owner, "Not the owner");
        _;
    }

    function restrictedFunction() public view virtual onlyOwner returns (string memory);
}

contract SecureContract is AccessControl {
    function restrictedFunction() public view override onlyOwner returns (string memory) {
        return "Access granted!";
    }
}
```

### Key Takeaways:
- `AccessControl` defines an **owner** variable and an `onlyOwner` modifier to restrict access.
- The function `restrictedFunction()` is declared **virtual**, meaning any child contract **must implement it**.
- `SecureContract` inherits from `AccessControl` and provides an implementation for `restrictedFunction()`.

---

## Conclusion

Abstract contracts are a **powerful tool** for **modular, reusable, and secure** smart contract development on the **EVM**. They allow developers to define **base contract logic** while enforcing **required implementations** in child contracts.

By leveraging **abstract contracts**, developers can:
✅ Reduce code duplication  
✅ Improve security through **standardized implementations**  
✅ Design flexible and scalable smart contract architectures  

In the next section, we will explore one of the most common contract standard used for **Fungible Tokens**, diving deeper into this standard, and how it extends and interact with one another efficiently in **EVM-based smart contract development**.


# Intro ERC-20 Tokens (/academy/solidity-foundry/07-erc20-smart-contracts/01-erc20-intro)

---
title: Intro ERC-20 Tokens
description: Fungible Token Standard
updated: 2025-01-24
authors: [Andrea Vargas, Ash, martineckardt]
icon: Book
---

# Intro ERC-20 Tokens

## Fungible Token Standard

Previously, we explored the concept of smart contracts and how they can be used to execute predefined rules on a blockchain. One of the most impactful use cases of smart contracts is the implementation of token standards. The **ERC-20** standard was introduced to create a universal and interoperable framework for tokens on the EVM.

The ERC-20 standard defines a set of functions and events that a token contract must implement, making it easier for wallets, exchanges, and applications to interact with these tokens. As a result, ERC-20 tokens have become the foundation for countless decentralized finance (DeFi) protocols, governance systems, and utility applications.

To better understand why ERC-20 is such a critical part of EVM’s ecosystem, let's first explore the concept of fungibility.

---

## Fungibility

Fungibility refers to an asset’s ability to be exchanged for another of the same type without any difference in value. Let’s use currency as an example:

- A $10 bill is considered fungible because it holds the same value as another $10 bill. If you exchange one $10 bill for another, their value remains the same.
- Similarly, you can break a $10 bill into smaller denominations like two $5 bills or ten $1 bills, without changing the total value.

ERC-20 tokens are fungible by design. For instance:

- 1 unit of an ERC-20 token (e.g., USDC or USDT) is indistinguishable and interchangeable with any other unit of the same token.
- The fungibility of ERC-20 tokens makes them ideal for use cases such as stablecoins, governance tokens, and liquidity pool assets.

However, fungibility also introduces a limitation: if a use case requires unique attributes for individual tokens, the ERC-20 standard is insufficient. For such scenarios, the ERC-721 standard is used instead, as we will discusse in next chapter.

---

## ERC-20: The Standard

The ERC-20 token standard was designed to simplify the implementation of fungible tokens and ensure compatibility across various EVM-based applications. At its core, an ERC-20 token contract allows the following operations:

- Tracking balances of token holders.
- Transferring tokens between accounts.
- Approving other accounts to spend tokens on behalf of the owner.
- Querying details about the token, such as its name, symbol, and total supply.

Below is the interface for ERC-20 tokens as defined in the original proposal:

```solidity
interface ERC20 {
    function totalSupply() external view returns (uint256);
    function balanceOf(address account) external view returns (uint256);
    function transfer(address recipient, uint256 amount) external returns (bool);
    function allowance(address owner, address spender) external view returns (uint256);
    function approve(address spender, uint256 amount) external returns (bool);
    function transferFrom(
        address sender,
        address recipient,
        uint256 amount
    ) external returns (bool);
    
    event Transfer(address indexed from, address indexed to, uint256 value);
    event Approval(address indexed owner, address indexed spender, uint256 value);
}


# ERC20 Technical Walkthrough (/academy/solidity-foundry/07-erc20-smart-contracts/02-technical-walkthrough)

---
title: ERC20 Technical Walkthrough
description: Fungible Token Standard
updated: 2024-06-28
authors: [Andrea Vargas, Ash, martineckardt]
icon: Book
---
In this section, we will introduce the ERC-20 interface that all token contracts should aim to implement. Furthermore, we will go through each function that the ERC-20 contract mentions and explain what it does in-depth.
## ERC-20 Interface

Below is the ERC-20 interface from EIP-20:

```solidity
interface IERC20 {
​
    function name() external view returns (string memory);
​
    function symbol() external view returns (string memory);
​
    function decimals() external view returns (uint8);
​
    function totalSupply() external view returns (uint256);
​
    function balanceOf(address _owner) external view returns (uint256 balance);
​
    function transfer(address _to, uint256 _value) external returns (bool success);
​
    function transferFrom(address _from, address _to, uint256 _value) external returns (bool success);
​
    function approve(address _spender, uint256 _value) external returns (bool success);
​
    function allowance(address _owner, address _spender) external view returns (uint256 remaining);
​
}
```
The above is derived from eips.ethereum.org/EIPS/eip-20, the official proposal page for the ERC-20 standard. We will now examine each function:

```solidity
name()
```

As the name might suggest, this function returns the name of the token. As an example, for the Wrapped AVAX contract, this would return "Wrapped AVAX".

```solidity
symbol()
```

This function returns the ticker representation of the token. As an example, the United States Dollar usually has the ticker symbol "USD".  For Wrapped Avax, we have "WAVAX".

```solidity
decimals()
```

Perhaps the first unfamiliar topic here, decimals refers to the precision of the token. In Solidity, there is no support for floating point numbers (i.e. decimals) and therefore, any quantity must be represented as a whole number. 

To get around this intricacy, we can represent floating-point numbers by multiplying them with a large number to convert them into a whole number: Consider the following examples:

$$0.05 * 100 = 5$$
$$0.54367 * 100000 = 54367$$
$$0.3 * 10 = 3$$

Multiplying by a power of 10 is equivalent to shifting a number one place to the right. Therefore, for a quantity of token x (which could be a floating point number), we represent this value on-chain as x * 10^n, where n is a number greater than 0. Therefore, n is what decimals() would return.
For the rest of this section, we will refer to the following terms:
Numerical Representation: a quantity of the token that has been converted from a floating-point number to a whole number (via multiplying by 10^n)
User-Representation: a quantity of the token represented in its true form (i.e. floating-point representation)
totalSupply()
This function returns the total number of tokens in circulation. The number returned is in terms of the token numerical representation.
balanceOf(address _owner)
This function returns the balance of the address passed in as the argument. The number returned is in terms of the token numerical representation.
transfer(address _to, uint256 _value)
When called, this function transfer _value amount of tokens (in terms of the token numerical representation) from the function caller to _to. This function is success if the balance of the caller is at least equal to _value. Furthermore, a successful call of this function should emit the following event:
event Transfer(address indexed _from, address indexed _to, uint256 _value)
transferFrom(address _from, address _to, uint256 _value)
Before discussing the functionality of transferFrom(), we will first discuss the concept of allowances.

As we saw with the transfer() function, holders of tokens are able to transfer their tokens to other accounts. While this is function is sufficient for a large amount of use cases, consider protocols such as decentralized exchanges which allow users to swap tokens. Generally, the logic of swaps are as follows:
Take x of token A from the user
Give y of token B to the user
The limitations of the transfer() function is with regards to the first step of the logic above. With our current understanding of ERC-20, the swapper would first need to give the decentralized exchange the tokens it wants to exchange. Therefore, this would result in two transactions in order for the whole swap to be executed, something which is highly undesirable. 

ERC-20, therefore, introduces the concept of allowances. By giving another account permission to take a prespecified amount of your tokens, protocols such as decentralized exchanges are able to conduct behaviors like swaps in an atomic manner. 

Focusing back on transferFrom(), this function transfers _value amount of tokens (in terms of the token numerical representation) from _from to _to. For this function to be successful, _from must have previously allocated the function caller at least _value amount of tokens to spend on their behalf.

This function also emits the Transfer event seen previously. Furthermore, this function updates the amount of tokens that the caller is able to spend on behalf of _from.
approve(address _spender, uint256 _value)
This function gives permission to _spender to spend at most _value tokens (in terms of the token numerical representation) from the balance of the function caller. If successful, this function emits the following event:
event Approval(address indexed _owner, address indexed _spender, uint256 _value)
allowance(address _owner, address _spender)
This function returns the amount of tokens (in terms of the token numerical representation) that _spender is allowed to spend on behalf of _owner.

# Interacting with ERC20 Tokens (/academy/solidity-foundry/07-erc20-smart-contracts/03-interacting-with-erc20-tokens)

---
title: Interacting with ERC20 Tokens
description: Fungible Token Standard
updated: 2024-06-28
authors: [Andrea Vargas, Ash, martineckardt]
icon: Book
---

In this section, we will go through an example of how to interact with an ERC-20 from another contract.

## Read Operations

Before calling any operations of an ERC-20 contract, we will need to have the following available:

- The ERC-20 interface
- The address of the ERC-20 token we want to interact with

Our starting Solidity file, therefore, will the following code:

```solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;
interface IERC20 {
    function name() external view returns (string memory);
    function symbol() external view returns (string memory);
    function decimals() external view returns (uint8);
    function totalSupply() external view returns (uint256);
    function balanceOf(address _owner) external view returns (uint256 balance);
    function transfer(address _to, uint256 _value) external returns (bool success);
    function transferFrom(address _from, address _to, uint256 _value) external returns (bool success);
    function approve(address _spender, uint256 _value) external returns (bool success);
    function allowance(address _owner, address _spender) external view returns (uint256 remaining);
}
```

```solidity
contract Test {
    address tokenAddress;
}
```

As a starter, let's write a function that gets the name of the token:

```solidity
contract Test {
    address tokenAddress;
  
    function getName() public view returns(string memory) {
      return IERC20(tokenAddress).name();
    }
}
```

Perhaps the only unfamiliar piece of syntax is in line 6. In Solidity, note the following:

- Contracts and interfaces are inherently types.
- We can wrap an address type into a contract/interface type. If the contract associated with the address

With the above in mind, the logic of getName is as follows:

- We call the function name at address token by wrapping the address type with the IERC20 interface
- name returns us the name of the token contract
- getName returns the name of the token contract

Just like that, we were able to call a read function of an ERC-20 contract. But what if we wanted to modify the state of an ERC-20 contract?

## Write Operations

In this example, we will look at calling the transferFrom function of an ERC-20 token contract. Recall that, if authorized, transferFrom allows us to transfer tokens from one account to another. As a starter, we have the following code:

```solidity
contract Test {
    address tokenAddress;
    address from;
    address to;
    uint amt;
  
    function getName() public view returns(string memory) {
      return IERC20(tokenAddress).name();
    }
  
    function doTransferFrom() public returns(bool) {
        return IERC20(tokenAddress).transferFrom(from, to, amt);
    }
}
```

In addition to adding additional state variables for context, we have also added the function doTransferFrom which calls the transferFrom function of the ERC-20 token contract. In particular, doTransferFrom returns the boolean returned by transferFrom, which represents whether if the function was successful or not. While the code above works, we can make it better by first checking if we are have been allocated enough tokens such that transferFrom(from, to, amt) will return true. To do this, we can make a call to the allowance function of the ERC-20 token contract. Our updated code is as follows:

```solidity
contract Test {
    address token;
    address from;
    address to;
    uint amt;
  
    function getName() public view returns(string memory) {
      return IERC20(token).name();
    }
  
    function doTransferFrom() public returns(bool) {
        if (IERC20(token).allowance(from, address(this) < amt) {
            return false;
        }
        return IERC20(token).transferFrom(from, to, amt);
    }
}
```

In line 13, we are passing in both the address of the spender and the address of our own smart contract to the allowance function, which returns the amount of allocated tokens which we compare to our amt variable. If we are have not been allocated enough tokens, we return false and therefore, we do not spend any additional computation resources calling transferFrom, which we know would have been unsuccessful.

# Deploying your own ERC20 Token (/academy/solidity-foundry/07-erc20-smart-contracts/04-deploying-your-erc20-token)

---
title: Deploying your own ERC20 Token
description: Fungible Token Standard
updated: 2024-06-28
authors: [Andrea Vargas, Ash, martineckardt]
icon: BookOpen
---

At this point of this chapter, you have become familiar with the design and implementation of the ERC-20 token standard. Still, you might have the following question: how does one actually go about deploying ERC-20 tokens? In this section, we will cover the following deployment methods:

- Custom Deployment
- OpenZeppelin Wizard Contract Deployer

## Custom Deployment

By custom deployment, we mean writing your own ERC-20 contract by hand. Right off the bat, this option offers the most customization as you are fully in control over the implementation details of your ERC-20 token. As long as you adhere to the ERC-20 token interface, your token is able to be used by any ERC-20 compatible protocol. However, consider the following downsides of writing your own ERC-20 token by-hand:

- Security: by writing your own custom code, you are putting your ERC-20 token at risk of being hacked by malicious actors. Even the best of programmers can fall victim to security vulnerabilities related to ERC-20 contracts!
- Gas Inefficiencies: it could be that while your contract is "correct," it may be expensive for users to interact with your ERC-20 contract.

The two reasons above, in additions to other small nuances, make it evident that writing your own ERC-20 token from scratch is not the best idea. This leads us to the other option:

## OpenZeppelin Wizard

OpenZeppelin's Wizard Contract Creator is a useful tool which allows for developers to deploy contracts on the fly. By this, we mean that by just filling a couple of fields and selecting a few options, we can autogenerate the code necessary to deploy a ERC-20 token to our liking! To get started, head over to [wizard.openzeppelin.com/#erc20](wizard.openzeppelin.com/#erc20) where you will see the following:

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/smartcontract-foundry/erc20-OpenZeppelin-gz9mc7CErNPx0PLFLwGMq2XBKlKOdE.png)


Front and center, you will see some Solidity code. At first, it seem as if this ERC20 contract OpenZeppelin has generated for us contains basically nothing. However, if you look closely, you will see that the MyToken contract that OpenZeppelin has generated for us inherits the ERC20, ERC20Permit contracts, which are defined and contain all the logic for our ERC-20 contract. This is the great part about the OpenZeppelin Wizard Contract Creator - we can easily modify our ERC-20 contract by inheriting the contracts whose functionalities we want. Therefore, as an example, let's create the following contract:

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/smartcontract-foundry/erc20-OpenZeppelin2-14GEmGL7MxlXGny0bUtZa3gjenHURz.png)
 
In the above, we've created a new ERC-20 contract named BigRedCoin. Furthermore, this ERC-20 token allocates to the deployer 20000 tokens on initialization and gives the owner full rights over the behavior of the token. Now that we have our ERC-20 token contract customized, how do we actually deploy it?

If you look at the righthand side of the Wizard page, you will see the button Copy to Clipboard. As the name might suggest, this allows us to copy our contract and paste it to a file in our Avalanche Starter Kit, which we can then compile and deploy onto the blockchain!

# Intro ERC-721 Tokens (/academy/solidity-foundry/08-erc721-smart-contracts/01-erc721-intro)

---
title: Intro ERC-721 Tokens
description: Non-Fungible Token Standard
updated: 2024-06-28
authors: [Andrea Vargas, Ash, martineckardt]
icon: Book
---
Previously, we explored the ERC-20 interface, a contract standard which allowed for the implementation of a token contract which the majority of smart contract users are able to easily call. As a result of the ERC-20 standard, many protocols were able flourish without having to worry about incompatible token interfaces. However, there is one thing that the ERC-20 standard did not fix...
To understand the biggest shortcoming of the ERC-20 standard, we have discussed the concept of fungibility. Its design enables crucial functionality. However, this also implies that for a use case that requires for 1 unit of some ERC-20 A to be different in value than 1 unit of the same ERC-20 token A, the ERC-20 token standard is not sufficient for such a use case.

## ERC-721

To make clear a particular that ERC-20 cannot support, imagine we wanted to represent an art collection within a smart contract. The smart contract would contain the following functionality in a similar fashion to an ERC-20 token:
- The ability to query the "balance" (i.e. the art holdings) of a particular user
- The ability to transfer art pieces from one account to another
- The ability to get information about the art collection
- The biggest different between an arbitrary ERC-20 token contract and an art collection is the fungibility of individual items - ERC-20 tokens are inherently fungible with items in the art collections are not (since the items each vary in value).

To account for uses cases like an art collection, the ERC-721 standard was introduced. Formally, ERC-721 is a standard for non-fungible tokens. Below is the interface of the ERC-721 token from its original proposal :

```solidity
interface ERC721 {
    /// @dev This emits when ownership of any NFT changes by any mechanism.
    ///  This event emits when NFTs are created (`from` == 0) and destroyed
    ///  (`to` == 0). Exception: during contract creation, any number of NFTs
    ///  may be created and assigned without emitting Transfer. At the time of
    ///  any transfer, the approved address for that NFT (if any) is reset to none.
    event Transfer(address indexed _from, address indexed _to, uint256 indexed _tokenId);
​
    /// @dev This emits when the approved address for an NFT is changed or
    ///  reaffirmed. The zero address indicates there is no approved address.
    ///  When a Transfer event emits, this also indicates that the approved
    ///  address for that NFT (if any) is reset to none.
    event Approval(address indexed _owner, address indexed _approved, uint256 indexed _tokenId);
​
    /// @dev This emits when an operator is enabled or disabled for an owner.
    ///  The operator can manage all NFTs of the owner.
    event ApprovalForAll(address indexed _owner, address indexed _operator, bool _approved);
​
    /// @notice Count all NFTs assigned to an owner
    /// @dev NFTs assigned to the zero address are considered invalid, and this
    ///  function throws for queries about the zero address.
    /// @param _owner An address for whom to query the balance
    /// @return The number of NFTs owned by `_owner`, possibly zero
    function balanceOf(address _owner) external view returns (uint256);
​
    /// @notice Find the owner of an NFT
    /// @dev NFTs assigned to zero address are considered invalid, and queries
    ///  about them do throw.
    /// @param _tokenId The identifier for an NFT
    /// @return The address of the owner of the NFT
    function ownerOf(uint256 _tokenId) external view returns (address);
​
    /// @notice Transfers the ownership of an NFT from one address to another address
    /// @dev Throws unless `msg.sender` is the current owner, an authorized
    ///  operator, or the approved address for this NFT. Throws if `_from` is
    ///  not the current owner. Throws if `_to` is the zero address. Throws if
    ///  `_tokenId` is not a valid NFT. When transfer is complete, this function
    ///  checks if `_to` is a smart contract (code size > 0). If so, it calls
    ///  `onERC721Received` on `_to` and throws if the return value is not
    ///  `bytes4(keccak256("onERC721Received(address,address,uint256,bytes)"))`.
    /// @param _from The current owner of the NFT
    /// @param _to The new owner
    /// @param _tokenId The NFT to transfer
    /// @param data Additional data with no specified format, sent in call to `_to`
    function safeTransferFrom(address _from, address _to, uint256 _tokenId, bytes data) external payable;
​
    /// @notice Transfers the ownership of an NFT from one address to another address
    /// @dev This works identically to the other function with an extra data parameter,
    ///  except this function just sets data to "".
    /// @param _from The current owner of the NFT
    /// @param _to The new owner
    /// @param _tokenId The NFT to transfer
    function safeTransferFrom(address _from, address _to, uint256 _tokenId) external payable;
​
    /// @notice Transfer ownership of an NFT -- THE CALLER IS RESPONSIBLE
    ///  TO CONFIRM THAT `_to` IS CAPABLE OF RECEIVING NFTS OR ELSE
    ///  THEY MAY BE PERMANENTLY LOST
    /// @dev Throws unless `msg.sender` is the current owner, an authorized
    ///  operator, or the approved address for this NFT. Throws if `_from` is
    ///  not the current owner. Throws if `_to` is the zero address. Throws if
    ///  `_tokenId` is not a valid NFT.
    /// @param _from The current owner of the NFT
    /// @param _to The new owner
    /// @param _tokenId The NFT to transfer
    function transferFrom(address _from, address _to, uint256 _tokenId) external payable;
​
    /// @notice Change or reaffirm the approved address for an NFT
    /// @dev The zero address indicates there is no approved address.
    ///  Throws unless `msg.sender` is the current NFT owner, or an authorized
    ///  operator of the current owner.
    /// @param _approved The new approved NFT controller
    /// @param _tokenId The NFT to approve
    function approve(address _approved, uint256 _tokenId) external payable;
​
    /// @notice Enable or disable approval for a third party ("operator") to manage
    ///  all of `msg.sender`'s assets
    /// @dev Emits the ApprovalForAll event. The contract MUST allow
    ///  multiple operators per owner.
    /// @param _operator Address to add to the set of authorized operators
    /// @param _approved True if the operator is approved, false to revoke approval
    function setApprovalForAll(address _operator, bool _approved) external;
​
    /// @notice Get the approved address for a single NFT
    /// @dev Throws if `_tokenId` is not a valid NFT.
    /// @param _tokenId The NFT to find the approved address for
    /// @return The approved address for this NFT, or the zero address if there is none
    function getApproved(uint256 _tokenId) external view returns (address);
​
    /// @notice Query if an address is an authorized operator for another address
    /// @param _owner The address that owns the NFTs
    /// @param _operator The address that acts on behalf of the owner
    /// @return True if `_operator` is an approved operator for `_owner`, false otherwise
    function isApprovedForAll(address _owner, address _operator) external view returns (bool);
}
```

## Implementation Design

Notice that for an ERC-20 token, we can store the balance of all token holders with the following data structure:

```solidity
mapping(address => uint) balances;
```

In the case of the ERC-721 token standard, this is not enough, since using just this data structure would imply that all tokens of an ERC-721 contract are fungible. Therefore, we want to use the following data structures:

```solidity
mapping(address => uint) balances;
mapping(uint => address) holders;
```

The balances data structure will map accounts to the number of non-fungible tokens they hold. The data structure holders, meanwhile, will map the ID of each non-fungible token to the address which holds the token. Therefore, by adding just another mapping, we've just allowed our token contract to incorporate non-fungible tokens!

# ERC721 Technical Walkthrough (/academy/solidity-foundry/08-erc721-smart-contracts/02-technical-walkthrough)

---
title: ERC721 Technical Walkthrough
description:  Non-Fungible Token Standard
updated: 2024-06-28
authors: [Andrea Vargas, Ash, martineckardt]
icon: Book
---
Just like with the ERC-20 chapter, in this section we will examine each of the functions that make up the ERC-721 interface. Below is the ERC-721 interface seen from the last section:

```solidity
pragma solidity ^0.4.20;
​
/// @title ERC-721 Non-Fungible Token Standard
/// @dev See https://eips.ethereum.org/EIPS/eip-721
///  Note: the ERC-165 identifier for this interface is 0x80ac58cd.
interface ERC721 {
    /// @dev This emits when ownership of any NFT changes by any mechanism.
    ///  This event emits when NFTs are created (`from` == 0) and destroyed
    ///  (`to` == 0). Exception: during contract creation, any number of NFTs
    ///  may be created and assigned without emitting Transfer. At the time of
    ///  any transfer, the approved address for that NFT (if any) is reset to none.
    event Transfer(address indexed _from, address indexed _to, uint256 indexed _tokenId);
​
    /// @dev This emits when the approved address for an NFT is changed or
    ///  reaffirmed. The zero address indicates there is no approved address.
    ///  When a Transfer event emits, this also indicates that the approved
    ///  address for that NFT (if any) is reset to none.
    event Approval(address indexed _owner, address indexed _approved, uint256 indexed _tokenId);
​
    /// @dev This emits when an operator is enabled or disabled for an owner.
    ///  The operator can manage all NFTs of the owner.
    event ApprovalForAll(address indexed _owner, address indexed _operator, bool _approved);
​
    /// @notice Count all NFTs assigned to an owner
    /// @dev NFTs assigned to the zero address are considered invalid, and this
    ///  function throws for queries about the zero address.
    /// @param _owner An address for whom to query the balance
    /// @return The number of NFTs owned by `_owner`, possibly zero
    function balanceOf(address _owner) external view returns (uint256);
​
    /// @notice Find the owner of an NFT
    /// @dev NFTs assigned to zero address are considered invalid, and queries
    ///  about them do throw.
    /// @param _tokenId The identifier for an NFT
    /// @return The address of the owner of the NFT
    function ownerOf(uint256 _tokenId) external view returns (address);
​
    /// @notice Transfers the ownership of an NFT from one address to another address
    /// @dev Throws unless `msg.sender` is the current owner, an authorized
    ///  operator, or the approved address for this NFT. Throws if `_from` is
    ///  not the current owner. Throws if `_to` is the zero address. Throws if
    ///  `_tokenId` is not a valid NFT. When transfer is complete, this function
    ///  checks if `_to` is a smart contract (code size > 0). If so, it calls
    ///  `onERC721Received` on `_to` and throws if the return value is not
    ///  `bytes4(keccak256("onERC721Received(address,address,uint256,bytes)"))`.
    /// @param _from The current owner of the NFT
    /// @param _to The new owner
    /// @param _tokenId The NFT to transfer
    /// @param data Additional data with no specified format, sent in call to `_to`
    function safeTransferFrom(address _from, address _to, uint256 _tokenId, bytes data) external payable;
​
    /// @notice Transfers the ownership of an NFT from one address to another address
    /// @dev This works identically to the other function with an extra data parameter,
    ///  except this function just sets data to "".
    /// @param _from The current owner of the NFT
    /// @param _to The new owner
    /// @param _tokenId The NFT to transfer
    function safeTransferFrom(address _from, address _to, uint256 _tokenId) external payable;
​
    /// @notice Transfer ownership of an NFT -- THE CALLER IS RESPONSIBLE
    ///  TO CONFIRM THAT `_to` IS CAPABLE OF RECEIVING NFTS OR ELSE
    ///  THEY MAY BE PERMANENTLY LOST
    /// @dev Throws unless `msg.sender` is the current owner, an authorized
    ///  operator, or the approved address for this NFT. Throws if `_from` is
    ///  not the current owner. Throws if `_to` is the zero address. Throws if
    ///  `_tokenId` is not a valid NFT.
    /// @param _from The current owner of the NFT
    /// @param _to The new owner
    /// @param _tokenId The NFT to transfer
    function transferFrom(address _from, address _to, uint256 _tokenId) external payable;
​
    /// @notice Change or reaffirm the approved address for an NFT
    /// @dev The zero address indicates there is no approved address.
    ///  Throws unless `msg.sender` is the current NFT owner, or an authorized
    ///  operator of the current owner.
    /// @param _approved The new approved NFT controller
    /// @param _tokenId The NFT to approve
    function approve(address _approved, uint256 _tokenId) external payable;
​
    /// @notice Enable or disable approval for a third party ("operator") to manage
    ///  all of `msg.sender`'s assets
    /// @dev Emits the ApprovalForAll event. The contract MUST allow
    ///  multiple operators per owner.
    /// @param _operator Address to add to the set of authorized operators
    /// @param _approved True if the operator is approved, false to revoke approval
    function setApprovalForAll(address _operator, bool _approved) external;
​
    /// @notice Get the approved address for a single NFT
    /// @dev Throws if `_tokenId` is not a valid NFT.
    /// @param _tokenId The NFT to find the approved address for
    /// @return The approved address for this NFT, or the zero address if there is none
    function getApproved(uint256 _tokenId) external view returns (address);
​
    /// @notice Query if an address is an authorized operator for another address
    /// @param _owner The address that owns the NFTs
    /// @param _operator The address that acts on behalf of the owner
    /// @return True if `_operator` is an approved operator for `_owner`, false otherwise
    function isApprovedForAll(address _owner, address _operator) external view returns (bool);
}
```

__balanceOf(address _owner)__
Similar to the function of the same name in the ERC20 interface, balanceOf returns the number of non-fungible tokens that _owner has.

__ownerOf(uint256 _tokenId)__
This function returns the address that owns the non-fungible token with id _tokenId
__safeTransferFrom(address _from, address _to, uint256 _tokenId, bytes data)__
This function is very similar to the transferFrom function in the ERC-20 specification. safeTransferFrom transfer a NFT of id _tokenId from _from to _to . However, after transferring the token, safeTransferFrom checks if the account is capable of handling the NFT (via passing in the arguments _from, _to, _tokenId, and data. If _to is not capable of handling the NFT, safeTransferFrom reverts.
__safeTransferFrom(address _from, address _to, uint256 _tokenId)__
This function behaves exactly like the function above, except that the argument data is set to the empty string.
__transferFrom(address _from, address _to, uint256 _tokenId)__
This function behaves exactly like safeTransferFrom, except that we do not check if _to is capable of receiving the NFT with id _tokenId.
__approve(address _approved, uint256 _tokenId)__
When called, this function gives _approved transfer rights to the NFT with id _tokenId. This function fails if an account without transfer rights to the NFT is the caller.
__setApprovalForAll(address _operator, bool _approved)__
When called, this function gives _operator either transfer rights to all NFTs of the function caller (if _approved is true) or revokes transfer rights to all NFTs of the function caller (if _approved is false).
__getApproved(uint256 _tokenId)__
This function returns the address of the account with transfer rights to the NFT with id _tokenId.
__isApprovedForAll(address _owner, address _operator)__
This function returns true if _operator has transfer rights to all of the NFTs that _owner holds, and false otherwise.

# Interacting with ERC721 Tokens (/academy/solidity-foundry/08-erc721-smart-contracts/03-interacting-with-erc721-tokens)

---
title: Interacting with ERC721 Tokens
description:  Non-Fungible Token Standard
updated: 2024-06-28
authors: [Andrea Vargas, Ash, martineckardt]
icon: Book
---
Just like with the ERC-20 chapter, in this section, we will take a look at interacting with the functions that make up a ERC-721 token contract:

```solidity
/// @title ERC-721 Non-Fungible Token Standard
/// @dev See https://eips.ethereum.org/EIPS/eip-721
///  Note: the ERC-165 identifier for this interface is 0x80ac58cd.
interface ERC721 {
    /// @dev This emits when ownership of any NFT changes by any mechanism.
    ///  This event emits when NFTs are created (`from` == 0) and destroyed
    ///  (`to` == 0). Exception: during contract creation, any number of NFTs
    ///  may be created and assigned without emitting Transfer. At the time of
    ///  any transfer, the approved address for that NFT (if any) is reset to none.
    event Transfer(address indexed _from, address indexed _to, uint256 indexed _tokenId);
​
    /// @dev This emits when the approved address for an NFT is changed or
    ///  reaffirmed. The zero address indicates there is no approved address.
    ///  When a Transfer event emits, this also indicates that the approved
    ///  address for that NFT (if any) is reset to none.
    event Approval(address indexed _owner, address indexed _approved, uint256 indexed _tokenId);
​
    /// @dev This emits when an operator is enabled or disabled for an owner.
    ///  The operator can manage all NFTs of the owner.
    event ApprovalForAll(address indexed _owner, address indexed _operator, bool _approved);
​
    /// @notice Count all NFTs assigned to an owner
    /// @dev NFTs assigned to the zero address are considered invalid, and this
    ///  function throws for queries about the zero address.
    /// @param _owner An address for whom to query the balance
    /// @return The number of NFTs owned by `_owner`, possibly zero
    function balanceOf(address _owner) external view returns (uint256);
​
    /// @notice Find the owner of an NFT
    /// @dev NFTs assigned to zero address are considered invalid, and queries
    ///  about them do throw.
    /// @param _tokenId The identifier for an NFT
    /// @return The address of the owner of the NFT
    function ownerOf(uint256 _tokenId) external view returns (address);
​
    /// @notice Transfers the ownership of an NFT from one address to another address
    /// @dev Throws unless `msg.sender` is the current owner, an authorized
    ///  operator, or the approved address for this NFT. Throws if `_from` is
    ///  not the current owner. Throws if `_to` is the zero address. Throws if
    ///  `_tokenId` is not a valid NFT. When transfer is complete, this function
    ///  checks if `_to` is a smart contract (code size > 0). If so, it calls
    ///  `onERC721Received` on `_to` and throws if the return value is not
    ///  `bytes4(keccak256("onERC721Received(address,address,uint256,bytes)"))`.
    /// @param _from The current owner of the NFT
    /// @param _to The new owner
    /// @param _tokenId The NFT to transfer
    /// @param data Additional data with no specified format, sent in call to `_to`
    function safeTransferFrom(address _from, address _to, uint256 _tokenId, bytes memory data) external payable;
​
    /// @notice Transfers the ownership of an NFT from one address to another address
    /// @dev This works identically to the other function with an extra data parameter,
    ///  except this function just sets data to "".
    /// @param _from The current owner of the NFT
    /// @param _to The new owner
    /// @param _tokenId The NFT to transfer
    function safeTransferFrom(address _from, address _to, uint256 _tokenId) external payable;
​
    /// @notice Transfer ownership of an NFT -- THE CALLER IS RESPONSIBLE
    ///  TO CONFIRM THAT `_to` IS CAPABLE OF RECEIVING NFTS OR ELSE
    ///  THEY MAY BE PERMANENTLY LOST
    /// @dev Throws unless `msg.sender` is the current owner, an authorized
    ///  operator, or the approved address for this NFT. Throws if `_from` is
    ///  not the current owner. Throws if `_to` is the zero address. Throws if
    ///  `_tokenId` is not a valid NFT.
    /// @param _from The current owner of the NFT
    /// @param _to The new owner
    /// @param _tokenId The NFT to transfer
    function transferFrom(address _from, address _to, uint256 _tokenId) external payable;
​
    /// @notice Change or reaffirm the approved address for an NFT
    /// @dev The zero address indicates there is no approved address.
    ///  Throws unless `msg.sender` is the current NFT owner, or an authorized
    ///  operator of the current owner.
    /// @param _approved The new approved NFT controller
    /// @param _tokenId The NFT to approve
    function approve(address _approved, uint256 _tokenId) external payable;
​
    /// @notice Enable or disable approval for a third party ("operator") to manage
    ///  all of `msg.sender`'s assets
    /// @dev Emits the ApprovalForAll event. The contract MUST allow
    ///  multiple operators per owner.
    /// @param _operator Address to add to the set of authorized operators
    /// @param _approved True if the operator is approved, false to revoke approval
    function setApprovalForAll(address _operator, bool _approved) external;
​
    /// @notice Get the approved address for a single NFT
    /// @dev Throws if `_tokenId` is not a valid NFT.
    /// @param _tokenId The NFT to find the approved address for
    /// @return The approved address for this NFT, or the zero address if there is none
    function getApproved(uint256 _tokenId) external view returns (address);
​
    /// @notice Query if an address is an authorized operator for another address
    /// @param _owner The address that owns the NFTs
    /// @param _operator The address that acts on behalf of the owner
    /// @return True if `_operator` is an approved operator for `_owner`, false otherwise
    function isApprovedForAll(address _owner, address _operator) external view returns (bool);
}
```

## Example
To start, let's define a Solidity file with the following:

- The ERC721 token standard interface
- A caller contract which stores the address of the ERC-721 contract we want to interact with and an arbitrary NFT id

```solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;
​
/// @title ERC-721 Non-Fungible Token Standard
/// @dev See https://eips.ethereum.org/EIPS/eip-721
///  Note: the ERC-165 identifier for this interface is 0x80ac58cd.
interface ERC721 {
    /// @dev This emits when ownership of any NFT changes by any mechanism.
    ///  This event emits when NFTs are created (`from` == 0) and destroyed
    ///  (`to` == 0). Exception: during contract creation, any number of NFTs
    ///  may be created and assigned without emitting Transfer. At the time of
    ///  any transfer, the approved address for that NFT (if any) is reset to none.
    event Transfer(address indexed _from, address indexed _to, uint256 indexed _tokenId);
​
    /// @dev This emits when the approved address for an NFT is changed or
    ///  reaffirmed. The zero address indicates there is no approved address.
    ///  When a Transfer event emits, this also indicates that the approved
    ///  address for that NFT (if any) is reset to none.
    event Approval(address indexed _owner, address indexed _approved, uint256 indexed _tokenId);
​
    /// @dev This emits when an operator is enabled or disabled for an owner.
    ///  The operator can manage all NFTs of the owner.
    event ApprovalForAll(address indexed _owner, address indexed _operator, bool _approved);
​
    /// @notice Count all NFTs assigned to an owner
    /// @dev NFTs assigned to the zero address are considered invalid, and this
    ///  function throws for queries about the zero address.
    /// @param _owner An address for whom to query the balance
    /// @return The number of NFTs owned by `_owner`, possibly zero
    function balanceOf(address _owner) external view returns (uint256);
​
    /// @notice Find the owner of an NFT
    /// @dev NFTs assigned to zero address are considered invalid, and queries
    ///  about them do throw.
    /// @param _tokenId The identifier for an NFT
    /// @return The address of the owner of the NFT
    function ownerOf(uint256 _tokenId) external view returns (address);
​
    /// @notice Transfers the ownership of an NFT from one address to another address
    /// @dev Throws unless `msg.sender` is the current owner, an authorized
    ///  operator, or the approved address for this NFT. Throws if `_from` is
    ///  not the current owner. Throws if `_to` is the zero address. Throws if
    ///  `_tokenId` is not a valid NFT. When transfer is complete, this function
    ///  checks if `_to` is a smart contract (code size > 0). If so, it calls
    ///  `onERC721Received` on `_to` and throws if the return value is not
    ///  `bytes4(keccak256("onERC721Received(address,address,uint256,bytes)"))`.
    /// @param _from The current owner of the NFT
    /// @param _to The new owner
    /// @param _tokenId The NFT to transfer
    /// @param data Additional data with no specified format, sent in call to `_to`
    function safeTransferFrom(address _from, address _to, uint256 _tokenId, bytes memory data) external payable;
​
    /// @notice Transfers the ownership of an NFT from one address to another address
    /// @dev This works identically to the other function with an extra data parameter,
    ///  except this function just sets data to "".
    /// @param _from The current owner of the NFT
    /// @param _to The new owner
    /// @param _tokenId The NFT to transfer
    function safeTransferFrom(address _from, address _to, uint256 _tokenId) external payable;
​
    /// @notice Transfer ownership of an NFT -- THE CALLER IS RESPONSIBLE
    ///  TO CONFIRM THAT `_to` IS CAPABLE OF RECEIVING NFTS OR ELSE
    ///  THEY MAY BE PERMANENTLY LOST
    /// @dev Throws unless `msg.sender` is the current owner, an authorized
    ///  operator, or the approved address for this NFT. Throws if `_from` is
    ///  not the current owner. Throws if `_to` is the zero address. Throws if
    ///  `_tokenId` is not a valid NFT.
    /// @param _from The current owner of the NFT
    /// @param _to The new owner
    /// @param _tokenId The NFT to transfer
    function transferFrom(address _from, address _to, uint256 _tokenId) external payable;
​
    /// @notice Change or reaffirm the approved address for an NFT
    /// @dev The zero address indicates there is no approved address.
    ///  Throws unless `msg.sender` is the current NFT owner, or an authorized
    ///  operator of the current owner.
    /// @param _approved The new approved NFT controller
    /// @param _tokenId The NFT to approve
    function approve(address _approved, uint256 _tokenId) external payable;
​
    /// @notice Enable or disable approval for a third party ("operator") to manage
    ///  all of `msg.sender`'s assets
    /// @dev Emits the ApprovalForAll event. The contract MUST allow
    ///  multiple operators per owner.
    /// @param _operator Address to add to the set of authorized operators
    /// @param _approved True if the operator is approved, false to revoke approval
    function setApprovalForAll(address _operator, bool _approved) external;
​
    /// @notice Get the approved address for a single NFT
    /// @dev Throws if `_tokenId` is not a valid NFT.
    /// @param _tokenId The NFT to find the approved address for
    /// @return The approved address for this NFT, or the zero address if there is none
    function getApproved(uint256 _tokenId) external view returns (address);
​
    /// @notice Query if an address is an authorized operator for another address
    /// @param _owner The address that owns the NFTs
    /// @param _operator The address that acts on behalf of the owner
    /// @return True if `_operator` is an approved operator for `_owner`, false otherwise
    function isApprovedForAll(address _owner, address _operator) external view returns (bool);
}
​
contract Caller {
​
    address tokenAddress;
  
    uint tokenId;
​
}
```

As a starter, let's write a function that will query the owner of a NFT with id tokenId:

```solidity
contract Caller {
​
    address tokenAddress;
  
    uint tokenId;
​
    function getNFTOwner() public view returns(address) {
        return ERC721(tokenAddress).ownerOf(tokenId);
    }
​
}
```

Next, let's write a function that, when called by some account A, transfers the NFT with id tokenId to the caller (i.e. we give up our own NFT; you definitely do not want to do this in the real world!):

```solidity
contract Caller {
​
    address tokenAddress;
    uint tokenId;
​
    function getNFTOwner() public view returns(address) {
        return ERC721(token).ownerOf(tokenId);
    }
​
    function transferNFT() public {
        ERC721(tokenAddress).safeTransferFrom(address(this), msg.sender, tokenId);
    }
​
}
```

Finally, let's write a function that, when called, gives the caller transfer rights to all of our NFTs (again, don't do this in the real world!):

```solidity
contract Caller {
​
    address tokenAddress;
    uint tokenId;
​
    function getNFTOwner() public view returns(address) {
        return ERC721(tokenAddress).ownerOf(tokenId);
    }
​
    function transferNFT() public {
        ERC721(tokenAddress).safeTransferFrom(address(this), msg.sender, tokenId);
    }
​
    function giveAllTransferRights() public {
        ERC721(tokenAddress).setApprovalForAll(msg.sender, true);
    }
​
}
```

# Deploying your own ERC20 Token (/academy/solidity-foundry/08-erc721-smart-contracts/04-deploying-your-erc721-token)

---
title: Deploying your own ERC20 Token
description:  Non-Fungible Token Standard
updated: 2024-06-28
authors: [Andrea Vargas, Ash, martineckardt]
icon: BookOpen
---

We again come across the question of how to deploy a ERC-721 token on the blockchain. Since we have access to the ERC-721 contract interface, there is nothing stopping us from writing our own implementation of an ERC-721 token. However, if you recall the deployment section of the ERC-20 chapter, then you know that we were able to use OpenZeppelin's Contract Wizard to autogenerate our own ERC-20 contract. Likewise, OpenZeppelin's Contract Wizard also allows to create ERC-721 tokens on the fly. For the rest of this section, we will look at just that!

## Autogenerating a ERC-721 Token
To start, head over to [wizard.openzeppelin.com/#erc721](wizard.openzeppelin.com/#erc721) where you should see the following:

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/smartcontract-foundry/erc721-OpenZeppelin-LCWPrQq2noPL22l0mSuIqvd2ZOeqi2.png)

As with the ERC-20 section, the base contract MyToken is deriving the ERC721 contract, which contains the logic necessary for a functional ERC-721 token contract. MyToken, in essence, allows us to define the initial values of our ERC-721 token. Just like the ERC-20 contract, we can also inherit optional features for our ERC-721 token as well. Below is an example of us customizing our ERC-721 token:

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builders-hub/course-images/smartcontract-foundry/erc721-OpenZeppelin2-mlDRnpBpXmO0SlBZzsMEeBAzeZNrz6.png)

To end off the ERC-721 chapter, we will look at one particular feature that makes ERC-721 token special: the URI Storage feature.

# URIs (/academy/solidity-foundry/08-erc721-smart-contracts/05-uris)

---
title: URIs
description:  Non-Fungible Token Standard
updated: 2024-06-28
authors: [Andrea Vargas, Ash, martineckardt]
icon: BookOpen
---
Ignoring the technical side of ERC-721 tokens, perhaps the most famous use case of such tokens is to track digital images. Whenever most people hear the term NFT, they mostly think of JPEGs that can be tracked on the blockchain. 

With our current understanding of ERC-721 tokens, it does not really make sense how we can use such a token standard to track pictures, considering NFTs are just mappings from numbers to addresses. In this section, we will look at how we can extend the functionality of ERC-721 tokens to be able to track digital assets such as JPEGs.

## URIs

URIs, or uniform resource indicators, can be thought of as a particular format of URLs which allow us to easily build a particular URL using just a base URL and a specific URL. As an example, consider the following base URL: rodrigo.xyz/images . As the URL might suggest, this URL is the base string for all webpages which store images. Some sample specific URLs would be /dog.jpeg, /cat.jpeg, ..., etc. By organizing our URLs in this manner, it makes it easy to organize our collection of images. 

NFTs, likewise, use the same principle. In the case of JPEGs, NFTs simply keep track of the URL of the jpeg via the URI format.

## Another Mapping

Tying everything together, to track digital assets such as JPEGs which use URIs, we can add the following mapping to our ERC-721 function:

```solidity
mapping(uint256 tokenId => string) private _tokenURIs;
```

The mapping above stores the specific token URIs, while the base URI is stored as a separate state variable. To be able to query the full URI of a particular token, we can use the following function (from OpenZeppelin's ERC721URIStorage contract):

```solidity
function tokenURI(uint256 tokenId) public view virtual override returns (string memory) {
        _requireOwned(tokenId);
​
        string memory _tokenURI = _tokenURIs[tokenId];
        string memory base = _baseURI();
​
        // If there is no base URI, return the token URI.
        if (bytes(base).length == 0) {
            return _tokenURI;
        }
        // If both are set, concatenate the baseURI and tokenURI (via string.concat).
        if (bytes(_tokenURI).length > 0) {
            return string.concat(base, _tokenURI);
        }
​
        return super.tokenURI(tokenId);
}
```

Just like that, our NFTs are now able to track digital assets like JPEGs!

# 0xGasless (/integrations/0xgasless)

---
title: 0xGasless
category: Account Abstraction
available: ["C-Chain"]
description: 0xGasless offers AgentKit for on-chain agent execution and an Account Abstraction SDK for developers to build user friendly blockchain applications..
logo: /images/0xGasless.png
developer: 0xGasless
website: https://0xgasless.com/
documentation: https://docs.0xgasless.com/
---

## Overview

0xGasless AgentKit is an SDK that provides on‑chain execution for AI agents, enabling them to sign transactions, interact with smart contracts, swap tokens, deploy contracts, and manage wallets without gas.

It also includes a complete account abstraction stack on ERC-4337 and ERC-7702, allowing developers to build seamless, user-friendly dApps with features like gasless transactions, batching, and session keys.

## What we are offering

0xGasless is an Account Abstraction platform and AI AgentKit enabling gasless smart accounts and autonomous on‑chain AI agents via ERC‑4337, with paymasters, bundlers, and LLM‑ready tools across EVM chains.

### AA SDK

- Bundler-as-a-Service
- Paymaster-as-a-Service
- ERC-4337 Smart Wallets
- ERC-7702

### AgentKit

- Open-source [GitHub repo](https://github.com/0xgasless/agentkit) 
- [NPM package](https://www.npmjs.com/package/@0xgasless/agentkit) 
- 0xGasless Claude MCP: [NPM Package](https://www.npmjs.com/package/@0xgasless/mcp) & [Github Repo](https://github.com/0xgasless/mcp)

In summary, the 0xGasless SDK represents a significant advancement in making blockchain technology more accessible and user-friendly while placing more emphasis on eliminating the complexities of gas fees, and enhancing security.

## C‑Chain (Avalanche) notes:

- **Native gas token**: AVAX (sponsored mode requires a funded paymaster).
- Many stablecoins (e.g., USDT) use 6 decimals, format amounts correctly.
- Ensure your API key is enabled for 43114 and that your paymaster gas tank is funded.


## Getting Started

To get started with 0xGasless, follow these steps:

1. **Sign up**: Create an account on the [0xGasless Platform](https://dashboard.0xgasless.com/) to access the dashboard and developer tools.
2. **Read the documentation**: See the [0xGasless docs](https://docs.0xgasless.com/) for installation guides, API references, and integrations.
3. **Fund the paymaster**: Follow the [guide](https://docs.0xgasless.com/Getting%20Started/create-a-page) and use the [dashboard](https://dashboard.0xgasless.com/) to create and fund the paymaster.
4. **Integrate the SDK**: Obtain API keys and configure the smart account, bundler, and paymaster using the SDK [docs](https://docs.0xgasless.com/Getting%20Started/create-a-page#step-1-obtain-required-api-keys).
5. **Explore modular options**: The SDK is modular; customize each step of the account abstraction cycle as needed.
6. **Test and deploy**: Leverage multi-chain support, thoroughly test, and ensure the paymaster gas tank remains funded for a smooth UX.

## Documentation

- For detailed guides, API references, and integration examples, visit [0xGasless Documentation](https://docs.0xgasless.com/).

- Dashboard for keys/paymasters: [0xGasless Dashboard](https://dashboard.0xgasless.com/).

## **Use Cases**

Anything can be built using the 0xGasless Account Abstraction SDK. Smart contract wallets are code; any required feature can be written as code.

- **AI Agents**: Streamline payment processes with smart accounts. Account abstraction provides a secure infrastructure for agents interacting with money.
- **DeFi Applications**: Improve accessibility and usability with gasless transactions and easy onboarding.
- **Enterprise Applications**: Manage complex access controls and transaction rules with scalable, secure integrations.
- **Crypto Wallets**: Develop secure and flexible wallets leveraging smart accounts for enhanced security, usability, and gasless transactions.
- **Digital Identity Management**: Manage digital identities with customizable transaction and access rules for secure, scalable identity.
- **Blockchain Games**: Provide seamless onboarding using social logins to manage in‑game assets and progress.
- **NFT Marketplaces**: Let users interact with platforms using their existing social accounts to improve acquisition and engagement.


## Conclusion

0xGasless stands as an advanced blockchain infrastructure platform with a primary emphasis on enhancing user experience through account abstraction. Leveraging ERC-4337, 0xGasless delivers a smart contract wallet solution, streamlining transactions and wallet management. This fosters a smoother interaction with decentralized applications (dApps), mitigating the usual complexity associated with Web3. Its modular SDK improves UX (gasless or token‑gas), security (programmable policies), and developer velocity (pluggable components) across dapps, agents, games, DeFi, and enterprises. On Avalanche C‑Chain and beyond, 0xGasless helps teams ship seamless, scalable, and secure web3 experiences.



# 3Sigma (/integrations/3sigma)

---
title: 3Sigma
category: Security Audits
available: ["C-Chain", "All EVM L1s"]
description: "3Sigma provides good-quality security audits with additional expertise in economic modeling for tokenomics and protocol design."
logo: /images/3sigma.png
developer: 3Sigma
website: https://threesigma.xyz/
---

## Overview

3Sigma is a security audit provider offering good-quality assessments for blockchain projects on Avalanche, with additional expertise in economic modeling. Beyond traditional security audits, they can analyze tokenomics and protocol economics, providing a more comprehensive evaluation of both technical security and economic design. This combined approach is particularly valuable for projects where economic incentives and security are closely intertwined.

## Features

- **Smart Contract Audits**: Thorough code reviews and vulnerability assessments.
- **Economic Modeling**: Specialized analysis of tokenomics and protocol economics.
- **20% Ecosystem Discount**: Referral discount available for Avalanche ecosystem projects.
- **Protocol Security**: Comprehensive examination of protocol design and implementation.
- **Incentive Analysis**: Evaluation of economic incentives and potential game-theoretic vulnerabilities.
- **Dual Expertise**: Combined security and economic analysis capabilities.
- **YFI Experience**: Notable experience with YFI economic modeling.

## Getting Started

To engage 3Sigma for security audits and economic modeling:

1. **Initial Contact**: Reach out through their website to discuss your project requirements.
2. **Mention Ecosystem**: Reference the Avalanche ecosystem for potential referral discounts.
3. **Assessment Process**: 
   - Technical security audit
   - Economic model analysis (if applicable)
   - Identification of both security and economic vulnerabilities
   - Comprehensive recommendations
4. **Report Delivery**: Receive detailed findings covering both security and economic aspects.
5. **Implementation Support**: Guidance on addressing identified issues.

## Use Cases

3Sigma audits are particularly valuable for:

- **DeFi Protocols**: Combined security and economic analysis for financial applications.
- **Novel Tokenomics**: Evaluation of innovative economic models and token designs.
- **Yield-Generating Protocols**: Assessment of yield mechanisms and associated risks.
- **Governance Systems**: Review of governance incentives and security.
- **Complex Economic Mechanisms**: Analysis of intricate economic interactions within protocols.

## Conclusion

3Sigma provides good-quality security audits with the unique addition of economic modeling expertise. This combined approach is particularly valuable for projects with complex tokenomics or economic mechanisms, offering insights into both technical vulnerabilities and potential economic exploits. With a 20% discount available for Avalanche ecosystem projects and notable experience in economic modeling (including work with YFI), 3Sigma offers a differentiated service that addresses both security and economic sustainability. 

# Aave (/integrations/aave)

---
title: Aave
category: Lending Protocols
available: ["C-Chain"]
description: "Aave is a leading decentralized lending protocol deployed on Avalanche, offering a robust platform for lending and borrowing with unique features like flash loans and stable rate borrowing."
logo: /images/aave.png
developer: Aave
website: https://aave.com/
documentation: https://docs.aave.com/
---

## Overview

Aave on Avalanche is a decentralized non-custodial liquidity protocol where users can participate as depositors or borrowers. Depositors provide liquidity to the market to earn a passive income, while borrowers can borrow in an overcollateralized or under-collateralized (flash loans) fashion. Aave leverages Avalanche's C-Chain for fast and cost-effective transactions.

## Features

- **Multiple Asset Markets**: Support for various cryptocurrencies and stablecoins.
- **Variable Interest Rates**: Dynamic rates based on market demand.
- **Stable Rate Borrowing**: Fixed-rate loans for better planning.
- **Flash Loans**: Uncollateralized loans within a single transaction.
- **Credit Delegation**: Delegate credit lines to other addresses.
- **Risk Management**: Advanced risk parameters and liquidation mechanisms.
- **Governance**: Community governance through AAVE token.
- **Safety Module**: Risk mitigation through staking.

## Getting Started

To begin using Aave on Avalanche:

1. **Access Platform**: Visit [Aave](https://aave.com/) and select Avalanche network.
2. **Connect Wallet**: Link your Web3 wallet with AVAX for gas fees.
3. **Supply or Borrow**: 
   - Deposit assets to earn interest
   - Use deposits as collateral for borrowing
   - Monitor health factor
4. **Manage Positions**: Track and adjust positions based on market conditions.

## Documentation

For comprehensive protocol documentation, visit the [Aave Documentation](https://docs.aave.com/).

## Use Cases

Aave serves various DeFi needs:

- **Yield Generation**: Earn interest by supplying assets to lending pools.
- **Leveraged Positions**: Borrow against collateral for trading or yield farming.
- **Flash Loans**: Execute complex DeFi strategies in single transactions.
- **Stable Rate Loans**: Access fixed-rate borrowing for predictable costs.
- **Credit Delegation**: Enable under-collateralized lending through trust.

## Conclusion

Aave on Avalanche provides a sophisticated lending protocol with advanced features and robust risk management. By combining Aave's battle-tested protocol with Avalanche's high-performance infrastructure, users can access efficient lending and borrowing services with enhanced speed and reduced costs. Whether you're looking to earn yield, access leverage, or execute complex DeFi strategies, Aave offers a comprehensive solution on Avalanche. 


# Alchemy (/integrations/alchemy)

---
title: Alchemy
category: RPC Providers
available: ["C-Chain"]
description: Alchemy is a blockchain developer platform that provides a suite of APIs and tools for building and scaling blockchain applications.
logo: /images/alchemy.png
developer: Alchemy
website: https://www.alchemy.com/
documentation: https://docs.alchemy.com/
---

## Overview

Alchemy is a comprehensive blockchain development platform that offers developers a wide range of tools and services. It simplifies the process of building, managing, and scaling blockchain applications. Alchemy’s platform provides access to various blockchain networks, including Ethereum, Polygon, and more, through reliable and scalable RPC (Remote Procedure Call) nodes.

## Features

- **Scalable Infrastructure**: Alchemy provides high-performance, scalable nodes that support various blockchain networks.
- **Enhanced APIs**: Alchemy offers a suite of enhanced APIs, including the Alchemy API, that simplifies interaction with blockchain networks.
- **Developer Tools**: Tools such as Alchemy Build, Monitor, and Notify help developers debug, track, and alert on blockchain transactions and events.
- **Reliable Uptime**: With distributed and redundant infrastructure, Alchemy ensures maximum uptime for your blockchain applications.
- **Analytics and Insights**: Gain insights into blockchain data and application performance through Alchemy’s analytics tools.

## Getting Started

To start using Alchemy, follow these steps:

1. **Sign Up**: Create an account on [Alchemy](https://www.alchemy.com/).
2. **Create an App**: After signing in, create a new application in your Alchemy dashboard. Choose the blockchain network you want to connect to.
3. **Get API Key**: Once your application is set up, you’ll be provided with an API key. This key is used to authenticate your requests to the Alchemy RPC node.
4. **Integrate with Your Project**: Use the API key to connect your blockchain application to the Alchemy network. You can integrate using the provided SDKs or directly via HTTP requests.

## Documentation

For detailed guides and API references, visit the [Alchemy Documentation](https://docs.alchemy.com/).

## Use Cases

Alchemy can be used in various blockchain development scenarios:

- **Decentralized Applications (DApps)**: Power your DApps with reliable and scalable blockchain infrastructure.
- **Analytics and Monitoring**: Use Alchemy’s tools to monitor blockchain events and transactions in real-time.
- **Smart Contracts**: Deploy and interact with smart contracts on multiple blockchain networks.

## Conclusion

Alchemy is a powerful tool for blockchain developers, offering a robust suite of APIs, tools, and infrastructure to build, scale, and monitor blockchain applications with ease. Whether you're building a simple DApp or a complex blockchain project, Alchemy provides the resources you need to succeed.



# Allbridge Core (/integrations/allbridge-core)

---
title: Allbridge Core
category: ["Crosschain Solutions"]
available: ["C-Chain"]
description: Allbridge Core enables native stablecoin transfers across blockchains without wrapping — powering frictionless DeFi and multi-chain liquidity.
logo: /images/allbridge-core.svg
developer: Allbridge
website: https://core.allbridge.io/
documentation: https://docs-core.allbridge.io/
---

## Overview

[Allbridge Core](https://core.allbridge.io) is a **cross-chain liquidity protocol** designed for **native stablecoin transfers** between major ecosystems such as Avalanche, Ethereum, Solana, and Tron.

Unlike traditional bridges that rely on wrapped or synthetic assets, Allbridge Core maintains liquidity pools of native stablecoins on each chain.
When users transfer funds, the value is transmitted via a messaging protocol and redeemed in the target network - **securely and with native tokens**.

Key features include:
- **Native Transfers**: Move native stablecoins (USDT, USDC, USDe, etc.) across chains without wrapping.
- **Messaging-Agnostic Design**: Integrate using Allbridge Messaging, Circle’s CCTP, and LayerZero OFT
- **Flexible Fee Options**: Pay bridge fees in stablecoins or gas tokens for a smoother UX.
- **Optional Gas Top-Up**: Users can receive AVAX on the destination chain to cover initial transactions.
- **Developer Tools**: Full SDK and REST API for quick integration into dApps, wallets, and exchanges.

## Getting Started

Allbridge Core SDK enables you to onboard cross-chain functionality into your protocol. Follow these instructions to get started using our SDK.

1. **Installation**:
    * **Using npm**
        ```txt
         $ npm install @allbridge/bridge-core-sdk
        ```
    * **Using yarn**
        ```txt
         $ yarn add @allbridge/bridge-core-sdk
        ```
    * **Using pnpm**
        ```txt
         $ pnpm add @allbridge/bridge-core-sdk
        ```
2. **Initialize the SDK instance with your node RPC URLs**:
    ```tsx
        import { AllbridgeCoreSdk, nodeRpcUrlsDefault } from "@allbridge/bridge-core-sdk";
        // Connections to blockchains will be made through your rpc-urls passed during initialization
        const sdk = new AllbridgeCoreSdk({
            ...nodeRpcUrlsDefault,
            TRX: "your trx-rpc-url",
            ETH: "your eth-rpc-url"
        });
    ```

## Documentation

For detailed guides, API references, and advanced integration examples, visit the [Allbridge Core Documentation](https://docs-core.allbridge.io/sdk/get-started)

## Use Cases

1. **Stablecoin Swaps**:
    Transfer your stables between EVM and non-EVM compatible chains.
2. **Seamless User Onboarding**:
    By enabling the optional gas top-up, Allbridge Core reduces the barriers to entry into the Avalanche ecosystem.
3. **dApp and Wallet Integrations**:
    Integrate cross-chain swaps directly into wallets, DEXs, or other dApps via our SDK/REST API.
4. **Flexible Transfers**:
    Choose between multiple supported messaging protocols to match your bridging needs.

## Conclusion

Allbridge Core enhances the Avalanche ecosystem by enabling seamless stablecoin transfers from other major blockchains.
By simplifying the bridging experience, it expands Avalanche’s accessibility and utility across the broader DeFi landscape.
It also empowers developers on the Avalanche C-Chain with tools to integrate cross-chain access into their applications easily.

# API3 (/integrations/api3)

---
title: API3
category: Oracles
available: ["C-Chain"]
description: API3 is a first-party oracle solution that enables dApps to access APIs in a decentralized and trust-minimized way.
logo: /images/api3.png
developer: API3 Alliance
website: https://api3.org/
documentation: https://docs.api3.org/
---

## Overview

API3 is an innovative oracle solution designed to connect decentralized applications (dApps) with real-world data. Unlike traditional third-party oracles, API3 uses first-party oracles that allow data providers to operate their own oracles, ensuring data authenticity and minimizing trust issues. This makes API3 a highly secure and reliable solution for integrating off-chain data into smart contracts.

## Features

- **First-Party Oracles**: API3 enables data providers to run their own oracles, removing intermediaries and reducing trust concerns.
- **Decentralized Governance**: The API3 DAO governs the network, ensuring a decentralized and community-driven approach.
- **dAPIs (Decentralized APIs)**: API3 offers decentralized APIs, which are aggregated and delivered by first-party oracles, providing a seamless way to access off-chain data.
- **Airnode**: API3’s flagship technology, Airnode, allows any API provider to deploy a first-party oracle without technical expertise.
- **Data Transparency**: Ensures complete transparency in how data is sourced and delivered to smart contracts.

## Getting Started

To begin using API3, follow these steps:

1. **Sign Up**: Visit the [API3 website](https://api3.org/) to learn more and get involved with the community.
2. **Explore Airnode**: Check out the [Documentation](https://docs.api3.org/) to understand how to deploy your own first-party oracle.
3. **Integrate dAPIs**: Utilize API3’s decentralized APIs by following the integration guides available in the [API3 documentation](https://docs.api3.org/).

## Documentation

For detailed technical guides, integration tutorials, and API references, visit the [API3 Documentation](https://docs.api3.org/).

## Use Cases

API3 can be utilized in various scenarios where trust-minimized data access is crucial:

- **DeFi Platforms**: Integrate accurate and reliable off-chain data, such as price feeds, into decentralized finance (DeFi) applications.
- **Insurance dApps**: Leverage real-world data for automated insurance claims and payouts using smart contracts.
- **Supply Chain Management**: Track and verify supply chain data using first-party oracles to ensure authenticity and reduce fraud.

## Conclusion

API3 revolutionizes the way dApps access off-chain data by utilizing first-party oracles. With its decentralized governance and innovative technology like Airnode, API3 offers a secure, transparent, and reliable solution for integrating real-world data into smart contracts. Whether you're building a DeFi application, an insurance platform, or any other blockchain-based solution, API3 provides the tools you need for trust-minimized data integration.



# Ash (/integrations/ash)

---
title: Ash
category: Blockchain as a Service
available: ["All Avalanche L1s"]
description: Ash is the one-stop shop for L1 development and operation on Avalanche, 100% cloud-agnostic.
logo: /images/ash.png
developer: E36 Knots
website: https://ash.center/
documentation: https://ash.center/docs/toolkit/
---

## Overview

Ash is a suite of open-source tools and services for Avalanche L1 development and operations. Ash is 100% cloud-agnostic and can be used to provision Avalanche validator nodes, L1s, block explorers and more!

## Features

- **Ash Console**: The Ash Console is the one-stop shop for **Appchain development and operation** on Avalanche. It allows you to manage your validators, create L1s and monitor your network **on your own infrastructure** (AWS, GCP and Azure are supported, with more cloud providers to come).
- **Ansible Avalanche Collection**: The [Ansible Avalanche Collection](https://github.com/AshAvalanche/ansible-avalanche-collection) provides [Ansible](https://www.ansible.com/) roles, playbooks and modules to manage Avalanche nodes, L1s and more on any infrastructure.
- **Ash CLI**: The [Ash CLI](https://ash.center/docs/toolkit/ash-cli/introduction) aims to boost Avalanche developers' productivity by providing a set of commands to interact with Avalanche and Ash services.
- **Ash Wallet**: A free-to-use shared infrastructure bringing all the features of [Safe](/integrations/gnosis-safe) (prev. Gnosis Safe) to the Avalanche L1s ecosystem. Read the [official announcement](https://ashavax.hashnode.dev/announcing-ash-wallet-for-avalanche-l1s) to learn more.

## Getting Started

There are many ways to get started with Ash depending on your use case:

- **One command Devnet**: Learn how to set up an [Avalanche devnet in a single command](https://ash.center/docs/console/guides/blueprint/) with the Ash Console. Perfect for infrastructure beginners!
- **HyperChain on AWS**: Are you an HyperSDK developer? Check out the [HyperSDK devnet on AWS](https://ash.center/docs/toolkit/ansible-avalanche-collection/tutorials/hypersdk-devnet-aws) tutorial to learn how to deploy your HyperChain at scale with Terraform and Ansible.
- **Avalanche L1s Exploration**: The Ash CLI is the perfect tool to explore Avalanche networks from the command line. Check out our [examples](https://ash.center/docs/toolkit/ash-cli/tutorials/network-exploration) of what you can do with it.

## Documentation

For detailed technical tutorials and API references, visit the [Ash Console](https://ash.center/docs/console/) and [Ash toolkit](https://ash.center/docs/toolkit/) documentations.

## Use Cases

Ash can be used for a variety of use cases:

- **Avalanche Validator Nodes**: Deploy and manage Avalanche validator nodes on your preferred cloud infrastructure with ease.
- **L1 Development**: Create and operate custom Avalanche L1s for specialized blockchain applications or private networks.
- **Add Safe-like features to your L1**: Bring the features of Safe (account abstraction, multisig wallets, etc.) to your Subnet-EVM based L1.

## Conclusion

Ash is here to help you build and operate Avalanche L1s and Avalanche L1s. Whether you're an L1 developer or an Avalanche validator, expert in infrastructure or just getting started, Ash has you covered with its suite of tools and services.


# Ava Cloud (/integrations/avacloud)

---
title: Ava Cloud
category: Blockchain as a Service
available: ["All EVM L1s"]
description: Ava Cloud is a cloud-based service that provides a suite of tools for developers to interact with the Avalanche network.
logo: /images/avacloud.png
developer: Ava Labs
website: https://avacloud.io/
documentation: https://support.avacloud.io/
featured: true
---

## Overview

Ava Cloud is a cloud-based service developed by Ava Labs that offers a comprehensive suite of tools for developers to interact with the Avalanche network. It provides a streamlined environment for building, deploying, and managing blockchain applications on Avalanche, simplifying the development process while offering robust scalability and performance.

## Features

- **Cloud-Based Infrastructure**: Access a cloud-based platform that offers reliable and scalable infrastructure for interacting with the Avalanche network.
- **Developer Tools**: Utilize a wide range of tools designed to simplify smart contract development, deployment, and management.
- **Automated Deployment**: Streamline the deployment process with automated tools that make launching applications on Avalanche fast and efficient.
- **Scalability**: Benefit from scalable cloud resources that adapt to your application's needs, ensuring consistent performance.
- **Support and Documentation**: Access extensive support and documentation to guide developers through the setup and usage of Ava Cloud.

## Getting Started

To begin using Ava Cloud:

1. **Visit the Ava Cloud Website**: Explore the [Ava Cloud website](https://avacloud.io/) to learn more about its services and capabilities.
2. **Access the Documentation**: Refer to the [Ava Cloud Documentation](https://support.avacloud.io/) for detailed guides on using the platform, including setup, configuration, and API usage.
3. **Create an Account**: Sign up for an Ava Cloud account to start leveraging cloud-based tools for your Avalanche projects.
4. **Deploy Applications**: Use the platform’s tools to build, deploy, and manage your applications on the Avalanche network.
5. **Monitor and Optimize**: Take advantage of monitoring tools to track the performance of your applications and optimize as needed.

## Documentation

For comprehensive guides, API references, and support, visit the [Ava Cloud Documentation](https://support.avacloud.io/).

## Use Cases

Ava Cloud is ideal for various blockchain development scenarios:

- **Smart Contract Development**: Simplify the development and deployment of smart contracts on the Avalanche network.
- **Decentralized Applications (dApps)**: Build and scale dApps with cloud-based resources tailored for Avalanche.
- **Enterprise Solutions**: Develop and manage enterprise-level blockchain applications with robust cloud infrastructure.
- **Blockchain Prototypes**: Rapidly prototype and test blockchain applications in a scalable cloud environment.

## Conclusion

Ava Cloud provides developers with a powerful cloud-based platform tailored for the Avalanche network. With its comprehensive suite of tools, automated deployment capabilities, and scalable infrastructure, Ava Cloud simplifies blockchain development and ensures that your applications perform reliably on the Avalanche network. Whether you're building dApps, smart contracts, or enterprise solutions, Ava Cloud offers the resources and support needed to succeed.



# Avalanche Explorer (/integrations/avalanche-explorer)

---
title: Avalanche Explorer
category: Block Explorers
available: ["C-Chain", "All EVM L1s"]
description: Avalanche L1 Explorer is an analytics tool for exploring Avalanche L1 transactions, addresses, statistics, and other platform activities.
logo: /images/avax.avif
developer: Ava Labs
website: https://subnets.avax.network/
documentation: https://build.avax.network/docs
featured: true
---

## Overview

Avalanche Explorer is a powerful analytics tool developed by Ava Labs, designed specifically for exploring transactions, addresses, statistics, and other activities on Avalanche L1s. It provides users with detailed, real-time data across various Avalanche L1s, making it an essential resource for developers, validators, and anyone involved in the Avalanche ecosystem.

## Features

- **Avalanche L1-Specific Data**: Explore real-time data for individual Avalanche L1s, including transactions, addresses, and other key metrics.
- **Comprehensive Analytics**: Gain insights into platform activities, with detailed statistics on network performance and usage.
- **User-Friendly Interface**: Navigate through different Avalanche L1s and explore blockchain data with ease using an intuitive interface.
- **Validator Monitoring**: Track validator activities, including performance metrics and staking information, across Avalanche L1s.
- **API Access**: Utilize the Avalanche Explorer API to integrate Avalanche L1 data into your applications or services.
- **Historical Data**: Access historical data to analyze trends and network activity over time.

## Getting Started

To begin using Avalanche Explorer:

1. **Visit Avalanche Explorer**: Head to the [Avalanche L1 Explorer website](https://subnets.avax.network/) to start exploring the data.
2. **Explore Avalanche L1 Data**: Use the explorer to view real-time transactions, address activity, and network statistics for individual Avalanche L1s.
3. **Monitor Validators**: Access detailed validator information to track performance and staking activities within Avalanche L1s.
4. **Access Documentation**: For more detailed instructions and technical information, visit the [Avalanche Documentation](https://build.avax.network/docs).
5. **Integrate with API**: Developers can use the API to pull data into their own platforms or applications for further analysis or display.

## Documentation

For more information on using Avalanche Explorer and integrating its data into your projects, check out the [Avalanche Documentation](https://build.avax.network/docs).

## Use Cases

Avalanche Explorer is perfect for:

- **Developers**: Monitor Avalanche L1-specific blockchain activity for development, debugging, and smart contract interaction.
- **Validators**: Track and optimize validator performance across Avalanche L1s with detailed, real-time data.
- **Blockchain Enthusiasts**: Explore the Avalanche network and Avalanche L1s, tracking transactions, addresses, and network activity.
- **Analysts and Researchers**: Access and analyze Avalanche L1 data for research and analytics purposes.

## Conclusion

Avalanche Explorer is a crucial tool for anyone involved with Avalanche L1s. With its detailed real-time analytics, intuitive interface, and robust API, it provides comprehensive insights into Avalanche L1 transactions, validator performance, and network activity. Whether you’re a developer, validator, or blockchain enthusiast, Avalanche Explorer offers the data and tools you need to effectively monitor and analyze Avalanche L1s.



# Avascan (/integrations/avascan)

---
title: Avascan
category: Block Explorers
available: ["C-Chain", "All Avalanche L1s"]
description: Avascan is a block explorer for the Avalanche network, providing real-time data on transactions, blocks, validators, and more.
logo: /images/avascan.jpg
developer: Routescan
website: https://avascan.info/
documentation: https://docs.avascan.info/
---

## Overview

Avascan is the official block explorer for the Avalanche network, offering a comprehensive view of blockchain activity. It provides real-time data on transactions, blocks, validators, and other key metrics, making it an essential tool for developers, validators, and anyone interested in monitoring the Avalanche blockchain.

## Features

- **Real-Time Data**: Access up-to-the-minute information on transactions, block details, and validator activities.
- **User-Friendly Interface**: Navigate easily through the Avalanche network's data with an intuitive and well-designed interface.
- **Validator Insights**: Explore detailed information on validators, including performance metrics and staking details.
- **Multi-Chain Support**: Supports multiple chains within the Avalanche network, providing a unified view across different chains.
- **Advanced Search**: Utilize powerful search functionalities to quickly find transactions, addresses, and block information.
- **API Access**: Offers API access for developers to integrate Avascan's data into their applications and services.

## Getting Started

To start using Avascan:

1. **Visit Avascan**: Go to the [Avascan website](https://avascan.info/) to explore its features and start navigating the Avalanche network.
2. **Use the Search Functionality**: Use the search bar to find specific transactions, blocks, or validators.
3. **Explore Validator Data**: Dive into detailed validator statistics, including staking information and performance metrics.
4. **Access Documentation**: Refer to the [Avascan Documentation](https://docs.avascan.info/) for guidance on using the explorer, API integration, and advanced features.
5. **Integrate with API**: Developers can use the API to fetch and display Avascan data within their own applications.

## Documentation

For more details on using Avascan, including how to access its API and utilize its features, visit the [Avascan Documentation](https://docs.avascan.info/).

## Use Cases

Avascan is ideal for:

- **Blockchain Developers**: Monitor and analyze blockchain activity for development and debugging purposes.
- **Validators**: Track and optimize validator performance with real-time data and historical insights.
- **Researchers and Analysts**: Conduct in-depth analysis of the Avalanche blockchain with comprehensive data access.
- **General Users**: Explore and verify transactions, blocks, and network status in a user-friendly environment.

## Conclusion

Avascan is a powerful block explorer tailored for the Avalanche network, providing a rich set of features and real-time data for a wide range of users. Whether you are a developer, validator, or just a curious user, Avascan offers the tools you need to effectively explore and understand the Avalanche blockchain. With its intuitive interface and detailed insights, Avascan is the go-to platform for monitoring the Avalanche network.



# Axelar (/integrations/axelar)

---
title: Axelar
category: Crosschain Solutions
available: ["C-Chain"]
description: "Axelar delivers secure cross-chain communication for Avalanche, enabling seamless asset transfers and general message passing between blockchain networks."
logo: /images/axelar.jpeg
developer: Axelar Network
website: https://axelar.network/
documentation: https://docs.axelar.dev/
---

## Overview

Axelar is a decentralized interoperability network that enables secure cross-chain communication for Avalanche. It provides infrastructure for both general message passing and asset transfers between different blockchain networks, utilizing a proof-of-stake validator network to ensure security and reliability of cross-chain operations.

## Features

- **General Message Passing**: Send arbitrary messages between supported chains.
- **Cross-Chain Token Transfers**: Native and wrapped asset transfers across networks.
- **Gateway Protocol**: Standardized interface for cross-chain communication.
- **Proof-of-Stake Security**: Decentralized validator network securing messages.
- **Gas Payment Service**: Pay transaction fees in any supported token.
- **Composable Architecture**: Build complex cross-chain applications.
- **Developer SDK**: Comprehensive tools and libraries for integration.

## Getting Started

To integrate Axelar:

1. **Review Documentation**: Study the [Axelar Documentation](https://docs.axelar.dev/).
2. **Choose Service**: 
   - General Message Passing (GMP) for custom logic
   - Gateway for asset transfers
   - Satellite for one-click transfers
3. **Implement SDK**: 
   - Install Axelar SDK
   - Configure for Avalanche
   - Test cross-chain functionality
4. **Monitor Operations**: Track cross-chain messages and transfers.

## Documentation

For comprehensive integration guides and technical details, visit the [Axelar Documentation](https://docs.axelar.dev/).

## Use Cases

Axelar enables various cross-chain scenarios:

- **Token Transfers**: Move assets seamlessly between chains.
- **Cross-Chain dApps**: Build applications that work across networks.
- **Remote Contract Execution**: Execute contracts on different chains.
- **Cross-Chain DEX**: Implement cross-chain trading functionality.
- **Interchain Accounts**: Manage accounts across multiple chains.

## Conclusion

Axelar provides essential infrastructure for secure cross-chain communication on Avalanche's C-Chain. With its robust security model, comprehensive feature set, and developer-friendly tools, Axelar enables the creation of sophisticated cross-chain applications. Whether you're building a simple token bridge or a complex cross-chain protocol, Axelar offers the security and functionality needed for reliable interchain operations. 

# Benqi (/integrations/benqi)

---
title: Benqi
category: Lending Protocols
available: ["C-Chain"]
description: "Benqi is an Avalanche-native algorithmic liquidity market protocol, enabling users to effortlessly lend, borrow, and earn interest with their digital assets."
logo: /images/benqi.jpg
developer: Benqi Finance
website: https://benqi.fi/
documentation: https://docs.benqi.fi/
---

## Overview

Benqi is a native Avalanche liquidity market protocol that enables users to lend, borrow, and earn interest on their crypto assets. Built specifically for the Avalanche ecosystem, Benqi offers efficient lending and borrowing services with competitive rates, leveraging Avalanche's fast and low-cost infrastructure.

## Features

- **Lending Markets**: Supply various crypto assets to earn interest.
- **Borrowing**: Borrow assets against supplied collateral.
- **Safety Module**: Risk mitigation through QI staking.
- **Liquid Staking**: Stake AVAX while maintaining liquidity through sAVAX.
- **Governance**: Community governance through QI token.
- **Flash Loans**: Uncollateralized loans for instant arbitrage or liquidations.
- **Avalanche Native**: Optimized for Avalanche's C-Chain performance.

## Getting Started

To begin using Benqi:

1. **Access Platform**: Visit [Benqi](https://benqi.fi/).
2. **Connect Wallet**: Link your Web3 wallet with AVAX for transactions.
3. **Supply Assets**: 
   - Deposit supported assets to earn interest
   - Use deposits as collateral for borrowing
4. **Manage Positions**: Monitor health factors and adjust positions as needed.

## Documentation

For detailed protocol documentation and guides, visit the [Benqi Documentation](https://docs.benqi.fi/).

## Use Cases

Benqi serves various DeFi needs:

- **Passive Income**: Earn interest by supplying assets to lending markets.
- **Leveraged Trading**: Borrow assets against collateral for trading.
- **Liquid Staking**: Stake AVAX while maintaining liquidity.
- **Flash Loans**: Execute arbitrage or liquidation strategies.
- **Treasury Management**: Efficient management of crypto assets with yield generation.

## Conclusion

Benqi provides a robust lending and borrowing protocol native to the Avalanche ecosystem. With its focus on efficiency, security, and user experience, Benqi offers essential DeFi services while leveraging Avalanche's high-performance infrastructure. Whether you're looking to earn yield on your assets or access liquidity, Benqi delivers a comprehensive solution for DeFi users on Avalanche. 

# Biconomy (/integrations/biconomy)

---
title: Biconomy
category: Account Abstraction
available: ["C-Chain"]
description: Leverage the Biconomy Smart Accounts Platform to endlessly add UX capability by easily & securely plugging in programmable modules.
logo: /images/biconomy.png
developer: Biconomy
website: https://www.biconomy.io/
documentation: https://docs.biconomy.io/
---

## Overview

Biconomy is a next-generation platform that simplifies blockchain development by enabling account abstraction and enhancing user experience through programmable modules. By leveraging Biconomy's Smart Accounts Platform, developers can build more intuitive, user-friendly decentralized applications (dApps) that offer features like gasless transactions, multi-chain support, and seamless onboarding, all while maintaining a high level of security and scalability.

## Features

- **Account Abstraction**: Biconomy provides a flexible architecture that abstracts away the complexities of blockchain accounts, making it easier to manage user accounts and interactions.
- **Gasless Transactions**: Enable users to interact with dApps without needing to hold cryptocurrency for gas fees, improving accessibility and reducing friction.
- **Modular Architecture**: Easily add or customize functionalities with programmable modules that enhance the user experience.
- **Multi-Chain Support**: Seamlessly integrate with multiple blockchains, allowing dApps to operate across different networks without compromising on performance or security.
- **Seamless Onboarding**: Simplify the onboarding process for new users with features like social login, reducing the barriers to entry for non-crypto-savvy users.

## Getting Started

To get started with Biconomy, follow these steps:

1. **Sign Up**: Create an account on the [Biconomy Platform](https://dashboard.biconomy.io/) to access the dashboard and developer tools.
2. **Set Up Smart Accounts**: Use the dashboard to set up Smart Accounts for your dApp, enabling account abstraction and programmable modules.
3. **Integrate Gasless Transactions**: Follow the [documentation](https://docs.biconomy.io/about#quickstart) to integrate gasless transactions into your dApp, improving the user experience.
4. **Explore Programmable Modules**: Leverage Biconomy's modular architecture to customize and add new features to your dApp using the available modules.
5. **Deploy on Multiple Chains**: Utilize Biconomy's multi-chain support to deploy your dApp across different blockchain networks, ensuring broader reach and usability.

## Documentation

For detailed guides, API references, and integration examples, visit the [Biconomy Documentation](https://docs.biconomy.io/).

## Use Cases

Biconomy can be utilized in various scenarios where enhanced user experience and seamless blockchain interaction are crucial:

- **DeFi Applications**: Improve the accessibility and usability of decentralized finance (DeFi) platforms with gasless transactions and easy onboarding.
- **Gaming dApps**: Enhance the gaming experience by abstracting complex blockchain interactions, allowing users to focus on gameplay.
- **NFT Marketplaces**: Simplify the process of buying, selling, and trading NFTs by eliminating the need for users to manage gas fees and complex wallet interactions.

## Conclusion

Biconomy is a powerful tool for developers looking to build user-friendly, scalable, and secure decentralized applications. With its account abstraction, gasless transactions, and modular architecture, Biconomy enables you to create dApps that offer a seamless user experience without sacrificing the security and decentralization benefits of blockchain technology. Whether you're developing a DeFi platform, a gaming application, or an NFT marketplace, Biconomy provides the tools you need to succeed.



# BlockJoy (/integrations/blockjoy)

---
title: BlockJoy
category: RPC Providers
available: ["C-Chain","P-Chain","X-Chain"]
description: BlockJoy specializes in fast, dedicated, unmetered blockchain nodes on bare metal
logo: /images/blockjoy.png
developer: BlockJoy
website: https://www.blockjoy.com/
---

## Overview

BlockJoy specializes in fast, dedicated, unmetered blockchain nodes on bare metal, purpose-built Web3 infrastructure without Docker, Kubernetes, or Ansible. Run on your infrastructure or ours with one-click deployment of fully synced AVAX archive nodes.
## Features

- **Fast setup**: One-click deployments for 50+ blockchains via our UI or API.
- **Efficiency**: Nearly-synced nodes with our snapshot services.
- **Flexibility**: Support for custom node settings, side-loading indexers, databases, and more.
- **Reliability**: 24/7 monitoring and incident response from our SRE team.

## Getting Started

To start using BlockJoy:

1. **Visit the BlockJoy Website**: Explore the [BlockJoy website](https://www.blockjoy.com/) to understand its features and offerings.
2. **Create an Account**: Sign up for a BlockJoy account to gain access to your node and start integrating blockchain functionality into your applications.
4. **Launch a node**: Deploy dedicated node with a click of a button to data center of your choice.
5. **Monitor and Optimize**: Utilize BlockJoy’s monitoring and analytics tools to track performance and optimize your blockchain applications.

## Conclusion

We’re not your typical provider — BlockJoy is built specifically to make blockchain node management seamless and cost-effective. Whether you need fully managed nodes on our servers or prefer running infrastructure on yours, we deliver enterprise-grade performance at the most competitive price.


# Blockscout (/integrations/blockscout)

---
title: Blockscout
category: Block Explorers
available: ["C-Chain", "All EVM Chains"]
description: Blockscout is an open-source, multichain block explorer for EVM-based networks, providing comprehensive tools for searching, analyzing, and verifying blockchain data across hundreds of chains. It supports transaction tracking, contract verification, token and NFT analytics, and developer APIs.
logo: /images/blockscout.png
developer: Blockscout
website: https://www.blockscout.com/
documentation: https://docs.blockscout.com/
---

## Overview
Blockscout is a leading open-source block explorer designed for all Ethereum Virtual Machine (EVM) compatible networks, including Avalanche C-Chain. It offers a unified interface for exploring blocks, transactions, accounts, tokens, and NFTs across hundreds of supported chains. Blockscout is trusted by developers and users for its transparency, extensibility, and advanced analytics capabilities.

## Features
- **Multichain Support**: Explore and analyze data across 1000+ EVM-based blockchains and rollups.
- **Transaction & Address Search**: Track transactions, monitor wallet activity, and inspect smart contract interactions.
- **Smart Contract Verification**: Verify, publish, and interact with smart contracts directly from the explorer.
- **Token & NFT Analytics**: Analyze ERC20 token movements, NFT collections, and associated metadata.
- **ENS Lookup**: Seamlessly resolve and search Ethereum Name Service addresses.
- **Developer APIs**: Access REST and JSON RPC APIs, tagging, debuggers, and more for custom integrations.
- **Open Source**: Fully open-source and community-driven, ensuring transparency and security.

## Getting Started
1. **Explore Blockscout**: Visit [Blockscout](https://www.blockscout.com/) to browse supported networks and try the explorer features.
2. **Self-Host for Avalanche**: For Avalanche-specific or private deployments, see the [Avalanche L1 Toolbox Self-Hosted Explorer Guide](https://build.avax.network/console/layer-1/explorer-setup).
3. **Verify Contracts**: Use the explorer to verify and interact with smart contracts on your network.
4. **Integrate APIs**: Leverage Blockscout's APIs for analytics, dApp integrations, and custom dashboards.
5. **Review Documentation**: Access full guides and references at the [Blockscout Documentation](https://docs.blockscout.com/).

## Documentation
For comprehensive integration guides, API references, and developer resources, visit the [Blockscout Documentation](https://docs.blockscout.com/).

## Use Cases
- **Network Transparency**: Provide users and developers with a transparent view of blockchain activity.
- **Smart Contract Development**: Verify, debug, and interact with contracts on EVM chains.
- **Token & NFT Analytics**: Track token transfers, NFT mints, and ecosystem trends.
- **Custom Deployments**: Launch your own explorer instance for private or public networks (see [Avalanche L1 Toolbox](https://build.avax.network/tools/l1-toolbox#selfHostedExplorer)).
- **dApp & Wallet Integrations**: Use Blockscout APIs to power analytics, dashboards, and wallet features.

## Conclusion
Blockscout is a powerful, open-source block explorer for the EVM ecosystem, supporting both public and private networks. Its multichain capabilities, developer tools, and transparent approach make it a top choice for projects seeking reliable blockchain data and analytics. For Avalanche-specific deployments, refer to the [L1 Toolbox Self-Hosted Explorer Guide](https://build.avax.network/tools/l1-toolbox#selfHostedExplorer). 

# Blocksec (/integrations/blocksec)

---
title: Blocksec
category: Security Audits
available: ["C-Chain", "All EVM L1s"]
description: "BlockSec provides high-quality security audits with particular expertise in USP exploit detection and blockchain security."
logo: /images/blocksec.jpeg
developer: BlockSec
website: https://blocksec.com/
---

## Overview

BlockSec is a high-quality security audit provider specializing in blockchain security with particular expertise in identifying USP exploits. Their security team combines academic research with practical security experience to deliver comprehensive audits for projects building on Avalanche. Noted in the ecosystem as "extremely helpful," BlockSec's approach to security assessments emphasizes practical vulnerability detection and remediation.

## Features

- **Smart Contract Audits**: Thorough code reviews and vulnerability assessments.
- **USP Exploit Detection**: Specialized expertise in identifying and preventing exploit vectors.
- **Security Monitoring**: Real-time monitoring solutions for blockchain projects.
- **Threat Intelligence**: Insights on emerging attack patterns and vulnerabilities.
- **Academic Approach**: Research-based methodology for security analysis.
- **Incident Response**: Support during security incidents and exploits.
- **Continuous Protection**: Ongoing security monitoring and assessment.

## Getting Started

To engage BlockSec for security audits:

1. **Initial Contact**: Reach out through their website to discuss your audit requirements.
2. **Audit Planning**: Define the scope, timeline, and specific security objectives.
3. **Audit Process**: 
   - Smart contract code review
   - Automated vulnerability scanning
   - Manual security analysis
   - Comprehensive exploit testing
4. **Findings Report**: Detailed documentation of security issues with severity ratings.
5. **Remediation Guidance**: Specific recommendations for addressing identified vulnerabilities.

## Use Cases

BlockSec security audits are particularly valuable for:

- **DeFi Protocols**: Thorough security validation for financial applications.
- **NFT Marketplaces**: Identifying vulnerabilities in NFT-related smart contracts.
- **Cross-Chain Applications**: Security assessment of bridge and cross-chain mechanisms.
- **Exchange Platforms**: Audit of exchange and trading contract implementations.
- **Protocol Implementations**: Verification of protocol security properties.

## Conclusion

BlockSec delivers high-quality security audits with particular strengths in USP exploit detection and practical security analysis. Their team combines academic research with hands-on security expertise to provide thorough assessments for projects building on Avalanche. Noted for being "extremely helpful" in the ecosystem, BlockSec offers both comprehensive audits and practical security guidance that helps projects build secure, resilient blockchain applications. 

# Certora (/integrations/certora)

---
title: Certora
category: Security Audits
available: ["C-Chain", "All EVM L1s"]
description: "Certora provides high-quality formal verification and security audits for smart contracts with specialized expertise in mathematical verification."
logo: /images/certora.png
developer: Certora
website: https://www.certora.com/
documentation: https://docs.certora.com/en/latest/
---

## Overview

Certora is a highly regarded security firm specializing in formal verification and comprehensive security audits for smart contracts. Using their proprietary Certora Prover technology, they can mathematically verify critical security properties of smart contracts, providing a level of assurance beyond traditional auditing approaches. Their team of formal verification experts and security researchers has been highlighted as highly recommended by security teams in the Avalanche ecosystem.

## Features

- **Formal Verification**: Mathematical verification of smart contract properties using the Certora Prover.
- **Smart Contract Audits**: Comprehensive security reviews combining formal methods with traditional auditing.
- **Custom Specification Development**: Creation of formal specifications for critical security properties.
- **Automated Analysis**: Advanced automated tools for detecting vulnerabilities.
- **Security Research**: Ongoing research into formal verification techniques for blockchain security.
- **Developer Education**: Resources for implementing formally verifiable smart contracts.

## Getting Started

To engage Certora for security audits:

1. **Initial Contact**: Reach out to Certora at [nooly@certora.com](mailto:nooly@certora.com) or [moran@certora.com](mailto:moran@certora.com) to discuss your project.
2. **Scoping Process**: Define the audit scope, formal verification requirements, and timeline.
3. **Audit and Verification Process**: 
   - Formal specification development
   - Mathematical verification using the Certora Prover
   - Traditional security audit methodologies
   - Comprehensive vulnerability assessment
4. **Results Delivery**: Detailed report of findings, verification results, and remediation recommendations.
5. **Post-Audit Support**: Assistance with implementing fixes and re-verification as needed.

## Documentation

For detailed information about Certora's formal verification approach and security services, visit their [website](https://docs.certora.com/en/latest/).

## Use Cases

Certora's services are particularly valuable for:

- **High-Value DeFi Protocols**: Mathematical verification of critical financial properties.
- **Complex Smart Contract Systems**: Formal verification of intricate contract interactions.
- **Novel Financial Mechanisms**: Validation of innovative DeFi mechanisms and algorithms.
- **Protocol Implementations**: Verification of protocol specification compliance.
- **Security-Critical Applications**: Projects where security failures would have significant consequences.

## Conclusion

Certora provides a unique combination of formal verification and traditional security auditing, offering one of the highest levels of security assurance available for smart contracts. Their approach is particularly valuable for projects with complex logic or high-value applications where mathematical certainty about critical properties is desired. Highly recommended by security teams in the ecosystem, Certora delivers sophisticated security analysis that can identify subtle vulnerabilities missed by conventional auditing approaches. 

# Chainlink CCIP (/integrations/chainlink-ccip)

---
title: Chainlink CCIP
category: Crosschain Solutions
available: ["C-Chain"]
description: "Chainlink CCIP (Cross-Chain Interoperability Protocol) enables secure cross-chain messaging and token transfers on Avalanche with built-in security features and DON support."
logo: /images/chainlink.png
developer: Chainlink
website: https://chain.link/cross-chain
documentation: https://docs.chain.link/ccip
---

## Overview

Chainlink CCIP (Cross-Chain Interoperability Protocol) is a secure interoperability protocol that enables cross-chain messaging and token transfers on Avalanche. Built by Chainlink, CCIP leverages decentralized oracle networks (DONs) to provide enhanced security features and reliable cross-chain communication capabilities.

## Features

- **Programmable Token Transfers**: Transfer tokens across chains with custom logic.
- **Cross-Chain Messages**: Send arbitrary messages between supported networks.
- **Risk Management**: Built-in risk management through circuit breakers.
- **DON Security**: Secured by decentralized oracle networks.
- **Anti-Fraud Network**: Additional security layer monitoring cross-chain transactions.
- **Native Token Transfers**: Support for native token movements across chains.
- **Developer Tools**: Comprehensive SDKs and testing environments.

## Getting Started

To integrate Chainlink CCIP:

1. **Access Documentation**: Review the [CCIP Documentation](https://docs.chain.link/ccip).
2. **Choose Integration**: 
   - Token transfers
   - Message passing
   - Combined transfers and messages
3. **Implement Protocol**: 
   - Install CCIP contracts
   - Configure for Avalanche
   - Test cross-chain operations
4. **Monitor Transfers**: Track messages and transfers through CCIP explorer.

## Documentation

For detailed technical documentation and integration guides, visit the [Chainlink CCIP Documentation](https://docs.chain.link/ccip).

## Use Cases

CCIP enables various cross-chain applications:

- **Token Bridges**: Build secure token transfer bridges.
- **Cross-Chain dApps**: Develop applications spanning multiple networks.
- **DeFi Protocols**: Create cross-chain DeFi applications.
- **Gaming**: Implement cross-chain gaming mechanics.
- **Governance**: Enable cross-chain governance systems.

## Conclusion

Chainlink CCIP provides a secure and reliable infrastructure for cross-chain operations on Avalanche's C-Chain. With its robust security features, including DON support and the Anti-Fraud Network, CCIP offers developers a trusted solution for building cross-chain applications. Whether implementing token transfers or complex cross-chain logic, CCIP delivers the security and functionality needed for reliable interoperability. 

# Chainlink Data Feeds (/integrations/chainlink-data-feeds)

---
title: Chainlink Data Feeds
category: Data Feeds
available: ["C-Chain"]
description: Chainlink Data Feeds are the quickest way to connect your smart contracts to the real-world data such as asset prices and reserve balances.
logo: /images/chainlink.png
developer: Chainlink Labs
website: https://chain.link/
documentation: https://chain.link/data-feeds
---

## Overview

Chainlink Data Feeds are the quickest way to connect your smart contracts to the real-world data such as asset prices and reserve balances.

If you already started a project and need to integrate Chainlink, you can [add Chainlink to your existing project](https://docs.chain.link/resources/create-a-chainlinked-project?parent=dataFeeds#installing-into-existing-projects) with the `@chainlink/contracts` NPM package.

## Data Feed Best Practices

Before you use Data Feeds, read and understand the best practices on the [Selecting Quality Data Feeds](https://docs.chain.link/data-feeds/selecting-data-feeds) page. For best practices about data for specific asset types, see the following sections:

- [Best Practices for ETF and Forex feeds](https://docs.chain.link/data-feeds/selecting-data-feeds#etf-and-forex-feeds)
- [Best Practices for Exchange Rate Feeds](https://docs.chain.link/data-feeds/selecting-data-feeds#exchange-rate-feeds)
- [Risk Categories](https://docs.chain.link/data-feeds/selecting-data-feeds#data-feed-categories)

## Types of data feeds
Data feeds provide many different types of data for your applications.

- [Price Feeds](https://docs.chain.link/data-feeds#price-feeds)
- [Proof of Reserve Feeds](https://docs.chain.link/data-feeds#proof-of-reserve-feeds)
- [Rate and Volatility Feeds](https://docs.chain.link/data-feeds#rate-and-volatility-feeds)

## Using Data Feeds on the Avalanche Primary Network

To consume price data, your smart contract should reference `AggregatorV3Interface`, which defines the external functions implemented by Data Feeds.

```solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.7;

import {AggregatorV3Interface} from "@chainlink/contracts/src/v0.8/shared/interfaces/AggregatorV3Interface.sol";

/**
 * THIS IS AN EXAMPLE CONTRACT THAT USES HARDCODED
 * VALUES FOR CLARITY.
 * THIS IS AN EXAMPLE CONTRACT THAT USES UN-AUDITED CODE.
 * DO NOT USE THIS CODE IN PRODUCTION.
 */


contract DataConsumerV3 {
    AggregatorV3Interface internal dataFeed;

    /**
     * Network: Avalanche Primary Network
     * Aggregator: AVAX/USD
     * Address: 0x0A77230d17318075983913bC2145DB16C7366156
     */
    constructor() {
        dataFeed = AggregatorV3Interface(
            0x0A77230d17318075983913bC2145DB16C7366156
        );
    }

    /**
     * Returns the latest answer.
     */
    function getChainlinkDataFeedLatestAnswer() public view returns (int) {
        // prettier-ignore
        (
            /* uint80 roundID */,
            int answer,
            /*uint startedAt*/,
            /*uint timeStamp*/,
            /*uint80 answeredInRound*/
        ) = dataFeed.latestRoundData();
        return answer;
    }
}
```

### Primary Network Price Feed Addresses

| **Status** | **Pair**                   | **Contract Address**                            | **Asset Name**              | **Asset Type** | **Market Hours** |
|------------|----------------------------|-------------------------------------------------|-----------------------------|----------------|------------------|
| 🟢         | AAVE / USD                  | 0x3CA13391E9fb38a75330fb28f8cc2eB3D9ceceED      | Aave                        | Crypto         | Crypto           |
| 🔵         | AAVE Network Emergency Count (Avalanche) | 0x41185495Bc8297a65DC46f94001DC7233775EbEe | N/A                         | N/A            | N/A              |
| 🟢         | ADA / USD                   | 0x69C2703b8F1A85a2EF6aBDd085699a9F909BE053      | Cardano                     | Crypto         | Crypto           |
| 🟡         | ALPHA / USD                 | 0x7B0ca9A6D03FE0467A31Ca850f5bcA51e027B3aF      | Alpha Finance               | Crypto         | Crypto           |
| 🟢         | AVAX / USD                  | 0x0A77230d17318075983913bC2145DB16C7366156      | Avalanche                   | Crypto         | Crypto           |
| 🟡         | AXS / USD                   | 0x155835C5755205597d62703a5A0b37e57a26Ee5C      | Axie Infinity               | Crypto         | Crypto           |
| 🟡         | BAT / USD                   | 0xe89B3CE86D25599D1e615C0f6a353B4572FF868D      | Basic Attention Token       | Crypto         | Crypto           |
| 🟠         | BEAM / USD                  | 0x3427232b88Ce4e7d62A03289247eE0cA5324f6ba      | Beam                        | Crypto         | Crypto           |


### Primary Network Proof of Reserve Addresses

| **Status** | **Asset**                     | **Contract Address**                              | **Reserve Type** | **Data Source** | **Reporting/Auditor**    |
|------------|--------------------------------|---------------------------------------------------|-----------------|----------------|-------------------------|
| 🔵         | AAVE.e PoR                     | 0x14C4c668E34c09E1FBA823aD5DB47F60aeBDD4F7        | Cross-chain     | Cross-chain    | Wallet address          |
| 🔵         | BTC.b PoR                      | 0x99311B4bf6D8E3D3B4b9fbdD09a1B0F4Ad8e06E9        | Cross-chain     | Cross-chain    | Wallet address          |
| 🔵         | DAI.e PoR                      | 0x976D7fAc81A49FA71EF20694a3C56B9eFB93c30B        | Cross-chain     | Cross-chain    | Wallet address          |
| 🔵         | Ion Digital Total Reserve      | 0x121C188f76831f504bD29C753074B37a4177cEc3        | Off-chain       | Instruxi       | Third-party auditor      |
| 🔵         | LINK.e PoR                     | 0x943cEF1B112Ca9FD7EDaDC9A46477d3812a382b6        | Cross-chain     | Cross-chain    | Wallet address          |
| 🔵         | USDC.e PoR                     | 0x63769951E4cfDbDC653dD9BBde63D2Ce0746e5F2        | Cross-chain     | Cross-chain    | Wallet address          |
| 🔵         | USDT.e PoR                     | 0x94D8c2548018C27F1aa078A23C4158206bE1CC72        | Cross-chain     | Cross-chain    | Wallet address          |
| 🔵         | WBTC.e PoR                     | 0xebEfEAA58636DF9B20a4fAd78Fad8759e6A20e87        | Cross-chain     | Cross-chain    | Wallet address          |


### Primary Network Rate and Volatility Feed Addresses

| **Asset**                   | **Contract Address**                              |
|-----------------------------|---------------------------------------------------|
| BTC-USD 30-Day Realized Vol  | 0x93b9B82158846cefa8b4040f22A3Bff05c365226        |
| ETH-USD 30-Day Realized Vol  | 0x89983A2FDd082FA40d8062BCE3986Fc601D2d29B        |


# Chainlink (/integrations/chainlink-oracles)

---
title: Chainlink
category: Oracles
available: ["C-Chain"]
description: "Chainlink is a decentralized oracle network that enables smart contracts to securely interact with real-world data."
logo: /images/chainlink.png
developer: Chainlink Labs
website: https://chain.link/
documentation: https://docs.chain.link/
---

## Overview

Chainlink is a decentralized oracle network that provides reliable, tamper-proof inputs and outputs for complex smart contracts on any blockchain. By connecting smart contracts with real-world data, events, and payments, Chainlink enables the development of advanced decentralized applications (dApps) across various industries. Its network of decentralized oracles allows smart contracts to securely interact with off-chain data, enhancing their functionality and scope.

## Features

- **Decentralized Oracles**: Chainlink uses a network of decentralized oracles to fetch and deliver reliable, tamper-resistant data to smart contracts.
- **Cross-Chain Interoperability**: Chainlink facilitates secure data exchange between different blockchains, enabling cross-chain smart contract functionality.
- **Data Integrity**: Chainlink ensures high data integrity by using multiple oracles and data sources, preventing single points of failure.
- **Verifiable Randomness**: Chainlink VRF (Verifiable Random Function) provides provably fair and tamper-proof randomness to smart contracts, essential for gaming, lotteries, and NFT minting.
- **Price Feeds**: Chainlink's widely used price feeds provide decentralized financial applications with accurate and reliable price data, supporting DeFi protocols like lending, borrowing, and stablecoins.

## Getting Started

To start using Chainlink, follow these steps:

1. **Visit Chainlink**: Explore the [Chainlink website](https://chain.link/) to understand its offerings and network capabilities.
2. **Set Up an Oracle**: Refer to the [documentation](https://docs.chain.link/docs/running-a-chainlink-node) to set up your own Chainlink node and participate in the decentralized oracle network.
3. **Integrate Price Feeds**: Use Chainlink's [Price Feeds](https://docs.chain.link/docs/get-the-latest-price) to integrate reliable price data into your DeFi application.
4. **Leverage Chainlink VRF**: Integrate [Chainlink VRF](https://docs.chain.link/docs/chainlink-vrf) for provably fair randomness in your smart contracts.
5. **Explore Cross-Chain Solutions**: Utilize Chainlink's [Cross-Chain Interoperability Protocol (CCIP)](https://docs.chain.link/ccip) for secure cross-chain data transfer and smart contract execution.

## Documentation

For in-depth guides, API references, and integration tutorials, visit the [Chainlink Documentation](https://docs.chain.link/).

## Use Cases

Chainlink is widely applicable in various blockchain scenarios:

- **DeFi Protocols**: Integrate secure and reliable price feeds to support lending, borrowing, and other financial activities.
- **Gaming and NFTs**: Use Chainlink VRF for fair randomness in gaming outcomes, lotteries, and NFT minting.
- **Insurance dApps**: Fetch real-world data like weather conditions or market prices to trigger automated insurance payouts.
- **Cross-Chain Applications**: Enable cross-chain data transfer and smart contract execution using Chainlink's CCIP.

## Conclusion

Chainlink is a crucial infrastructure for decentralized applications, offering a robust and secure way to connect smart contracts with real-world data. Whether you're developing a DeFi protocol, a gaming platform, or any other blockchain-based solution, Chainlink provides the tools and services needed to enhance your dApp's functionality and trustworthiness.


# Chainlink VRF (/integrations/chainlink-vrf)

---
title: Chainlink VRF
category: VRF
available: ["C-Chain", "All EVM L1s"]
description: Chainlink VRF (Verifiable Random Function) is a provably fair and verifiable random number generator (RNG) that enables smart contracts to access random values without compromising security or usability. 
logo: /images/chainlink.png
developer: Chainlink Labs
website: https://chain.link/vrf
documentation: https://docs.chain.link/vrf
---

## Overview

Chainlink VRF (Verifiable Random Function) is a provably fair and verifiable random number generator (RNG) that enables smart contracts to access random values without compromising security or usability. For each request, Chainlink VRF generates one or more random values and cryptographic proof of how those values were determined. The proof is published and verified onchain before any consuming applications can use it. This process ensures that results cannot be tampered with or manipulated by any single entity including oracle operators, miners, users, or smart contract developers.

Use Chainlink VRF to build reliable smart contracts for any applications that rely on unpredictable outcomes:

- Building blockchain games and NFTs.
- Random assignment of duties and resources. For example, randomly assigning judges to cases.
- Choosing a representative sample for consensus mechanisms.

### Two methods to request randomness
- **Subscription:** Create a subscription account and fund its balance with either native tokens or LINK. You can then connect multiple consuming contracts to the subscription account. When the consuming contracts request randomness, the transaction costs are calculated after the randomness requests are fulfilled and the subscription balance is deducted accordingly. This method allows you to fund requests for multiple consumer contracts from a single subscription.
- **Direct funding:** Consuming contracts directly pay with either native tokens or LINK when they request random values. You must directly fund your consumer contracts and ensure that there are enough funds to pay for randomness requests.

### Use Chainlink VRF on the Avalanche Primary Network

To use Chainlink VRF on the Avalanche Primary Network using **subscription**, utilize the [following information from Chainlink](https://docs.chain.link/vrf/v2-5/supported-networks#avalanche-mainnet):

| **Item**                               | **Value**                                                                                  |
|----------------------------------------|--------------------------------------------------------------------------------------------|
| **LINK Token**                          | 0x5947BB275c521040051D82396192181b413227A3                                                 |
| **VRF Coordinator**                    | 0xE40895D055bccd2053dD0638C9695E326152b1A4                                                 |
| **200 gwei Key Hash**                   | 0xea7f56be19583eeb8255aa79f16d8bd8a64cedf68e42fefee1c9ac5372b1a102                         |
| **500 gwei Key Hash**                   | 0x84213dcadf1f89e4097eb654e3f284d7d5d5bda2bd4748d8b7fada5b3a6eaa0d                         |
| **1000 gwei Key Hash**                  | 0xe227ebd10a873dde8e58841197a07b410038e405f1180bd117be6f6557fa491c                         |
| **Premium percentage (paying with AVAX)**| 60                                                                                         |
| **Premium percentage (paying with LINK)**| 50                                                                                         |
| **Max Gas Limit**                        | 2,500,000                                                                                  |
| **Minimum Confirmations**               | 0                                                                                          |
| **Maximum Confirmations**               | 200                                                                                        |
| **Maximum Random Values**               | 500                                                                                        |


### Use Chainlink VRF on an Avalanche L1

This repository provides **example** contracts for how an Avalanche L1 could leverage Chainlink VRF functionality (available on the C-Chain) using Teleporter. This allows newly launched L1s to immediately utilize VRF without any trusted intermediaries or third-party integration requirements.

[Avalanche L1 VRF Example Contracts](https://github.com/ava-labs/subnet-vrf-contracts)

### Best Practices

These are example best practices for using Chainlink VRF. To explore more applications of VRF, refer to [Chainlink's blog](https://blog.chain.link/).

**Getting a random number within a range**

If you need to generate a random number within a given range, use modulo to define the limits of your range. Below you can see how to get a random number in a range from 1 to 50.

```solidity
function fulfillRandomWords(
  uint256, /* requestId */
  uint256[] memory randomWords
) internal override {
  // Assuming only one random word was requested.
  s_randomRange = (randomWords[0] % 50) + 1;
}
```

**Getting multiple random values**

If you want to get multiple random values from a single VRF request, you can request this directly with the `numWords` argument:

- If you are using the VRF v2.5 subscription method, see the full example code for an example where one request returns multiple random values.

**Processing simultaneous VRF requests**

If you want to have multiple VRF requests processing simultaneously, create a mapping between `requestId` and the response. You might also create a mapping between the `requestId` and the address of the requester to track which address made each request.

```solidity
mapping(uint256 => uint256[]) public s_requestIdToRandomWords;
mapping(uint256 => address) public s_requestIdToAddress;
uint256 public s_requestId;

function requestRandomWords() external onlyOwner returns (uint256) {
  uint256 requestId = s_vrfCoordinator.requestRandomWords(
      VRFV2PlusClient.RandomWordsRequest({
          keyHash: keyHash,
          subId: s_vrfSubscriptionId,
          requestConfirmations: requestConfirmations,
          callbackGasLimit: callbackGasLimit,
          numWords: numWords,
          extraArgs: VRFV2PlusClient._argsToBytes(VRFV2PlusClient.ExtraArgsV1({nativePayment: true})) // new parameter
      })
  );
  s_requestIdToAddress[requestId] = msg.sender;

  // Store the latest requestId for this example.
  s_requestId = requestId;

  // Return the requestId to the requester.
  return requestId;
}

function fulfillRandomWords(
    uint256 requestId,
    uint256[] memory randomWords
  ) internal override {
  // You can return the value to the requester,
  // but this example simply stores it.
  s_requestIdToRandomWords[requestId] = randomWords;
}
```
You could also map the `requestId` to an index to keep track of the order in which a request was made.

**Processing VRF responses through different execution paths**

If you want to process VRF responses depending on predetermined conditions, you can create an `enum`. When requesting for randomness, map each `requestId` to an enum. This way, you can handle different execution paths in `fulfillRandomWords`. See the following example:

```solidity
// SPDX-License-Identifier: MIT
// An example of a consumer contract that relies on a subscription for funding.
// It shows how to setup multiple execution paths for handling a response.
pragma solidity 0.8.19;

import {LinkTokenInterface} from "@chainlink/contracts/src/v0.8/shared/interfaces/LinkTokenInterface.sol";
import {IVRFCoordinatorV2Plus} from "@chainlink/contracts/src/v0.8/vrf/dev/interfaces/IVRFCoordinatorV2Plus.sol";
import {VRFConsumerBaseV2Plus} from "@chainlink/contracts/src/v0.8/vrf/dev/VRFConsumerBaseV2Plus.sol";
import {VRFV2PlusClient} from "@chainlink/contracts/src/v0.8/vrf/dev/libraries/VRFV2PlusClient.sol";

/**
 * THIS IS AN EXAMPLE CONTRACT THAT USES HARDCODED VALUES FOR CLARITY.
 * THIS IS AN EXAMPLE CONTRACT THAT USES UN-AUDITED CODE.
 * DO NOT USE THIS CODE IN PRODUCTION.
 */

contract VRFv2MultiplePaths is VRFConsumerBaseV2Plus {

    // Your subscription ID.
    uint256 s_subscriptionId;

    // Avalanche Primary Network coordinator.
    address vrfCoordinatorV2Plus = 0xE40895D055bccd2053dD0638C9695E326152b1A4;

    // The gas lane to use, which specifies the maximum gas price to bump to.
    // For a list of available gas lanes on each network,
    // see https://docs.chain.link/vrf/v2-5/supported-networks
    bytes32 keyHash =
        0x787d74caea10b2b357790d5b5247c2f63d1d91572a9846f780606e4d953677ae;

    uint32 callbackGasLimit = 100000;

    // The default is 3, but you can set this higher.
    uint16 requestConfirmations = 3;

    // For this example, retrieve 1 random value in one request.
    // Cannot exceed VRFCoordinatorV2_5.MAX_NUM_WORDS.
    uint32 numWords = 1;

    enum Variable {
        A,
        B,
        C
    }

    uint256 public variableA;
    uint256 public variableB;
    uint256 public variableC;

    mapping(uint256 => Variable) public requests;

    // events
    event FulfilledA(uint256 requestId, uint256 value);
    event FulfilledB(uint256 requestId, uint256 value);
    event FulfilledC(uint256 requestId, uint256 value);

    constructor(uint256 subscriptionId) VRFConsumerBaseV2Plus(vrfCoordinatorV2Plus) {
        s_vrfCoordinator = IVRFCoordinatorV2Plus(vrfCoordinatorV2Plus);
        s_subscriptionId = subscriptionId;
    }

    function updateVariable(uint256 input) public {
      uint256 requestId = s_vrfCoordinator.requestRandomWords(VRFV2PlusClient.RandomWordsRequest({
            keyHash: keyHash,
            subId: s_subscriptionId,
            requestConfirmations: requestConfirmations,
            callbackGasLimit: callbackGasLimit,
            numWords: numWords,
            extraArgs: VRFV2PlusClient._argsToBytes(VRFV2PlusClient.ExtraArgsV1({nativePayment: true}))
          })
        );

        if (input % 2 == 0) {
            requests[requestId] = Variable.A;
        } else if (input % 3 == 0) {
            requests[requestId] = Variable.B;
        } else {
            requests[requestId] = Variable.C;
        }
    }

    function fulfillRandomWords(
        uint256 requestId,
        uint256[] memory randomWords
    ) internal override {
        Variable variable = requests[requestId];
        if (variable == Variable.A) {
            fulfillA(requestId, randomWords[0]);
        } else if (variable == Variable.B) {
            fulfillB(requestId, randomWords[0]);
        } else if (variable == Variable.C) {
            fulfillC(requestId, randomWords[0]);
        }
    }

    function fulfillA(uint256 requestId, uint256 randomWord) private {
        // execution path A
        variableA = randomWord;
        emit FulfilledA(requestId, randomWord);
    }

    function fulfillB(uint256 requestId, uint256 randomWord) private {
        // execution path B
        variableB = randomWord;
        emit FulfilledB(requestId, randomWord);
    }

    function fulfillC(uint256 requestId, uint256 randomWord) private {
        // execution path C
        variableC = randomWord;
        emit FulfilledC(requestId, randomWord);
    }
}
```


# Chainstack (/integrations/chainstack)

---
title: Chainstack
category: Indexers
available: ["C-Chain"]
description: Chainstack is a multi-cloud, multi-protocol blockchain Platform as a Service (PaaS) that enables developers to deploy, manage, and scale nodes and networks across multiple cloud providers.
logo: /images/chainstack.webp
developer: Chainstack
website: https://chainstack.com/
documentation: https://docs.chainstack.com/
---

## Overview

Chainstack is a powerful blockchain Platform as a Service (PaaS) designed to simplify the deployment, management, and scaling of blockchain nodes and networks. With support for multiple cloud providers and protocols, Chainstack allows developers to build and manage blockchain infrastructures with ease, ensuring high performance, reliability, and security. Whether you're running a private network, a public blockchain node, or deploying a decentralized application, Chainstack offers the tools and infrastructure needed to succeed.

## Features

- **Multi-Cloud Support**: Deploy nodes across various cloud providers, including AWS, Google Cloud, Microsoft Azure, and more, ensuring flexibility and redundancy.
- **Multi-Protocol Compatibility**: Chainstack supports multiple blockchain protocols, including Ethereum, Hyperledger Fabric, Corda, and more, allowing you to work with the technology of your choice.
- **Scalability**: Easily scale your blockchain infrastructure to meet the demands of your applications, whether it's for development, testing, or production environments.
- **Simplified Node Management**: Use Chainstack's intuitive dashboard to manage your nodes and networks, monitor performance, and perform updates with minimal effort.
- **High Availability**: Ensure your blockchain applications remain online and performant with Chainstack's robust infrastructure and automated failover mechanisms.

## Getting Started

To begin using Chainstack, follow these steps:

1. **Create an Account**: Sign up on the [Chainstack website](https://chainstack.com/) to access the platform.
2. **Deploy a Node**: Use the Chainstack dashboard to deploy your first blockchain node. Choose your preferred protocol and cloud provider.
3. **Manage Your Infrastructure**: Utilize Chainstack’s tools to monitor, manage, and scale your nodes as needed. Take advantage of multi-cloud deployments for increased reliability.
4. **Integrate with dApps**: Connect your deployed nodes to your decentralized applications or blockchain projects, ensuring seamless interaction with the blockchain.
5. **Explore Advanced Features**: Dive into Chainstack’s advanced features like API access, node telemetry, and analytics to optimize your blockchain infrastructure.

## Documentation

For detailed setup guides, API references, and integration instructions, visit the [Chainstack Documentation](https://docs.chainstack.com/).

## Use Cases

Chainstack is ideal for various blockchain projects and applications:

- **Enterprise Blockchain Networks**: Deploy and manage private or consortium blockchain networks with ease, ensuring enterprise-grade security and performance.
- **Decentralized Applications (dApps)**: Run scalable and reliable nodes to support your dApps on public blockchains like Ethereum.
- **Blockchain Development and Testing**: Use Chainstack’s infrastructure to develop and test your blockchain applications in a controlled environment before deploying to production.
- **Multi-Cloud Deployments**: Ensure high availability and redundancy by deploying your blockchain infrastructure across multiple cloud providers.

## Conclusion

Chainstack provides a comprehensive and flexible platform for deploying and managing blockchain infrastructure, making it an essential tool for developers and enterprises alike. With its multi-cloud, multi-protocol support and ease of use, Chainstack enables you to build, scale, and maintain blockchain networks with confidence and efficiency.



# Chronicle (/integrations/chronicle-data-feeds)

---
title: Chronicle
category: Oracles
available: ["C-Chain"]
description: Chronicle Oracles enable you to access verifiable data onchain.
logo: /images/chronicle.png
developer: Chronicle Labs
website: https://chroniclelabs.org/
documentation: https://docs.chroniclelabs.org/
---

## Overview
[Chronicle Protocol](https://chroniclelabs.org/) is a novel Oracle solution that overcomes the current limitations of transferring data onchain by developing scalable, cost-efficient, decentralized, and verifiable Oracles.
For the data feeds addresses, please check out the [Chronicle Dashboard](https://chroniclelabs.org/dashboard) under **Oracles** section. Select either **Mainnets** or **Testnets**, then **Avalanche C-Chain Oracles**.

### Data Feeds Types
Chronicle provides two categories of Oracles: [DeFi Oracles](https://docs.chroniclelabs.org/Products/DeFiOracle/) and [Verified Asset Oracles (VAO)](https://docs.chroniclelabs.org/Products/DeFiOracle/).

DeFi Oracles include:
- Cryptocurrency Oracles
- Fiat Currency Oracles
- Yield Rate Oracles

[The Verified Asset Oracle (VAO)](https://docs.chroniclelabs.org/Products/VerifiedAssetOracle/) — formerly known as the RWA Oracle — securely and transparently verifies the integrity and quality of any offchain asset, transports the resulting data onchain, and makes it directly available to smart contracts and onchain products.

### Check the Chronicle Oracles on the Chronicle Dashboard

- [Avalanche C-Chain Oracles](https://chroniclelabs.org/dashboard/oracles#blockchain=AVAX)
- [Avalanche Fuji Testnet Oracles](https://chroniclelabs.org/dashboard/oracles#testnet=true&blockchain=FUJI)

## Using Chronicle DeFi Oracles on Avalanche Fuji Testnet

The following example showcases how to integrate the AVAX/USD oracle on Avalanche Fuji Testnet.

Chronicle contracts are read-protected by a whitelist, meaning you won't be able to read them onchain without your address being added to the whitelist. 
On the Testnet networks, users can add themselves to the whitelist through the SelfKisser contract; a process playfully referred to as "kissing" themselves. 
**To get access to production Oracles on the Mainnet, please open a support ticket in [Discord](https://discord.com/invite/CjgvJ9EspJ) in the 🆘 ｜ support channel.**

For oracle addresses, please check out the [Dashboard](https://chroniclelabs.org/dashboard/oracles).

```solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.16;

/**
 * @title OracleReader
 * @notice A simple contract to read from Chronicle oracles
 * @dev To see the full repository, visit https://github.com/chronicleprotocol/OracleReader-Example.
 * @dev Addresses in this contract are hardcoded for Avalanche Fuji Testnet.
 * For other supported networks, check the https://chroniclelabs.org/dashboard/oracles.
 */
contract OracleReader {
    /**
    * @notice The Chronicle oracle to read from.
    * Chronicle_AVAX_USD - 0x8b3328b27436263e0BfE7597a0D97B1BEE9cC576
    * Network: Avalanche Fuji Testnet
    */

    IChronicle public chronicle = IChronicle(address(0x8b3328b27436263e0BfE7597a0D97B1BEE9cC576));

    /**
    * @notice The SelfKisser granting access to Chronicle oracles.
    * SelfKisser_1:0x371A53bB4203Ad5D7e60e220BaC1876FF3Ddda5B
    * Network: Avalanche Fuji Testnet
    */
    ISelfKisser public selfKisser = ISelfKisser(address(0x371A53bB4203Ad5D7e60e220BaC1876FF3Ddda5B));

    constructor() {
        // Note to add address(this) to chronicle oracle's whitelist.
        // This allows the contract to read from the chronicle oracle.
        selfKisser.selfKiss(address(chronicle));
    }

    /**
    * @notice Function to read the latest data from the Chronicle oracle.
    * @return val The current value returned by the oracle.
    * @return age The timestamp of the last update from the oracle.
    */
    function read() external view returns (uint256 val, uint256 age) {
        (val, age) = chronicle.readWithAge();
    }
}

// Copied from [chronicle-std](https://github.com/chronicleprotocol/chronicle-std/blob/main/src/IChronicle.sol).
interface IChronicle {
    /**
    * @notice Returns the oracle's current value.
    * @dev Reverts if no value set.
    * @return value The oracle's current value.
    */
    function read() external view returns (uint256 value);

    /**
    * @notice Returns the oracle's current value and its age.
    * @dev Reverts if no value set.
    * @return value The oracle's current value using 18 decimals places.
    * @return age The value's age as a Unix Timestamp .
    * */
    function readWithAge() external view returns (uint256 value, uint256 age);
}

// Copied from [self-kisser](https://github.com/chronicleprotocol/self-kisser/blob/main/src/ISelfKisser.sol).
interface ISelfKisser {
    /// @notice Kisses caller on oracle `oracle`.
    function selfKiss(address oracle) external;
}
```

## Documentation Link
For more examples, check out the [Chronicle Documentation](https://docs.chroniclelabs.org/Developers/tutorials/Remix).

# CoinGecko (/integrations/coingecko)

---
title: CoinGecko
category: Token Aggregators
available: ["C-Chain", "All EVM L1s"]
description: "CoinGecko provides comprehensive cryptocurrency data including prices, trading volume, market cap, and detailed analytics for tokens on Avalanche."
logo: /images/coingecko.png
developer: CoinGecko
website: https://www.coingecko.com/
documentation: https://www.coingecko.com/api/documentation
---

## Overview

CoinGecko is a leading cryptocurrency data aggregator that provides comprehensive market data for the Avalanche ecosystem. It offers detailed information about tokens, exchanges, and DeFi protocols, including price data, trading volumes, market capitalization, and various other metrics that help users make informed decisions.

## Features

- **Market Data**: Real-time price tracking, market cap, and volume data for Avalanche tokens.
- **Developer Tools**: Robust API access with extensive endpoints for market data integration.
- **Token Info**: Detailed information about tokens including team, technology, and community metrics.
- **Exchange Data**: Comprehensive trading pair information across centralized and decentralized exchanges.
- **DeFi Insights**: Tracking of DeFi protocols, TVL, and yield opportunities on Avalanche.
- **Portfolio Tracking**: Tools for monitoring and analyzing cryptocurrency holdings.
- **Historical Data**: Access to historical price and market data for analysis.

## Getting Started

To utilize CoinGecko's services:

1. **Visit Platform**: Access [CoinGecko](https://www.coingecko.com/).
2. **Explore Avalanche**: Navigate to Avalanche ecosystem tokens and markets.
3. **Track Assets**: 
   - Search for specific tokens
   - Monitor market metrics
   - Create watchlists
4. **API Integration**: For developers, integrate CoinGecko data using their API.

## Documentation

For detailed API documentation and integration guides, visit the [CoinGecko API Documentation](https://www.coingecko.com/api/documentation).

## Use Cases

CoinGecko serves various market data needs:

- **Market Analysis**: Track token prices and market trends on Avalanche.
- **Development**: Integrate reliable price feeds and market data into dApps.
- **Portfolio Tracking**: Monitor investment performance across multiple tokens.
- **Research**: Access detailed token information and historical data.
- **DeFi Integration**: Build applications with comprehensive market data support.

## Conclusion

CoinGecko provides essential market data infrastructure for the Avalanche ecosystem, offering reliable and comprehensive information crucial for users, developers, and analysts. Its combination of detailed token metrics, market data, and developer tools makes it an invaluable resource for anyone operating in the Avalanche marketplace. 

# CoinMarketCap (/integrations/coinmarketcap)

---
title: CoinMarketCap
category: Token Aggregators
available: ["C-Chain", "All EVM L1s"]
description: "CoinMarketCap is a leading cryptocurrency data platform providing comprehensive market data, analytics, and insights for Avalanche ecosystem tokens."
logo: /images/coinmarketcap.jpeg
developer: CoinMarketCap
website: https://coinmarketcap.com/
documentation: https://coinmarketcap.com/api/documentation/v1/
---

## Overview

CoinMarketCap is one of the most referenced price-tracking websites for crypto assets, providing comprehensive data for the Avalanche ecosystem. It offers real-time market data, detailed analytics, and various tools for tracking cryptocurrency markets, with extensive coverage of tokens and projects building on Avalanche.

## Features

- **Market Data**: Real-time price tracking, market cap rankings, and trading volume analytics.
- **Exchange Data**: Comprehensive information about trading pairs and exchange volumes.
- **On-Chain Metrics**: Integration with blockchain data for enhanced analytics.
- **Professional API**: Enterprise-grade API access for market data integration.
- **Token Information**: Detailed profiles of cryptocurrencies including team info, events, and announcements.
- **Market Analysis**: Tools for technical analysis and market trends.
- **Educational Content**: Resources for understanding crypto markets and technologies.

## Getting Started

To begin using CoinMarketCap:

1. **Access Platform**: Visit [CoinMarketCap](https://coinmarketcap.com/).
2. **Explore Avalanche**: Navigate to Avalanche ecosystem tokens and markets.
3. **Track Assets**: 
   - Search for specific tokens
   - Create watchlists
   - Monitor market metrics
4. **API Integration**: For developers, integrate market data using their professional API.

## Documentation

For comprehensive API documentation and integration guides, visit the [CoinMarketCap API Documentation](https://coinmarketcap.com/api/documentation/v1/).

## Use Cases

CoinMarketCap serves various market intelligence needs:

- **Market Research**: Access comprehensive market data and analytics.
- **Development**: Integrate reliable price and market data into applications.
- **Investment Analysis**: Track market trends and token performance.
- **Due Diligence**: Research detailed token and project information.
- **Market Monitoring**: Real-time tracking of market movements and trends.

## Conclusion

CoinMarketCap provides essential market intelligence and data services for the Avalanche ecosystem. With its comprehensive coverage, professional-grade API, and extensive market analytics, it serves as a crucial resource for users, developers, and institutions operating in the Avalanche marketplace. Whether for market research, development, or investment analysis, CoinMarketCap delivers reliable and detailed information for informed decision-making. 

# Colossus Digital (/integrations/colossus)

---
title: Colossus Digital
category: Enterprise Solutions
available: ["C-Chain", "P-Chain"]
description: The Colossus Institutional Hub is a unified platform for institutional staking, governance, and custody workflows across multiple chains and custody providers.
logo: /images/colossus.png
developer: Colossus Digital
website: https://colossus.digital/
documentation: https://docs.colossus.life/
---

## Overview

Colossus Institutional Hub is a comprehensive platform designed to simplify staking, governance, and custody operations for institutions across PoS networks. Built with security, compliance, and scalability in mind, it enables seamless interaction between clients, custodians and validators through a unified API and UI interface. Whether using third-party custody platforms like Fireblocks, Ledger Enterprise, DFNS or HSMs, Colossus ensures secure, policy-governed transaction orchestration at scale.

## Features

- **Unified API & UI**: A single interface for staking, governance, and delegation across all major L1 networks and custody solutions.
- **Multi-Chain Support**: Stake and manage assets across Avax C-Chain and P-Chain, and more.
- **Custodian Agnostic**: Integrates with Fireblocks, Ledger Enterprise, DFNS, and other self-managed custody setups.
- **Secure Transaction Crafting**: Colossus Multi-party crafting and governance-driven approval using quorum-based threshold-initiation.
- **Transaction Lens & Decoder**: Institutional-grade transaction preview and validation tools to ensure compliant transaction generation.
- **Governance Workflows**: Define approval policies, quorum thresholds, and audit trails for every transaction.
- **Auditing & Reporting**: Real-time reporting for compliance, treasury tracking, and validator operations.

## Getting Started

To begin using the Colossus Institutional Hub:

1. **Visit the Website**: Learn more about Colossus and the Institutional Hub at [colossus.digital](https://colossus.digital/).
2. **Explore the Docs**: Review the [Colossus Developer Docs](https://docs.colossus.life/) to understand how to integrate.
3. **Connect a Custody Provider**: Link your Fireblocks, DFNS, or Ledger Enterprise setup to begin delegation.
4. **Configure Policies**: Define your governance approval rules, transaction initation quorum, and transaction controls.
5. **Start Staking**: Delegate assets to validators across supported networks with full custody security.

## Documentation

For full integration guides, transaction workflows samples, and API references, explore the [Colossus Documentation Portal](https://docs.colossus.life/).

## Use Cases

Colossus Institutional Hub is ideal for:

- **Exchanges**: Offer staking-as-a-service without taking custody risk.
- **Custodians**: Enable delegation and governance services directly from MPC or HSM-based vaults.
- **Funds and Treasuries**: Manage validator positions and governance votes with enterprise controls.
- **Staking Providers**: Connect to a two-sided marketplace to source institutional delegations.

## Conclusion

The Colossus Institutional Hub enables institutions to securely stake and govern assets at scale with full compliance and custody controls. It removes the complexity of managing staking across chains, validators, and wallet providers by unifying everything under a secure, policy-driven architecture. Whether you're an institutional investor, exchange, custodian, or validator, Colossus offers the tools you need to scale digital asset operations securely and efficiently.


# Core (/integrations/core)

---
title: Core
category: Wallet SDKs
available: ["C-Chain", "All EVM L1s"]
description: "Core is the native wallet SDK for the Avalanche blockchain."
logo: /images/core.svg
developer: Ava Labs
website: https://core.app/en/
documentation: https://docs.core.app/
featured: true
---

## Overview

Core is the native wallet SDK developed by Ava Labs specifically for the Avalanche blockchain. It provides developers with the tools needed to integrate wallet functionalities into decentralized applications (dApps) built on Avalanche. With Core, you can create seamless and secure user experiences, enabling users to manage their assets, interact with smart contracts, and perform transactions directly within your application.

## Features

- **Avalanche-Native**: Core is designed specifically for the Avalanche ecosystem, ensuring optimal compatibility and performance with the network.
- **Comprehensive Wallet Functions**: Core enables a wide range of wallet functionalities, including asset management, transaction signing, and interaction with Avalanche's L1s and smart contracts.
- **User-Friendly Interface**: Core is built to provide a smooth user experience, making it easy for users to navigate and manage their assets.
- **Security**: Core incorporates robust security measures to protect users' private keys and assets, adhering to the best practices in wallet development.
- **Cross-Platform Support**: Core SDK is available for integration across various platforms, including web, mobile, and desktop applications.

## Getting Started

To start using Core in your application, follow these steps:

1. **Visit the Core Website**: Explore the [Core website](https://core.app/en/) to learn more about its features and capabilities.
2. **Access the SDK**: Go to the [Core Documentation](https://docs.core.app/) to download the SDK and access integration guides.
3. **Integrate Wallet Functions**: Follow the integration tutorials in the documentation to add wallet functionalities such as asset management, transaction signing, and smart contract interaction to your dApp.
4. **Test and Deploy**: Test the integrated wallet features in a development environment before deploying your application on the Avalanche mainnet.

## Documentation

For detailed guides, API references, and integration examples, visit the [Core Documentation](https://docs.core.app/).

## Use Cases

Core can be utilized in a variety of applications within the Avalanche ecosystem:

- **DeFi Applications**: Enable users to manage their assets, stake tokens, and interact with DeFi protocols on Avalanche.
- **NFT Marketplaces**: Integrate wallet functionalities that allow users to buy, sell, and manage NFTs on the Avalanche network.
- **Gaming dApps**: Allow players to securely manage in-game assets, purchase items, and participate in the game economy using the Core wallet.
- **General dApps**: Any decentralized application built on Avalanche can integrate Core to offer users a native wallet experience for asset management and transactions.

## Conclusion

Core is a powerful and versatile wallet SDK designed for the Avalanche blockchain, providing developers with the tools needed to create seamless, secure, and user-friendly experiences. Whether you're building a DeFi platform, an NFT marketplace, or any other type of dApp on Avalanche, Core offers the essential wallet functionalities to help your application succeed.



# Crossmint (/integrations/crossmint)

---
title: Crossmint
category: Enterprise Solutions
available: ["C-Chain"]
description: Crossmint is an enterprise blockchain platform providing APIs for seamless on-chain applications, supporting wallets, NFT minting, verifiable credentials, and NFT checkout with multiple payment methods.
logo: /images/crossmint.jpeg
developer: Crossmint
website: https://crossmint.com/
documentation: https://docs.crossmint.com/
---

## Overview

Crossmint is an enterprise-grade blockchain platform trusted by over 30,000 enterprises and developers. It provides all the tools and infrastructure needed to build and deploy on-chain applications quickly and efficiently. With a comprehensive set of APIs, Crossmint enables wallet creation, NFT minting, credential management, and seamless checkout processes for NFTs.

## Features

- **Wallets**: Create embedded wallets with secure enterprise-grade Multi-Party Computation (MPC). These wallets are embeddable into your website and fully interoperable.
- **NFT Minting**: Mint, distribute, edit, and burn NFTs with ease. Airdrop NFTs directly into wallets or via email using simple API calls, no-code tools, QR codes, or NFC chips.
- **Verifiable Credentials**: Issue and manage verifiable credentials at scale, ensuring anyone can easily verify them on-chain.
- **NFT Checkout**: Sell NFTs using any payment method, including credit cards, Apple Pay, Google Pay, and cross-chain tokens.

## Getting Started

To start using Crossmint, follow these steps:

1. **Sign Up**: Visit [Crossmint](https://crossmint.com/) and create an account.
2. **Set Up Your Project**: Set up wallets, NFT minting tools, and verifiable credentials for your project in the Crossmint dashboard.
3. **Get API Key**: Obtain your API key to authenticate requests and integrate Crossmint's services into your application.
4. **Integration**: Use Crossmint's APIs or no-code tools to enable wallets, NFT checkout, and credential management in your app or website.

## Documentation

For detailed setup instructions, API references, and more, visit the [Crossmint Documentation](https://docs.crossmint.com/).

## Use Cases

Crossmint is ideal for:

- **NFT Marketplaces**: Easily mint, sell, and manage NFTs using multiple payment methods, including credit cards and cross-chain tokens.
- **Enterprises**: Manage and issue verifiable on-chain credentials at scale.
- **Developers**: Seamlessly integrate secure wallets, NFT minting, and checkout features into your applications.

## Conclusion

Crossmint simplifies blockchain development for enterprises and developers with its fully integrated suite of APIs. Whether you're looking to create NFTs, manage wallets, or sell NFTs with fiat payments, Crossmint provides all the infrastructure you need to build robust on-chain applications in minutes.

# Cubist (/integrations/cubist)

---
title: Cubist
category: Wallet SDKs
available: ["C-Chain", "All EVM L1s"]
description: Low-latency API for generating keys and signing transactions inside secure hardware.
logo: /images/cubist.svg
developer: Cubist
website: https://cubist.dev/
documentation: https://cubist.dev/ 
---

## Overview

Cubist is a high-performance wallet SDK that provides a low-latency API for generating cryptographic keys and signing blockchain transactions within secure hardware environments. Designed for developers who require enhanced security and efficiency, Cubist leverages hardware security modules (HSMs) and secure enclaves to protect private keys and ensure that sensitive operations are performed within a trusted execution environment. This makes Cubist an ideal solution for building secure decentralized applications (dApps) and blockchain platforms.

## Features

- **Hardware Security**: Cubist ensures that all key generation and transaction signing are performed within secure hardware, such as HSMs or secure enclaves, providing robust protection against attacks.
- **Low-Latency API**: The API is optimized for speed, offering low-latency interactions with secure hardware, which is crucial for performance-sensitive applications.
- **Flexible Integration**: Cubist supports multiple blockchain networks and can be integrated into various platforms, including web, mobile, and desktop applications.
- **Scalability**: Designed to handle high transaction volumes, Cubist is suitable for applications that require both security and scalability.
- **Compliance**: The use of secure hardware ensures that your application meets stringent security and compliance requirements, making Cubist ideal for enterprise-grade solutions.

## Getting Started

To get started with Cubist, follow these steps:

1. **Visit the Cubist Website**: Explore the [Cubist website](https://cubist.dev/) to understand its offerings, architecture, access the SDK, and find the latest documentation.
2. **Integrate Secure Key Management**: Use the guides and documentation found on the Cubist website to integrate Cubist's key management and transaction signing capabilities into your application, ensuring all operations are conducted within secure hardware.
3. **Optimize for Performance**: Leverage Cubist's low-latency API to ensure your application maintains high performance, even when handling large volumes of transactions.
4. **Test and Deploy**: After integrating and testing the SDK in a development environment, deploy your application with confidence, knowing that it meets high-security standards.

## Documentation

For detailed guides, API references, and step-by-step integration tutorials, please visit the main [Cubist website](https://cubist.dev/) and navigate to their documentation section.

## Use Cases

Cubist can be utilized in a variety of applications that require secure key management and transaction signing:

- **Enterprise Blockchain Applications**: Protect sensitive operations in enterprise blockchain solutions by leveraging secure hardware for key management.
- **DeFi Platforms**: Enhance the security of decentralized finance (DeFi) applications by ensuring that all transaction signing occurs within a secure enclave.
- **Cryptocurrency Wallets**: Build secure cryptocurrency wallets that offer users peace of mind by protecting their private keys within hardware security modules.
- **Regulated Industries**: Meet regulatory requirements in industries such as finance and healthcare by integrating Cubist's secure transaction signing and key management.

## Conclusion

Cubist offers a robust and secure solution for developers looking to integrate low-latency, hardware-based key management and transaction signing into their applications. With its focus on security, performance, and scalability


# DeFi Llama (/integrations/defilama)

---
title: DeFi Llama
category: Token Aggregators
available: ["C-Chain", "All EVM L1s"]
description: "DeFi Llama is a transparent and open-source DeFi analytics platform providing comprehensive data for Avalanche protocols and tokens."
logo: /images/defilama.jpeg
developer: DeFi Llama
website: https://defillama.com/
documentation: https://docs.llama.fi/
---

## Overview

DeFi Llama is the largest TVL (Total Value Locked) aggregator for DeFi protocols, providing transparent and comprehensive data for the Avalanche ecosystem. It offers real-time analytics, tracking TVL, yields, stablecoin data, and protocol metrics across multiple chains, with a particular focus on accuracy and transparency.

## Features

- **TVL Tracking**: Real-time monitoring of Total Value Locked across Avalanche protocols.
- **Yield Analytics**: Comprehensive yield farming opportunities tracking on Avalanche.
- **Protocol Insights**: Detailed metrics for individual protocols and their performance.
- **Stablecoin Data**: Track stablecoin circulation and usage across Avalanche.
- **Open Source**: Transparent methodology with community-driven updates.
- **API Access**: Free and comprehensive API for developers and analysts.
- **DEX Analytics**: Track volume, liquidity, and other metrics for Avalanche DEXs.

## Getting Started

To use DeFi Llama for Avalanche analytics:

1. **Visit Platform**: Go to [DeFi Llama](https://defillama.com/).
2. **Explore Avalanche**: Navigate to the Avalanche chain section for ecosystem-specific data.
3. **Track Protocols**: Monitor your favorite Avalanche protocols' performance and TVL.
4. **Access APIs**: For developers, integrate DeFi Llama's data using their comprehensive API.

## Documentation

For detailed API documentation and integration guides, visit the [DeFi Llama Documentation](https://docs.llama.fi/).

## Use Cases

DeFi Llama serves various analytical needs:

- **Market Research**: Track protocol growth and market trends on Avalanche.
- **Investment Analysis**: Compare yields and TVL across different protocols.
- **Risk Assessment**: Monitor protocol health and market dynamics.
- **Development**: Integrate DeFi analytics into your applications via API.
- **Protocol Comparison**: Compare performance across different chains and protocols.

## Conclusion

DeFi Llama provides essential analytics and insights for the Avalanche ecosystem, offering transparent and comprehensive data crucial for users, developers, and analysts. Whether you're tracking TVL, researching yields, or analyzing protocol performance, DeFi Llama delivers reliable and up-to-date information for the Avalanche DeFi landscape.


# DEX Screener (/integrations/dexscreener)

---
title: DEX Screener
category: Token Aggregators
available: ["C-Chain", "All EVM L1s"]
description: "DEX Screener provides real-time analytics and trading data for decentralized exchanges on Avalanche, offering comprehensive market insights and trading pair analysis."
logo: /images/dexscreener.png
developer: DEX Screener
website: https://dexscreener.com/
documentation: https://docs.dexscreener.com/
---

## Overview

DEX Screener is a powerful analytics platform that provides real-time data and insights for decentralized exchanges on Avalanche. It offers comprehensive trading pair analysis, price charts, liquidity information, and market metrics, making it an essential tool for traders and investors in the Avalanche ecosystem.

## Features

- **Real-Time Charts**: Live price and volume charts for all trading pairs on Avalanche DEXs.
- **Multi-DEX Support**: Track pairs across multiple Avalanche DEXs simultaneously.
- **Price Alerts**: Set custom alerts for price movements and trading volume.
- **Liquidity Analysis**: Deep insights into liquidity pools and movements.
- **Trading Pair Analytics**: Detailed metrics including volume, liquidity, and price changes.
- **Market Sentiment**: Track social metrics and trading patterns.
- **API Access**: Professional-grade API for developers and traders.

## Getting Started

To begin using DEX Screener:

1. **Access Platform**: Visit [DEX Screener](https://dexscreener.com/).
2. **Select Network**: Choose Avalanche to view C-Chain pairs.
3. **Analyze Pairs**: 
   - Search for specific trading pairs
   - View real-time charts and metrics
   - Set up custom watchlists
4. **Configure Alerts**: Set up price and volume notifications for tracked pairs.

## Documentation

For API documentation and integration guides, visit the [DEX Screener Documentation](https://docs.dexscreener.com/).

## Use Cases

DEX Screener serves various analytical needs:

- **Trading Analysis**: Real-time market analysis and trading pair monitoring.
- **Liquidity Tracking**: Monitor liquidity depths and movements across DEXs.
- **Market Research**: Analyze new tokens and trading pairs on Avalanche.
- **Portfolio Management**: Track multiple pairs and set alerts for price movements.
- **Development Integration**: Build trading tools using the DEX Screener API.

## Conclusion

DEX Screener provides essential trading analytics and market insights for the Avalanche DeFi ecosystem. With its comprehensive feature set and real-time data across multiple DEXs, it serves as a crucial tool for traders, investors, and developers operating in the Avalanche marketplace.


# DIA (/integrations/dia)

---
title: DIA
category: Oracles
available: ["C-Chain"]
description: DIA is an open-source oracle platform that provides transparent, crowd-verified price oracles for DeFi applications.
logo: /images/DIA.png
developer: DIA
website: https://diadata.org/
documentation: https://docs.diadata.org/
---

## Overview

DIA (Decentralized Information Asset) is an open-source oracle platform designed to deliver transparent, crowd-verified data feeds for decentralized finance (DeFi) applications. By leveraging community-driven data collection and validation, DIA ensures that its price oracles are accurate, reliable, and tamper-resistant. This makes DIA an essential tool for developers looking to integrate secure and trustworthy data into their DeFi protocols and smart contracts.

## Features

- **Open-Source Platform**: DIA's data feeds and infrastructure are fully open-source, allowing developers to inspect, contribute to, and customize the platform according to their needs.
- **Crowd-Verified Data**: Data is sourced, validated, and verified by the community, ensuring transparency and reducing the risk of manipulation.
- **Multi-Chain Support**: DIA provides oracles that are compatible with multiple blockchain networks, including Ethereum, Binance Smart Chain, and more.
- **Customizable Oracles**: Developers can create custom data feeds tailored to specific use cases, ensuring that the data meets their exact requirements.
- **DeFi Focused**: DIA's oracles are specifically designed for DeFi applications, providing accurate price feeds and other financial data essential for the operation of decentralized financial products.

## Getting Started

To integrate DIA into your DeFi application, follow these steps:

1. **Explore DIA**: Visit the [DIA website](https://diadata.org/) to learn more about the platform and its offerings.
2. **Access the Documentation**: Refer to the [DIA Documentation](https://docs.diadata.org/) to get started with the integration process, including API usage and custom oracle creation.
3. **Set Up Data Feeds**: Follow the documentation to integrate DIA's price oracles into your DeFi application, ensuring reliable and transparent data inputs.
4. **Customize Oracles**: Use DIA's tools to create custom oracles that meet the specific needs of your application, whether it's a unique price feed or another type of financial data.
5. **Deploy and Monitor**: After integration, deploy your application and continuously monitor the performance and accuracy of the data feeds provided by DIA.

## Documentation

For detailed integration guides, API references, and customization options, visit the [DIA Documentation](https://docs.diadata.org/).

## Use Cases

DIA is particularly suited for a wide range of DeFi applications that require reliable and transparent data:

- **Lending and Borrowing Platforms**: Use DIA's price oracles to provide accurate asset valuations, ensuring fair lending and borrowing conditions.
- **Decentralized Exchanges (DEXs)**: Integrate DIA to power your DEX with real-time, crowd-verified price feeds, enhancing trade accuracy.
- **Stablecoins**: Utilize DIA's oracles to maintain accurate price pegs by feeding reliable data into the smart contracts governing stablecoins.
- **Derivatives Markets**: DIA can be used to provide the necessary financial data for creating and managing decentralized derivatives products.

## Conclusion

DIA is a powerful tool for DeFi developers, offering transparent, reliable, and customizable oracles that are essential for the integrity and success of decentralized financial applications. Whether you're building a lending platform, a DEX, or any other type of DeFi product, DIA provides the data infrastructure you need to ensure your application operates smoothly and securely.



# DipDup (/integrations/dipdup)

---
title: DipDup
category: Indexers
available: ["C-Chain"]
description: DipDup is a Python framework for building smart contract indexers. It helps developers focus on business logic instead of writing boilerplate code to store and serve data.
logo: /images/dipdup.png
developer: DipDup
website: https://dipdup.io/
documentation: https://dipdup.io/docs
---

## Overview

DipDup is a Python-based framework specifically designed for building smart contract indexers. It simplifies the development process by allowing developers to concentrate on business logic without needing to write extensive boilerplate code for data storage and retrieval. DipDup is ideal for creating scalable and efficient indexers on the Avalanche C-Chain.

## Features

- **Python Framework**: Leverage the power and simplicity of Python to build custom smart contract indexers quickly.
- **Focus on Business Logic**: DipDup handles the heavy lifting of data storage and serving, enabling developers to focus on implementing their specific business logic.
- **Scalable Indexing**: Easily scale your indexing solutions to handle increasing data and transaction volumes.
- **Customizability**: DipDup offers flexibility, allowing developers to customize their indexers to meet specific project needs.

## Getting Started

To start using DipDup:

1. **Visit the DipDup Website**: Explore the [DipDup website](https://dipdup.io/) to learn more about the framework.
2. **Access the Documentation**: Refer to the [DipDup Documentation](https://dipdup.io/docs) for step-by-step guides on setting up and using DipDup.
3. **Set Up Your Indexer**: Follow the documentation to set up a custom smart contract indexer using DipDup.
4. **Implement Business Logic**: Focus on implementing your specific business logic while DipDup handles the data management.
5. **Deploy on C-Chain**: Utilize DipDup to deploy and manage your indexer on the Avalanche C-Chain.

## Documentation

For comprehensive guides and tutorials, visit the [DipDup Documentation](https://dipdup.io/docs).

## Use Cases

DipDup is suitable for:

- **Blockchain Developers**: Build efficient and scalable smart contract indexers on the Avalanche C-Chain.
- **Data-Intensive Applications**: Simplify the indexing process for applications that require robust data storage and retrieval mechanisms.
- **Custom Indexer Development**: Tailor your indexers to meet the unique requirements of your blockchain projects.

## Conclusion

DipDup is a powerful and flexible Python framework that streamlines the creation of smart contract indexers. By handling the complexities of data storage and serving, DipDup allows developers to focus on building and deploying business logic, making it an essential tool for projects on the Avalanche C-Chain.



# dKiT API/SDK (/integrations/dkit)

---
title: dKiT API/SDK
category: Crosschain Solutions
available: ["C-Chain"]
description: "dKit is a production-ready cross-chain DEX aggregation API/SDK that enables native swaps across 15+ blockchains including Avalanche by routing liquidity through THORChain, Chainflip, Maya, Jupiter, Garden and 1inch."
logo: /images/dkit.png
developer: dKit Team
website: https://dkit.xyz/
documentation: https://docs.dkit.xyz/
---

## Overview

dKiT is a unified cross-chain DEX aggregation layer that lets dApps execute **native** token swaps across 19+ blockchains including Avalanche’s C-Chain—via a single API/SDK. It abstracts multiple protocols and aggregators behind one interface, providing best-price discovery, non-custodial execution, and real-time tracking.

## Features

- **Native Cross-Chain Swaps**: Swap native assets (e.g. BTC ↔ AVAX).  
- **Smart Routing**: Finds optimal routes across multiple protocols and DEX aggregators. 
- **Streaming Swaps**: Splits large trades to reduce price impact. 
- **One-Transaction UX**: “One-signature” Cross-Chain Swaps.  
- **Revenue & Fee Streaming**: Add custom affiliate fees and automatically stream them to your wallets.  
- **Broad Wallet Support**: Easily integrate 20+ wallets (EVM, Solana, Cosmos, hardware, and WalletConnect). 
- **Avalanche Support**: Support for Avalanche (C-Chain) cross-chain swaps.

## Getting Started

1. **Review the Docs**  
   Browse the [dKit Documentation](https://docs.dkit.xyz/) to understand concepts, endpoints, and workflows.

2. **Get an API Key**  
   Request API keys on [dkit.xyz](https://dkit.xyz/get-api-key) → **Get API Key**.

3. **Install & Configure**  
   - Use the SDK (e.g., `@doritokit/sdk`) or call the REST API directly.  
   - Provide any required API keys (e.g., EVM explorers or UTXO helpers).  
   - Enable Avalanche (C-Chain) within your chain list.

4. **Quote → Execute → Track**  
   - Call `/v1/quote` to get the best route and expected output.  
   - Execute the transaction 
   - Poll `/v1/track` to monitor progress, including streaming status.

5. **Monetize**  
   Configure **affiliate fees** so a share of volume routed via your app is streamed to your addresses.

## Documentation

- **Introduction & Concepts**: [docs.dkit.xyz](https://docs.dkit.xyz/)  
- **API Reference / Swagger**: [api.dkit.xyz](https://api.dkit.xyz)  
- **Quick Start**: End-to-end example for quoting, executing, and tracking swaps  
- **Revenue Generation**: [docs.dkit.xyz/revenue-generation](https://docs.dkit.xyz/revenue-generation)  
- **Status Page**: [dkit.instatus.com](https://dkit.instatus.com)

## Supported Protocols & Aggregators

- **THORChain** 
- **Chainflip**   
- **MayaChain**   
- **Jupiter**  
- **1inch**  
- **Garden Finance** 

## Use Cases

- **Cross-Chain Swaps in Any dApp**: Add native BTC ↔ EVM/Solana/Cosmos swaps to wallets and DEXs. 
- **Cross-Chain DEX / Router**: Power a trading interface with best-price discovery and cross-chain support.  
- **Bridgeless Asset Migration**: Let users move assets across ecosystems without using wrapped tokens or CEXs.    
- **Affiliate Monetization**: Stream fees on every swaps.

## Conclusion

dKit delivers a reliable, developer-friendly cross-chain aggregation layer for Avalanche’s C-Chain and beyond. With native swaps, smart routing and fee monetization, it’s a fast way to ship a seamless cross-chain experience in production.


# Dreamspace (/integrations/dreamspace)

---
title: Dreamspace
category: Developer Tooling
available: ["C-Chain", "All EVM L1s"]
description: Dreamspace is a drag and drop vibe coding canvas that lets anyone build apps and deploy smart contracts on any EVM-compatible chain. 
logo: /images/dreamspace.jpg
developer: Dreamspace
website: https://dreamspace.xyz
documentation: https://docs.makeinfinite.com/docs/getting-started
---

## Overview
Dreamspace is redefining the way decentralized applications (dApps) are built by merging AI-powered development tools with no-code accessibility. As a leading vibe coding studio, it empowers creators, developers, and entrepreneurs to transform ideas into fully functional Web3 applications without the steep learning curve of traditional coding. Whether you’re building DeFi protocols, NFT platforms, DAOs, or blockchain analytics dashboards, Dreamspace provides the tools to go from concept to deployment seamlessly.

## Key Features

- **AI-Powered Smart Contract Generation**: Build and deploy secure contracts for DeFi, NFTs, or DAOs without writing code.
- **Prompt-to-SQL Queries**: Query indexed blockchain data in natural language, unlocking real-time analytics and data-driven dApps with minimal effort.
- **Visual Drag-and-Drop Builder**: Assemble contracts, queries, and UI components in an intuitive canvas to create full-stack dApps.
- **Native Data Integration**:  Powered by Space and Time’s ZK-proven data warehouse, enabling advanced data visualization and interaction for onchain apps.
- **No-Code Accessibility**: Lowers barriers for creators of all skill levels, making blockchain development more inclusive.

## Getting Started:

1. **Launch Your Project**: Start from a blank project or describe your app idea, then click “Start Creating” on the homepage.

2. **Select a Component**: – Click the element you want to edit; it will be highlighted with a pink border and shown as Selected in the chatbot.

3. **Edit with AI**: In canvas edit mode, type a request (e.g., “change the background to blue”) into the chatbot and press enter. Wait for Dreamspace AI to apply changes.

4. **Refine & Adjust**: Use undo/redo, resize, or move components directly in the canvas.

5. **Style Your App**: Customize colors, fonts, and layouts under the “Themes” tab in the chatbot.

6. **Enhance with Data & Integrations**: Add SQL queries, charts, third-party APIs, or connect smart contracts to bring your dApp to life.

## Documentation:

For detailed documentation on how to get started, visit [here](https://docs.makeinfinite.com/docs/getting-started)

## Use Cases

Dreamspace is ideal for; 

- **DeFi Protocols**: Launch staking platforms, lending apps, or liquidity pools without deep blockchain coding.

- **NFT Platforms**: Build marketplaces, rarity trackers, or minting sites powered by AI-generated contracts.

- **DAOs**: Create governance tools, voting systems, and treasury management apps with ease.

- **Blockchain Analytics Dashboards** Query and visualize onchain data using natural language (Prompt-to-SQL).

- **Rapid dApp Prototyping**: Turn ideas into functional applications quickly with drag-and-drop editing and AI-powered customization.

 ## Conclusion

With Dreamspace, anyone can seamlessly build and deploy apps on EVM chains—including Avalanche—without writing a single line of code.

  


# Dynamic (/integrations/dynamic)

---
title: Dynamic
category: Wallet SDKs
available: ["C-Chain", "All EVM L1s"]
description: Dynamic simplifies the creation of multi-chain experiences with its customizable suite of tools, offering onboarding, embedded wallets, efficient authentication, and scalable user management.
logo: /images/dynamic.png
developer: Dynamic
website: https://www.dynamic.xyz/
documentation: https://docs.dynamic.xyz/
---

## Overview

Dynamic provides the simplest way for developers to onboard their users to their apps, whether they are a crypto enthusiast or newcomer to the space. Dynamic achieves this through offering a growing suite of tools catered to embedded wallets, authentication, multi-chain experiences, and user management.

## Features

- Embedded Wallets: Spin up flexible, non-custodial embedded wallets, and focus on building experiences that matter. Abstract the complexity of crypto away from users, and onboard them with familiar and customizable UX.
- Authentication: Dynamic provides secure and seamless authentication, with the ability for end-users to protect their wallets further with Passkeys, MFA, one-time codes, and more.
- Multi-Chain Wallet Adaptor: Through Dynamic, end-users can connect hundreds of different wallets across EVM, Solana, Bitcoin, Starknet, and more. We support more chains and wallets than any other Web3 auth provider. Additionally, users can get started with SMS, email, or familiar social login options.
- User Management Solution: Dynamic allows developers to assign their end-users roles & permissions, present custom onboarding flows, and manage everything through a robust dashboard.

And much more - try it all out for yourself in [Dynamic's live demo](https://demo.dynamic.xyz/)!

## Getting Started

1. Access our Documentation: Our [best-in-class docs](https://docs.dynamic.xyz/) provide all of the information developers need to get started building with Dynamic.
2. Get started on your own: Create a free account [here](https://app.dynamic.xyz) to explore Dynamic’s powerful developer dashboard and capabilities.
3. Talk with our team: Set up a time to [meet with our team](https://www.dynamic.xyz/talk-to-us) and discuss what’s possible with Dynamic.
4. Try out our live demo: Through [our demo environment](https://demo.dynamic.xyz/), developers can experiment with our multi-chain wallet adaptor and customize it to their exact needs.

## Documentation
For detailed guides on building with Dynamic, refer to our documentation [here](https://docs.dynamic.xyz/).

## Use Cases

Dynamic is a strong fit for any Web2 or Web3 experience that requires onboarding users at scale, in a secure and simple manner. We work with projects in every sector of crypto across Solana, Bitcoin, a wide range of EVM chains, and more.

Here are a few of the many use cases we cover:

- Onchain Gaming
- DeFi Platforms
- L1s & L2s
- Bridges
- Multi-chain apps
- Social & consumer apps

## Conclusion

Dynamic empowers developers to create multi-chain experiences with ease. Whether you're implementing embedded wallets, searching for a secure and fast auth experience, or handling scalable user management, Dynamic's suite of tools is designed to streamline the process. And with comprehensive documentation and a live demo, getting started is only a few clicks away.


# Envio (/integrations/envio)

---
title: Envio
category: Indexers
available: ["C-Chain", "All EVM L1s"]
description: Envio is a full-featured data indexing solution that provides application developers with a seamless and efficient way to index and aggregate real-time and historical blockchain data for any EVM.
logo: /images/envio.png
developer: Envio
website: https://envio.dev/
documentation: https://docs.envio.dev/docs/HyperIndex/overview
---

## Overview

Envio is a comprehensive data indexing solution tailored for developers working on EVM-compatible blockchains, including Avalanche's C-Chain and Layer 1 chains. Envio simplifies the process of indexing and aggregating both real-time and historical blockchain data, providing a reliable and efficient infrastructure for decentralized applications.

## Features

- **Full-Featured Indexing**: Envio offers complete indexing capabilities, handling both real-time and historical blockchain data across EVM-compatible chains.
- **EVM Compatibility**: Designed to work seamlessly with any EVM, including Avalanche's C-Chain and Layer 1 networks.
- **Scalable Solution**: Envio provides scalability, ensuring your indexing needs are met as your application grows.
- **Efficient Data Aggregation**: Aggregate blockchain data efficiently, allowing developers to focus on building applications rather than data management.
- **Customizable**: Envio allows for customization to meet the specific needs of different applications and use cases.

## Getting Started

To start using Envio:

1. **Visit the Envio Website**: Learn more about Envio's features and offerings on the [Envio website](https://envio.dev/).
2. **Access the Documentation**: Detailed setup instructions can be found in the [Envio Documentation](https://docs.envio.dev/docs/HyperIndex/overview).
3. **Set Up Indexing**: Follow the documentation to set up indexing for your blockchain data.
4. **Customize Your Solution**: Tailor Envio to your application's specific data needs, ensuring efficient and accurate data aggregation.
5. **Deploy on C-Chain and L1**: Utilize Envio for indexing on Avalanche's C-Chain and Layer 1 networks.

## Documentation

For in-depth guides and support, refer to the [Envio Documentation](https://docs.envio.dev/docs/HyperIndex/overview).

## Use Cases

Envio is ideal for:

- **EVM Developers**: Efficiently index and manage data for applications on EVM-compatible blockchains.
- **Data-Intensive DApps**: Ensure reliable access to both real-time and historical blockchain data.
- **Custom Blockchain Solutions**: Build customized indexing solutions tailored to specific use cases and performance requirements.

## Conclusion

Envio provides a robust and flexible indexing solution for developers working on EVM-compatible blockchains, including Avalanche's C-Chain and Layer 1 networks. By offering seamless data aggregation and customizable indexing features, Envio helps streamline the development of decentralized applications.



# Fireblocks (/integrations/fireblocks)

---
title: Fireblocks
category: Wallet SDKs
available: ["C-Chain", "All EVM L1s"]
description: Fireblocks is an institutional-grade platform for securing digital assets, providing secure storage, transfer, and management of cryptocurrencies.
logo: /images/fireblocks.png
developer: Fireblocks
website: https://www.fireblocks.com/
documentation: https://developers.fireblocks.com/
---

## Overview

Fireblocks is a leading platform designed for the secure storage, transfer, and management of digital assets. Tailored for institutional clients, Fireblocks offers a robust and scalable solution for managing cryptocurrencies and digital assets with the highest level of security. Whether you're a financial institution, a crypto service provider, or an enterprise, Fireblocks provides the tools necessary to protect and manage digital assets efficiently.

## Features

- **Secure Storage**: Fireblocks offers institutional-grade security for storing digital assets, leveraging MPC (Multi-Party Computation) technology and hardware isolation.
- **Safe Transfers**: Transfer assets securely across wallets and exchanges with built-in safeguards against fraud and hacking.
- **Comprehensive Wallet Management**: Manage multiple digital asset wallets through a single platform with streamlined workflows and advanced security protocols.
- **APIs for Integration**: Integrate Fireblocks' secure storage and transfer capabilities into your existing systems using their comprehensive API suite.
- **Compliance and Governance**: Maintain compliance with regulatory requirements and implement governance controls for digital asset management.
- **24/7 Monitoring and Support**: Benefit from continuous monitoring and dedicated support to ensure your assets remain secure and operations run smoothly.

## Getting Started

To get started with Fireblocks:

1. **Visit the Fireblocks Website**: Learn more about Fireblocks and its offerings by visiting the [Fireblocks website](https://www.fireblocks.com/).
2. **Access the Documentation**: Refer to the [Fireblocks Developer Documentation](https://developers.fireblocks.com/) for detailed instructions on integrating Fireblocks into your operations.
3. **Explore Integration Options**: Use Fireblocks' API to integrate secure digital asset management into your existing infrastructure.
4. **Set Up Wallets**: Securely set up and manage digital asset wallets tailored to your institutional needs.
5. **Utilize Governance Features**: Implement governance controls and workflows to ensure compliance and operational security.

## Documentation

For comprehensive guides on using Fireblocks and integrating it into your systems, check out the [Fireblocks Developer Documentation](https://developers.fireblocks.com/).

## Use Cases

Fireblocks is ideal for:

- **Financial Institutions**: Securely manage and transfer large volumes of digital assets with institutional-grade security.
- **Crypto Service Providers**: Provide secure custody and transfer services to clients using Fireblocks' infrastructure.
- **Enterprises**: Integrate digital asset management into your business operations, ensuring security and compliance.
- **Trading Desks**: Streamline secure asset transfers and wallet management for efficient trading operations.

## Conclusion

Fireblocks is an essential platform for any institution involved in the management and transfer of digital assets. With its robust security features, easy integration, and comprehensive wallet management tools, Fireblocks helps protect your assets while simplifying operations. Whether you're managing digital assets at scale or providing crypto services to clients, Fireblocks offers the security and flexibility you need.



# Flair (/integrations/flair)

---
title: Flair
category: Indexers
available: ["C-Chain", "All EVM L1s"]
description: Flair provides real-time and historical custom data indexing for any EVM-compatible chain.
logo: /images/flair.jpg
developer: Flair
website: https://flair.dev/
documentation: https://docs.flair.dev/
---

## Overview

Flair is a powerful indexing solution designed to offer both real-time and historical data indexing for any EVM-compatible blockchain, including Avalanche's C-Chain and Layer 1 networks. Flair enables developers to create custom indexing solutions, ensuring that their applications have access to accurate and timely blockchain data.

## Features

- **Custom Data Indexing**: Build and deploy custom data indexing solutions tailored to the specific needs of your application.
- **Real-Time Indexing**: Access real-time blockchain data, ensuring that your application stays up-to-date with the latest information.
- **Historical Data Indexing**: Efficiently index and retrieve historical data, providing a complete view of blockchain activity.
- **EVM Compatibility**: Designed to work seamlessly with any EVM-compatible chain, including Avalanche's C-Chain and L1 networks.
- **Scalable Infrastructure**: Flair’s infrastructure scales to meet the demands of growing applications, ensuring reliable performance.

## Getting Started

To start using Flair:

1. **Visit the Flair Website**: Explore the features and capabilities of Flair on the [Flair website](https://flair.dev/).
2. **Access the Documentation**: Follow the [Flair Documentation](https://docs.flair.dev/) for detailed setup instructions and guides.
3. **Set Up Custom Indexing**: Implement custom data indexing tailored to your application's requirements.
4. **Deploy on C-Chain and L1**: Utilize Flair for indexing on Avalanche's C-Chain and other EVM-compatible Layer 1 networks.
5. **Monitor and Scale**: Take advantage of Flair’s scalable infrastructure to ensure your indexing solution grows alongside your application.

## Documentation

For detailed instructions and support, refer to the [Flair Documentation](https://docs.flair.dev/).

## Use Cases

Flair is ideal for:

- **Developers on EVM Chains**: Create tailored indexing solutions for applications on any EVM-compatible blockchain.
- **Data-Centric Applications**: Ensure real-time access and retrieval of both current and historical blockchain data.
- **Custom Indexing Solutions**: Build and deploy custom indexing infrastructure that meets the unique needs of your project.

## Conclusion

Flair provides a robust and scalable solution for custom data indexing on EVM-compatible blockchains. Whether you need real-time data or historical records, Flair’s flexible infrastructure ensures that your application has access to the data it needs to function efficiently and effectively.



# Foundry (/integrations/foundry)

---
title: Foundry
category: Developer Tooling
available: ["C-Chain", "All EVM L1s"]
description: Foundry is a blockchain development platform that provides a suite of tools for building and deploying blockchain applications.
logo: /images/foundry.png
developer: Paradigm
website: https://book.getfoundry.sh/
documentation: https://book.getfoundry.sh/
---

## Overview

Foundry is a robust blockchain development toolchain created by Paradigm, designed to streamline the process of building, testing, and deploying smart contracts. Written in Rust, Foundry offers developers a comprehensive suite of tools that manage dependencies, compile projects, run tests, deploy contracts, and interact with blockchain networks directly from the command line. It is particularly well-suited for developers looking for a fast, reliable, and modern toolchain to enhance their Ethereum development workflow.

## Features

- **Rust-Based Toolchain**: Foundry is written in Rust, providing performance and reliability, essential for complex smart contract development.
- **Comprehensive Tool Suite**: Foundry includes tools for every stage of development, from dependency management to contract deployment.
- **Fast Compilation**: The toolchain is optimized for speed, allowing for rapid compilation of smart contracts.
- **Advanced Testing Framework**: Foundry's testing framework supports unit tests, fuzz tests, and more, helping to ensure your contracts are secure and bug-free.
- **Deployment and Interaction**: Foundry simplifies the process of deploying smart contracts and interacting with them directly from the command line, streamlining the development workflow.

## Getting Started

To start using Foundry, follow these steps:

1. **Install Foundry**: Visit the [Foundry website](https://book.getfoundry.sh/) to install the toolchain on your development environment.
2. **Set Up a Project**: Use Foundry to initialize a new smart contract project, managing dependencies and setting up the project structure.
3. **Write and Compile Contracts**: Write your smart contracts and compile them using Foundry’s high-performance compiler.
4. **Run Tests**: Utilize Foundry’s built-in testing framework to write and execute tests, ensuring your contracts function as expected.
5. **Deploy Contracts**: Deploy your smart contracts to the blockchain directly from the command line using Foundry’s deployment tools.
6. **Interact with Contracts**: Use Foundry to interact with your deployed contracts, making function calls, and managing contract state.

## Documentation

For detailed installation instructions, tutorials, and API references, visit the [Foundry Documentation](https://book.getfoundry.sh/).

## Use Cases

Foundry is ideal for developers who need a powerful toolchain for Ethereum smart contract development:

- **Smart Contract Development**: Build, test, and deploy Ethereum smart contracts efficiently using Foundry’s suite of tools.
- **Testing and Debugging**: Write comprehensive tests, including unit and fuzz tests, to ensure the security and reliability of your smart contracts.
- **Rapid Prototyping**: Quickly prototype and deploy smart contracts, leveraging Foundry’s fast compilation and deployment processes.
- **Advanced Blockchain Interaction**: Use Foundry’s CLI tools to interact with blockchain networks, enabling sophisticated contract management and interaction.

## Conclusion

Foundry offers a powerful, modern toolchain for developers looking to build and deploy Ethereum smart contracts with efficiency and reliability. Its Rust-based design ensures performance, while its comprehensive tool suite simplifies every step of the development process, from writing code to interacting with deployed contracts. Whether you’re a seasoned blockchain developer or new to smart contract development, Foundry provides the tools you need to build robust, secure blockchain applications.



# FrostyMetrics (/integrations/frostymetrics)

---
title: FrostyMetrics
category: Analytics & Data
available: ["C-Chain"]
description: "FrostyMetrics provides comprehensive analytics APIs and SDKs for accessing real-time and historical Avalanche blockchain data."
logo: /images/frostymetrics.jpeg
developer: FrostyMetrics
website: https://www.frostymetrics.com/
documentation: https://docs.frostymetrics.com/
---

## Overview

FrostyMetrics is a specialized analytics platform built for Avalanche, providing developers with APIs and SDKs to access comprehensive blockchain data. It enables integration of real-time metrics, historical data, and custom analytics into applications built on Avalanche.

## Features

- **Data Access**:
  - Real-time blockchain metrics
  - Historical data queries
  - Custom data endpoints
  - Aggregated statistics
- **Integration Tools**:
  - REST API
  - WebSocket feeds
  - GraphQL endpoints
  - SDK integration
- **Analytics Types**:
  - Transaction metrics
  - Address analytics
  - Token statistics
  - Protocol data
- **Developer Tools**:
  - Query builder
  - Data filtering
  - Custom endpoints
  - Rate limiting options

## Getting Started

To integrate FrostyMetrics:

1. **Access API**:
   - Register for API key
   - Choose subscription plan
   - Set up authentication
2. **Implementation**:
```javascript
import { FrostyMetricsClient } from '@frostymetrics/sdk';

const client = new FrostyMetricsClient({
  apiKey: 'your-api-key'
});

// Fetch real-time metrics
const metrics = await client.getMetrics({
  type: 'transaction',
  timeframe: '24h'
});
```

## Documentation

For detailed API documentation and integration guides, visit the [FrostyMetrics Documentation](https://docs.frostymetrics.com/).

## Use Cases

FrostyMetrics enables:

- **DApp Analytics**: Integrate blockchain metrics into applications
- **Market Analysis**: Access historical data and trends
- **Protocol Monitoring**: Track protocol performance and usage
- **User Analytics**: Analyze user behavior and transactions
- **Custom Dashboards**: Build custom analytics displays

## Conclusion

FrostyMetrics provides essential data infrastructure for developers building on Avalanche, offering comprehensive APIs and SDKs for accessing and analyzing blockchain data. Its tools enable developers to integrate sophisticated analytics capabilities into their applications. 

# Gelato (/integrations/gelato)

---
title: Gelato
category: Blockchain as a Service
available: ["All Avalanche L1s"]
description: Gelato Cloud now supports Avalanche L1s delivering enterprise-grade infrastructure for building, deploying, and scaling custom Avalanche networks.
logo: /images/gelato.png
developer: Gelato Network 
website: https://gelato.network/
baas_platform: https://raas.gelato.network/
documentation: https://docs.gelato.network/
featured: true
---

## Overview

Gelato's Blockchain-as-a-Service (BaaS) platform is expanding to support Avalanche L1s, offering developers a comprehensive solution for testing and launching custom L1s. As an early integration partner, Gelato combines its expertise in automation and interoperability with Avalanche's subnet architecture, providing a streamlined experience for L1 deployment and management.As an early integration partner, Gelato fuses Avalanche's powerful Subnet architecture with its cloud-native developer stack, bringing a fully managed, production-ready environment to teams launching Avalanche L1s. 

From native account abstraction to cross-chain interoperability with tight integrations with 50+ 3rd party infrastructure providers like Etherscan, LayerZero, MoonPay, and more, Gelato Cloud offers a unified platform experience purpose-built for enterprise adoption and scale. Trusted by top builders, including projects from Animoca Brands' portfolio like Open Campus, Kraken's Ink, and Fox News Verify, Gelato powers the next generation of blockchain builders.

## Features

#### Gelato brings Enterprise-Grade Cloud Infrastructure to Avalanche L1s:

- **Streamlined Deployment**: Build, deploy, and scale custom Avalanche L1s with Gelato's fully managed Blockchain-as-a-Service. Backed by globally distributed, fault-tolerant infrastructure and 99.99% uptime SLAs, Gelato ensures your L1 is always on, compliant, and ready for mission-critical use cases.
- **Web3 Ecosystem Connectivity**: Seamlessly connect your Avalanche L1 to the broader Web3 ecosystem with built-in interoperability across chains and services. From cross-chain messaging to bridging, Gelato provides the infrastructure and tools to integrate your L1 from day one.
- **Enhanced End-User Experience**: Deliver faster, more reliable applications for your users. Gelato's full-stack infrastructure, spanning Account Abstraction, Node Sale Infrastructure, Oracles, VRF, Functions, and Relayers, ensures your L1 runs smoothly, reduces friction, and builds trust with every interaction.
- **Plug-and-Play Integrations via Gelato Marketplace**: Accelerate development and extend functionality with the Gelato Marketplace, featuring 50+ pre-integrated services, including block explorers, indexers, bridges, smart wallet infrastructure, security tooling, and more. Everything you need to go from testnet to production, all in one place.


## Getting Started

#### Getting Started with Gelato BaaS for Avalanche

1. **Deploy Your Testnet**: Launch your custom Avalanche L1 starting from just $99/month, using Gelato's fully managed testnet deployment service
2. **Configure with Native & Third-Party Infrastructure & Tooling**: Customize your Avalanche L1 with Gelato's integrated infrastructure: Account Abstraction, Oracles, VRF, and more, alongside supported third-party tools.
3. **Gain Deep Operational Insights**: Monitor performance, track profitability, and analyze usage with detailed dashboards tailored for Avalanche L1s.
4. **Scale Your Rollup**: Launch on mainnet and scale with support for Node Sales, Native Yield integrations, and marketplace-driven services.

## Documentation

For comprehensive guides on deploying and managing Avalanche L1s with Gelato BaaS, visit the [Gelato Documentation](https://docs.gelato.network/).

## Conclusion

**Gelato Cloud unlocks a new standard for Avalanche L1 deployment: enterprise-ready, cloud-native, and built for scale.**

By combining Avalanche's powerful Subnet architecture with Gelato's BaaS Platform and Native Web3 Services, developers can build, launch, and grow their own Avalanche L1s with the confidence of 99.99% uptime, world-class UX, and deep ecosystem integrations. Whether you're testing, scaling, or going to market, Gelato provides the end-to-end platform to power your Avalanche L1 from idea to mainnet.



# Glacier (/integrations/glacier)

---
title: Glacier
category: Indexers
available: ["C-Chain", "All EVM L1s"]
description: Glacier is a blockchain indexer built for the Avalanche network, providing real-time data on transactions, blocks, validators, and more.
logo: /images/avacloud.png
developer: Ava Labs
website: https://avacloud.io/products/glacier-api
documentation: https://glacier.docs.avacloud.io/reference/getting-started-with-your-api
featured: true
---

## Overview

Glacier is a robust blockchain indexer specifically designed for the Avalanche network, developed by Ava Labs. It provides real-time data on transactions, blocks, validators, and more, offering developers a powerful tool for integrating blockchain data into their applications. Whether you're building dApps, exploring analytics, or managing blockchain infrastructure, Glacier delivers the data you need with high accuracy and performance.

## Features

- **Real-Time Data**: Access real-time information on transactions, blocks, validators, and other key blockchain metrics.
- **Avalanche-Specific**: Tailored specifically for the Avalanche network, ensuring optimized performance and data relevance.
- **Comprehensive Indexing**: Indexes a wide range of blockchain data, making it easily accessible for various use cases.
- **API Access**: Provides a user-friendly API that simplifies the process of querying and retrieving blockchain data.
- **Scalable Infrastructure**: Built to handle high volumes of requests and data, ensuring reliability even as your application scales.

## Getting Started

To start using Glacier:

1. **Visit the Glacier Product Page**: Explore the [Glacier product page](https://avacloud.io/products/glacier-api) on the Ava Cloud website to understand its features and capabilities.
2. **Access the Documentation**: Refer to the [Glacier Documentation](https://glacier.docs.avacloud.io/reference/getting-started-with-your-api) for detailed guides on setting up and using the Glacier API.
3. **Obtain API Access**: Sign up for an API key to start querying Glacier’s data endpoints.
4. **Integrate Data**: Use the API to integrate real-time blockchain data into your applications, dashboards, or analytics platforms.
5. **Monitor and Optimize**: Utilize available tools to monitor API usage and optimize your queries for better performance.

## Documentation

For detailed instructions, API references, and integration guides, visit the [Glacier Documentation](https://glacier.docs.avacloud.io/reference/getting-started-with-your-api).

## Use Cases

Glacier is suitable for a variety of blockchain-related applications:

- **Decentralized Applications (dApps)**: Enhance dApps with real-time blockchain data for transactions, blocks, and validators.
- **Blockchain Analytics**: Use Glacier to power analytics platforms, providing insights into blockchain activity and trends.
- **Infrastructure Monitoring**: Monitor and manage blockchain infrastructure with accurate and timely data from the Avalanche network.
- **Enterprise Solutions**: Integrate reliable blockchain data into enterprise-level applications and platforms.

## Conclusion

Glacier offers a powerful and scalable solution for indexing and accessing real-time blockchain data on the Avalanche network. With its comprehensive features and user-friendly API, Glacier enables developers to seamlessly integrate critical blockchain data into their applications, supporting a wide range of use cases from dApps to enterprise solutions. Whether you need detailed transaction data, block information, or validator metrics, Glacier provides the tools and resources to meet your needs.



# GMX (/integrations/gmx)

---
title: GMX
category: DEX Liquidity
available: ["C-Chain"]
description: "GMX is a decentralized perpetual exchange offering low fees, deep liquidity and minimal price impact."
logo: /images/gmx.jpeg
developer: GMX Team
website: https://gmx.io/
documentation: https://gmx.io/docs
---

## Overview

GMX is a decentralized perpetual exchange that offers traders deep liquidity, low fees, and minimal price impact. Built on Avalanche's C-Chain, GMX provides users with a robust platform for spot and perpetual trading with up to 30x leverage, all while maintaining decentralization and security.

## Features

- **Deep Liquidity**: Access to deep liquidity pools for minimal price impact on trades.
- **Low Trading Fees**: Competitive fee structure with rewards for liquidity providers.
- **Leverage Trading**: Up to 30x leverage for both long and short positions.
- **Zero Price Impact**: Trade large sizes without affecting market prices through unique pricing mechanism.
- **Real Yield**: Earn rewards in ETH/AVAX from platform trading fees.
- **Multi-Asset Collateral**: Support for multiple assets as collateral for trading.

## Getting Started

To begin using GMX:

1. **Connect Wallet**: Visit [GMX](https://gmx.io/) and connect your Web3 wallet (MetaMask, Core, etc.).
2. **Fund Your Account**: Deposit supported assets to use as collateral.
3. **Start Trading**: 
   - Select your preferred trading pair
   - Choose leverage amount (up to 30x)
   - Place your trade
4. **Manage Positions**: Monitor and manage your open positions through the dashboard.

## Documentation

For comprehensive guides and technical documentation, visit the [GMX Documentation](https://gmx.io/docs).

## Use Cases

GMX serves various trading needs:

- **Spot Trading**: Execute standard token swaps with minimal price impact.
- **Leverage Trading**: Access up to 30x leverage for both long and short positions.
- **Yield Generation**: Earn yields by providing liquidity or staking GMX tokens.
- **Portfolio Management**: Manage positions across multiple assets with advanced trading features.

## Conclusion

GMX provides a powerful decentralized trading platform on Avalanche's C-Chain, offering users access to deep liquidity, leverage trading, and yield opportunities. With its focus on minimal price impact and competitive fees, GMX serves both casual traders and sophisticated users looking for advanced trading features in a decentralized environment.

# Safe{Core} (/integrations/gnosis-safe)

---
title: Safe{Core}
category: Account Abstraction
available: ["C-Chain"]
description: An open-source and modular account abstraction stack. It's the essential tooling and infrastructure for integrating the Safe Smart Account into any digital platform.
logo: /images/gnosis-safe.png
developer: Gnosis
website: https://safe.global/
documentation: https://docs.safe.global/
---
## Overview

Safe is an open-source, modular account abstraction stack developed by Gnosis, designed to facilitate the integration of the Safe Smart Account into digital platforms. It provides the necessary tooling and infrastructure to manage smart contract accounts with advanced security and flexibility. Safe is built to enhance the usability and functionality of smart contract accounts, making it a vital component for developers working with account abstraction and secure transaction management.

## Features

- **Modular Architecture**: Safe offers a modular design, allowing developers to customize and extend its functionality according to their needs.
- **Secure Smart Accounts**: The stack enables the use of Safe Smart Accounts, which are designed to offer enhanced security features such as multi-signature support and customizable transaction rules.
- **Open-Source**: As an open-source project, Safe allows developers to inspect, contribute to, and adapt the codebase for their specific use cases.
- **Integration Tools**: Safe provides a suite of tools for integrating smart account functionalities into various digital platforms, including web and mobile applications.
- **Scalability**: The stack is built to handle a range of use cases from simple transactions to complex multi-signature operations, making it suitable for diverse applications.

## Getting Started

<Callout>The easiest way to integrate the Safe\{Core\} stack to your Avalanche L1 is to use the [Ash Wallet](/integrations/ash).</Callout>

To integrate Safe into your application, follow these steps:

1. **Visit the Safe Website**: Explore the [Safe website](https://safe.global/) to understand its features and capabilities.
2. **Access the Documentation**: Refer to the [Safe Documentation](https://docs.safe.global/) for installation guides, API references, and integration instructions.
3. **Set Up Safe Smart Accounts**: Utilize the documentation to set up and configure Safe Smart Accounts, tailoring them to your application’s requirements.
4. **Integrate with Your Platform**: Use Safe’s tools to integrate smart account functionalities into your digital platform, whether it's a web app, mobile app, or other digital service.
5. **Test and Deploy**: Thoroughly test the integration in a development environment before deploying to production to ensure seamless operation and security.

## Documentation

For detailed guides, API references, and setup instructions, visit the [Safe Documentation](https://docs.safe.global/).

## Use Cases

Safe can be utilized in a variety of scenarios where secure account management and transaction handling are required:

- **Decentralized Finance (DeFi)**: Integrate Safe Smart Accounts to enhance security and multi-signature capabilities for DeFi platforms.
- **Enterprise Applications**: Use Safe to manage complex access controls and transaction rules in enterprise blockchain solutions.
- **Crypto Wallets**: Develop secure and flexible crypto wallets that leverage Safe Smart Accounts for enhanced security and usability.
- **Digital Identity Management**: Employ Safe for managing digital identities with customizable transaction and access rules.

## Conclusion

Safe offers a powerful and flexible solution for integrating secure smart account functionalities into digital platforms. Its modular design, open-source nature, and comprehensive toolset make it an essential resource for developers seeking to enhance the security and functionality of their blockchain applications. Whether you are building a DeFi platform, an enterprise solution, or a crypto wallet, Safe provides the essential infrastructure for effective account abstraction and transaction management.



# GoldRush (/integrations/goldrush)

---
title: GoldRush
category: Indexers
available: ["C-Chain", "All EVM L1s"]
description: GoldRush (powered by Covalent) provides structured onchain data for easy app development. 
logo: /images/goldrush.png
developer: Covalent
website: https://goldrush.dev/
documentation: https://goldrush.dev/docs/
---

## Overview

GoldRush (powered by Covalent) is a set of data tools that enable easy web3 development across [200+ supported blockchains](https://goldrush.dev/docs/networks) including the Avalanche C-Chain and several L1s/avalanche-l1s.

## Features
- Wallet API: All token balances (ERC20, 721, 1155, native), token transfers and prices for a wallet.
- Transactions API: All historical transactions with human-readable log events. Includes gas usage and spend summaries.
- NFT API: Media assets, metadata, sales, owners, trait & attribute filters, thumbnails & previews.
- Cross-Chain Activity API: Single API call to fetch a list of active chains and the latest transaction date on each for an address.
- Security API: NFT and ERC20 token allowances, including value-at-risk.
- Blockchain API: Block details, log events by contract address or topic hash, gas prices, token prices and holders.
## Getting Started
Sign up for a free [API Key](https://goldrush.dev/platform/auth/register/)

There are 4 primary developer tools for using the above mentioned APIs with your key:
1. [GoldRush API](https://goldrush.dev/docs/api/) - REST API with enterprise-grade endpoints to use with any programming language. Switch blockchains with one path parameter.
2. [GoldRush SDKs](https://goldrush.dev/docs/unified-api/sdk/) - official client libraries for TypeScript, Python, Go and Viem.
3. [GoldRush UI Kit](https://github.com/covalenthq/goldrush-kit/) - beautifully designed React components for your dApp frontend.
4. [GoldRush Decoder](https://github.com/covalenthq/goldrush-decoder/) - decode any raw event logs into human-readable structured data.

## Documentation
For detailed guides and API references, visit the [GoldRush Docs](https://goldrush.dev/docs/)

## Use Cases
- [Wallets and portfolio trackers](https://goldrush-wallet-portfolio-ui.vercel.app/)
- [Accounting and tax tools](https://bit.ly/crypto-tax-tool)
- [NFT rendering](https://goldrush-nft-gallery-ui.vercel.app/)
- [App onboarding](https://goldrush-wallet-portfolio-ui.vercel.app/activity/0xfc43f5f9dd45258b3aff31bdbe6561d97e8b71de/)

## Conclusion
Use GoldRush to build faster. GoldRush helps scale hundreds of projects from crypto native teams to Fortune 500 companies.



# Halliday (/integrations/halliday)

---
title: Halliday
category: Account Abstraction
available: ["C-Chain"]
description: The commerce automation platform for modular chains. Empower your users with smart accounts and seamless fiat onramps and offramps.
logo: /images/halliday.png
developer: Halliday
website: https://halliday.xyz/
documentation: https://docs.halliday.xyz/
---

## Overview

Halliday is a commerce automation platform tailored for modular chains, specializing in account abstraction with smart accounts and offering seamless fiat onramps and offramps. It empowers users to manage, spend, and transact digital assets effortlessly, bridging the gap between traditional finance and blockchain technology.

## Features

- **Account Abstraction with Smart Accounts**: Simplify blockchain interactions by utilizing smart accounts, enabling users to manage digital assets without dealing with the complexities of blockchain technology.
- **Fiat Onramps and Offramps**: Provide users with easy access to convert fiat currency into digital assets and vice versa, facilitating smoother transitions between traditional finance and the blockchain ecosystem.
- **User-Friendly Interface**: Empower users with an intuitive platform for managing, spending, and transacting with digital assets.
- **API Integration**: Seamlessly incorporate Halliday’s smart accounts and fiat onramp/offramp features into your platform via comprehensive APIs.
- **Security and Compliance**: Ensure secure transactions and compliance with industry standards to protect user assets and data.

## Getting Started

To start using Halliday:

1. **Visit the Halliday Website**: Explore the [Halliday website](https://halliday.xyz/) to learn more about their platform and offerings.
2. **Access the Documentation**: Consult the [Halliday Documentation](https://docs.halliday.xyz/) for step-by-step instructions on integrating Halliday into your platform.
3. **Implement Smart Accounts**: Utilize Halliday's account abstraction features to simplify user management of digital assets.
4. **Set Up Fiat Onramps/Offramps**: Enable seamless conversion between fiat and digital assets to enhance user accessibility.

## Documentation

For detailed guides on integrating Halliday’s features, refer to the [Halliday Documentation](https://docs.halliday.xyz/).

## Use Cases

Halliday is ideal for:

- **E-commerce Platforms**: Streamline payment processes with smart accounts and fiat onramps/offramps.
- **Video Games**: Implement in-game purchases and digital asset management using Halliday’s platform.
- **Financial Services**: Provide clients with secure and compliant solutions for managing and converting digital assets.

## Conclusion

Halliday is at the forefront of simplifying digital asset management on modular chains, with a focus on account abstraction through smart accounts and seamless fiat onramps and offramps. Whether you're developing an e-commerce platform, a digital wallet, or financial services, Halliday offers the tools necessary to bridge the gap between traditional finance and blockchain technology.



# Hardhat (/integrations/hardhat)

---
title: Hardhat
category: Developer Tooling
available: ["C-Chain", "All EVM L1s"]
description: Hardhat is a development environment for building, testing, and deploying smart contracts on Avalanche and other Ethereum-compatible networks.
logo: /images/hardhat.png
developer: Nomic Labs
website: https://hardhat.org/
documentation: https://hardhat.org/getting-started/
---

## Overview

Hardhat is a comprehensive development environment designed for building, testing, and deploying smart contracts. Developed by Nomic Labs, Hardhat supports Ethereum and Ethereum-compatible networks like Avalanche. It provides developers with a range of tools to streamline the smart contract development process, from local blockchain testing to automated deployment.

## Features

- **Local Blockchain Network**: Hardhat includes a local Ethereum network for rapid testing and development, allowing developers to test contracts before deploying to public networks.
- **Advanced Testing Framework**: It offers robust testing capabilities, including unit tests and integration tests, with advanced debugging features to ensure contract reliability.
- **Extensible Plugins**: Hardhat supports various plugins to extend its functionality, enabling custom features and integrations tailored to development needs.
- **Avalanche Integration**: Configure Hardhat to work seamlessly with the Avalanche network, facilitating deployment and interaction with Avalanche smart contracts.
- **Automated Deployment**: Simplify contract deployment with Hardhat’s tools for managing and automating deployment scripts.

## Getting Started

To start using Hardhat:

1. **Install Hardhat**: Visit the [Hardhat website](https://hardhat.org/) and install Hardhat via npm with `npm install --save-dev hardhat`.
2. **Set Up a New Project**: Initialize a new Hardhat project by running `npx hardhat` and follow the prompts to configure your project.
3. **Configure Avalanche Network**: Update your Hardhat configuration file (`hardhat.config.js`) to include settings for the Avalanche network.
4. **Write and Test Contracts**: Develop and test your smart contracts using Hardhat’s built-in testing framework.
5. **Deploy Contracts**: Use Hardhat’s deployment tools to deploy your contracts to Avalanche or other Ethereum-compatible networks.

## Documentation

For detailed installation instructions, configuration guides, and usage examples, visit the [Hardhat Documentation](https://hardhat.org/getting-started/).

## Use Cases

Hardhat is well-suited for various blockchain development tasks:

- **Smart Contract Development**: Develop, test, and deploy smart contracts efficiently.
- **Decentralized Finance (DeFi)**: Build and deploy DeFi applications on Avalanche or other Ethereum-compatible networks.
- **NFT Projects**: Create and manage NFT smart contracts with Hardhat’s tools.
- **Blockchain Prototypes**: Rapidly prototype and test blockchain applications using Hardhat’s local network.

## Conclusion

Hardhat provides a powerful and flexible development environment for smart contract development on Avalanche and other Ethereum-compatible networks. Its comprehensive toolset, including a local blockchain network, advanced testing capabilities, and support for plugins, makes it an essential resource for developers looking to streamline the development and deployment of blockchain applications.



# Jumio (/integrations/jumio)

---
title: Jumio
category: KYC / Identity Verification
available: ["C-Chain"]
description: Jumio provides AI-powered identity verification and KYC/AML compliance solutions that integrate seamlessly with txAllowlist precompiles for secure and regulatory-compliant blockchain applications.
logo: /images/jumio.png
developer: Jumio
website: https://www.jumio.com/
documentation: https://www.jumio.com/resources/
---

## Overview

Jumio is a leading identity verification and KYC/AML compliance platform powered by AI and machine learning. Their comprehensive suite of solutions enables blockchain applications to verify user identities securely and efficiently, making them an excellent partner for projects implementing txAllowlist precompiles. Jumio's technology combines ID verification, biometric authentication, and AML screening to ensure that only legitimate users can access restricted blockchain applications, while providing a streamlined verification process that minimizes friction.

## Features

- **AI-Powered Identity Verification**: Verifies government-issued IDs with advanced OCR and authenticity checks across 5,000+ ID types from 200+ countries and territories.
- **Biometric Authentication**: Ensures the person is physically present and matches their ID through advanced liveness detection and facial recognition.
- **Deepfake Detection**: Employs sophisticated algorithms to detect and prevent synthetic identity fraud attempts.
- **AML Screening**: Automatically screens users against global watchlists for sanctions, politically exposed persons (PEPs), and adverse media.
- **Risk Signals**: Provides additional verification through address checks, phone verification, email validation, and government database checks.
- **Customizable Risk Scoring**: Determine verification requirements based on transaction risk levels with configurable workflows.
- **Self-Service Rules Editor**: Adjust verification rules in real-time to respond to emerging fraud patterns.
- **Omnichannel Support**: Verify users across web, mobile, and API integrations with consistent security standards.
- **Continuous Monitoring**: Ongoing screening of user profiles against watchlists to maintain compliance.

## Getting Started

To integrate Jumio with your Avalanche-based application using txAllowlist precompiles, follow these steps:

1. **Contact Jumio**: Reach out to Jumio to discuss your specific requirements and establish an account.
2. **Integration Planning**: Choose the appropriate integration method based on your application's needs (API, SDK, or iframe).
3. **Configuration**: Set up your verification workflows, risk rules, and compliance requirements in the Jumio dashboard.
4. **Implementation**: Use Jumio's [resources](https://www.jumio.com/resources/) to integrate their verification services into your application.
5. **Testing**: Test the integration in Jumio's sandbox environment to ensure proper functionality.
6. **Allowlist Automation**: Connect verification results to your txAllowlist management, automatically adding verified users and removing those who fail checks.

## Integration with txAllowlist

Jumio's identity verification platform integrates effectively with Avalanche's txAllowlist precompile through:

1. **Verified Transaction Authorization**: Only allow blockchain transactions from users who have successfully completed Jumio's identity verification.
2. **Risk-Based Transaction Permissions**: Apply different verification levels based on transaction types or amounts, controlling access to functionality through the allowlist.
3. **Automated Compliance Management**: Automatically update the allowlist based on ongoing monitoring of user verification status and AML screening results.
4. **API-Driven Architecture**: Jumio's robust API allows for programmatic management of the txAllowlist based on verification outcomes.
5. **Fraud Prevention**: Reduce the risk of malicious actors accessing your blockchain application by implementing multiple layers of identity verification.

## Documentation

Jumio provides comprehensive [resources](https://www.jumio.com/resources/) for developers looking to integrate their identity verification solutions. The documentation includes whitepapers, case studies, implementation guides, and best practices for implementing identity verification in blockchain applications.

## Use Cases

Jumio's identity verification solutions are particularly valuable for these Avalanche-based applications:

- **Regulatory-Compliant DeFi**: Create lending, borrowing, or trading platforms that meet KYC/AML requirements.
- **Private Blockchain Networks**: Ensure that only verified participants can access permissioned networks.
- **Tokenized Securities**: Verify investor accreditation and identity for compliant security token offerings.
- **High-Value Asset Trading**: Implement enhanced verification for platforms dealing with high-value digital assets.
- **Cross-Border Payment Solutions**: Address compliance requirements for international money transfers on blockchain.
- **Enterprise Applications**: Provide secure identity verification for B2B blockchain solutions.

## Conclusion

Jumio offers a robust, AI-powered identity verification solution that integrates seamlessly with Avalanche's txAllowlist functionality. By combining Jumio's advanced verification technology with txAllowlist precompiles, developers can create secure, compliant blockchain applications that maintain regulatory compliance while providing a smooth user experience. The platform's flexibility, extensive global coverage, and emphasis on fraud prevention make it an excellent choice for projects looking to implement identity verification in regulated blockchain environments. 

# Keyring (/integrations/keyring)

---
title: Keyring
category: KYC / Identity Verification
available: ["C-Chain"]
description: Keyring provides privacy-preserving identity verification using zero-knowledge technology, enabling seamless compliance for blockchain applications implementing txAllowlist precompiles.
logo: /images/keyring.png
developer: Keyring Network
website: https://www.keyring.network/
documentation: https://docs.keyring.network/docs
---

## Overview

Keyring is a pioneering identity verification platform that leverages zero-knowledge (ZK) technology to transform the KYC process for blockchain applications. Through its signature products, Keyring Pro and Keyring Connect, it enables users to verify their identity once and reuse their credentials across multiple platforms without compromising privacy. For projects implementing txAllowlist precompiles, Keyring offers a unique approach that balances regulatory compliance with the privacy-preserving ethos of Web3, allowing only verified users to transact on permissioned networks while minimizing data exposure.

## Features

- **Zero-Knowledge Verification**: Utilizes zkTLS technology to verify user identity without exposing personal data, allowing proofs to be submitted on-chain.
- **Privacy-First Approach**: Users maintain control of their personal information while still satisfying verification requirements.
- **Instant ZK-KYC**: Enables users to extract information from established platforms (like Binance, Revolut, or Coinbase) with proof of authenticity in minutes.
- **Multi-Chain Support**: Available on multiple networks including Ethereum, Base, Arbitrum, Optimism, and Avalanche.
- **Customizable Compliance Policies**: Define specific rules and verification requirements for your platform's risk profile.
- **On-Chain Credential Issuance**: Creates verifiable credentials that can be queried by smart contracts for transaction approval.
- **Seamless Developer Integration**: Simple implementation that can be completed in under 3 hours.
- **Automates Identity Verification**: Replaces manual KYC workflows with automated credential verification.

## Getting Started

To integrate Keyring into your Avalanche-based application with txAllowlist precompiles, follow these steps:

1. **Contact Keyring**: Reach out to Keyring through their [contact page](https://www.keyring.network/contact) to discuss your specific compliance requirements.
2. **Define Compliance Policy**: Work with Keyring to establish the rules and data sources you'll accept for verification.
3. **SDK Integration**: Add a button or link to your frontend using Keyring's SDK to initiate the verification process.
4. **Smart Contract Integration**: Implement the provided modifiers in your smart contracts to check credential validity before allowing transactions.
5. **Testing**: Thoroughly test the integration to ensure proper credential verification and allowlist management.
6. **Launch**: Deploy your enhanced application with integrated txAllowlist and Keyring verification.

## Integration with txAllowlist

Keyring's technology works exceptionally well with Avalanche's txAllowlist precompile for several reasons:

1. **Privacy-Preserving Compliance**: Users can prove they've passed KYC without revealing personal details, maintaining privacy while still enforcing transaction restrictions.
2. **On-Chain Credential Verification**: Smart contracts can verify credentials in real-time before approving transactions, creating a seamless allowlist enforcement mechanism.
3. **Dynamic Access Control**: Transaction permissions can be automatically granted or revoked based on credential status, without requiring manual allowlist management.
4. **Frictionless User Experience**: Users verify once and can interact with multiple applications using the same credentials, reducing barriers to entry.
5. **Risk-Based Approach**: Verification can be calibrated to the level of risk associated with different transaction types or user profiles.

## Documentation

For developers, Keyring provides comprehensive documentation on integrating their identity verification solutions. While documentation links may change, you can find the latest resources on their website at [docs.keyring.network/docs](https://docs.keyring.network/docs).

## Use Cases

Keyring's identity verification solutions are particularly valuable for these Avalanche-based applications:

- **Permissioned DeFi Pools**: Create lending pools or trading platforms that only allow KYC'd users from non-sanctioned countries.
- **Compliant DEXs**: Enable decentralized exchanges to implement regulatory-compliant trading without compromising on decentralization principles.
- **Cross-Chain Ecosystems**: Maintain consistent identity verification across multiple chains or subnets.
- **Token Offerings**: Ensure participants in token sales meet jurisdictional requirements.
- **Enterprise Applications**: Build permissioned applications that require verified identity while maintaining privacy.
- **Travel Rule Compliance**: Implement solutions compatible with the FATF Travel Rule for VASPs without excessive data sharing.

## Conclusion

Keyring represents a significant advancement in blockchain identity verification, offering a unique approach that preserves privacy while enabling compliance with regulatory requirements. By combining Keyring's zero-knowledge verification with Avalanche's txAllowlist precompiles, developers can create applications that satisfy compliance requirements without compromising on the core values of decentralization and user privacy. The seamless integration process and focus on minimizing friction make Keyring an excellent choice for projects looking to implement permissioned systems that maintain a positive user experience. 

# Keystone (/integrations/keystone)

---
title: Keystone
category: Hardware Wallets
available: ["C-Chain"]
description: Integrate Keystone hardware wallet support into your applications using Keystone's SDK.
logo: /images/keystone.png
developer: Keystone
website: https://keyst.one/
documentation: https://docs.keyst.one/
---

## Overview

Keystone provides SDK support for integrating air-gapped hardware wallet functionality into applications built on Avalanche. With recent grant support, Keystone is expanding its capabilities to include X-Chain and P-Chain support.

## SDK Components

- **[Firmware](https://github.com/KeystoneHQ/keystone3-firmware)**: Open-source firmware for secure transaction signing
- **Integration SDK**: Coming soon with X-Chain and P-Chain support
- **QR Code Protocol**: Specifications for air-gapped transaction signing

## Integration Features

- **Air-Gapped Security**: QR code-based transaction signing
- **Multi-Chain Support**: Current C-Chain with upcoming X-Chain and P-Chain support
- **Cross-Platform**: Support for both desktop and mobile applications
- **Hardware Security**: Secure element protection for private keys

## Coming Soon

Integration documentation and SDKs for Avalanche chains will be available in the coming months, enabling developers to:

- Initialize QR code scanning for air-gapped communication
- Generate and manage wallet addresses
- Implement secure transaction signing
- Handle key management within secure hardware

## Use Cases

- **Wallet Applications**: Add air-gapped hardware wallet support
- **Mobile Applications**: Implement QR-based transaction signing
- **DeFi Applications**: Enable secure hardware wallet transactions
- **Cross-Chain Applications**: Support multi-chain operations

## Documentation

Full SDK documentation and integration guides will be released alongside the upcoming X-Chain and P-Chain support.

## Conclusion

Keystone's upcoming SDK support for Avalanche chains will provide developers with tools to integrate secure, air-gapped hardware wallet functionality into their applications. The SDK will enable robust security features through QR code-based signing, making it ideal for applications requiring high-security standards.



# LayerZero (/integrations/layerzero)

---
title: LayerZero
category: Crosschain Solutions
available: ["C-Chain"]
description: "LayerZero is a trustless omnichain interoperability protocol enabling seamless cross-chain messaging and asset transfers on Avalanche."
logo: /images/layerzero.png
developer: LayerZero Labs
website: https://layerzero.network/
documentation: https://docs.layerzero.network/
---

## Overview

LayerZero is an omnichain interoperability protocol that enables secure and reliable cross-chain messaging and asset transfers. On Avalanche's C-Chain, LayerZero provides the infrastructure for applications to communicate across different blockchain networks, facilitating seamless cross-chain experiences with high security guarantees.

## Features

- **Trustless Messaging**: Secure cross-chain communication without trusted intermediaries.
- **Ultra Light Nodes**: Efficient validation of cross-chain messages.
- **Configurable Security**: Customizable security parameters for different use cases.
- **Native Asset Bridging**: Enable native asset transfers across supported chains.
- **Cross-Chain Apps**: Support for omnichain application development.
- **Message Passing**: Generic message passing capabilities across chains.
- **Guaranteed Delivery**: Reliable message delivery with transaction finality.

## Getting Started

To integrate LayerZero:

1. **Review Documentation**: Study the [LayerZero Documentation](https://docs.layerzero.network/).
2. **Choose Endpoint**: Connect to LayerZero's Avalanche endpoint.
3. **Implement Interface**: 
   - Integrate LayerZero messaging interfaces
   - Configure security parameters
   - Test cross-chain functionality
4. **Deploy**: Launch your cross-chain application or service.

## Documentation

For comprehensive integration guides and technical details, visit the [LayerZero Documentation](https://docs.layerzero.network/).

## Use Cases

LayerZero enables various cross-chain scenarios:

- **Token Bridges**: Build secure token bridges between chains.
- **Cross-Chain dApps**: Develop applications that work across multiple chains.
- **NFT Transfers**: Enable NFT movement between different networks.
- **Omnichain Governance**: Implement cross-chain governance mechanisms.
- **Message Passing**: Send arbitrary messages between smart contracts on different chains.

## Conclusion

LayerZero provides essential infrastructure for building cross-chain applications on Avalanche's C-Chain. With its focus on security, reliability, and flexibility, LayerZero enables developers to create truly omnichain experiences while leveraging Avalanche's high-performance infrastructure. Whether you're building a token bridge, cross-chain dApp, or implementing governance mechanisms, LayerZero offers the tools needed for secure cross-chain communication. 

# Least Authority (/integrations/leastauthority)

---
title: Least Authority
category: Security Audits
available: ["C-Chain", "All EVM L1s"]
description: "Least Authority delivers top-tier security audits for blockchain systems with specialized expertise in cryptography and distributed systems."
logo: /images/leastauthority.jpg
developer: Least Authority
website: https://leastauthority.com/
---

## Overview

Least Authority is a top-tier security firm specializing in cryptography, distributed systems, and privacy-focused technologies. Their team provides comprehensive security audits for blockchain projects building on Avalanche, with particular expertise in cryptographic protocols and distributed consensus systems. Founded on principles of privacy and security, Least Authority brings deep technical knowledge and rigorous methodology to their security assessments.

## Features

- **Smart Contract Audits**: Thorough code reviews of Solidity and other smart contract implementations.
- **Cryptographic Protocol Analysis**: Specialized review of cryptographic implementations and protocols.
- **Distributed Systems Security**: Expert evaluation of consensus mechanisms and network protocols.
- **Privacy-Focused Security**: Specialized assessments for privacy-enhancing technologies.
- **Formal Security Models**: Development of formal security models and threat assessments.
- **Open Source Expertise**: Deep experience with open source security principles.

## Getting Started

To engage Least Authority for security audits:

1. **Initial Inquiry**: Contact Least Authority through their website to discuss your project's needs.
2. **Project Scoping**: Define the scope, objectives, and timeline for the security assessment.
3. **Audit Process**: 
   - In-depth code review by specialized security researchers
   - Comprehensive analysis of protocol design and implementation
   - Identification of vulnerabilities and security concerns
   - Detailed remediation recommendations
4. **Final Report**: Delivery of a comprehensive audit report documenting findings and recommendations.
5. **Remediation Review**: Optional review of implemented fixes to verify security improvements.

## Use Cases

Least Authority security audits are particularly valuable for:

- **Privacy-Focused Projects**: Applications requiring strong privacy guarantees.
- **Cryptographic Protocols**: Systems implementing novel cryptographic approaches.
- **Consensus Mechanisms**: Custom consensus implementations for Avalanche L1s.
- **Distributed Systems**: Complex distributed systems with multiple interaction points.
- **Zero-Knowledge Applications**: Projects implementing zero-knowledge proof systems.

## Conclusion

Least Authority provides top-tier security assessments with specialized expertise in cryptography, distributed systems, and privacy technologies. Their technical depth and focus on fundamental security principles make them an excellent choice for projects requiring rigorous cryptographic validation or building privacy-enhancing technologies on Avalanche. While their audit process has longer lead times due to demand and thoroughness, the resulting security assurance is valuable for projects where cryptographic correctness and privacy are paramount. 

# Ledger (/integrations/ledger)

---
title: Ledger
category: Hardware Wallets
available: ["C-Chain", "All EVM L1s"]
description: Integrate Ledger hardware wallet support into your applications using official Ledger SDKs for Avalanche.
logo: /images/ledger.png
developer: Ledger
website: https://www.ledger.com/
documentation: https://developers.ledger.com/
---

## Overview

Ledger provides multiple SDKs that enable wallet applications and dApps to integrate hardware wallet functionality for Avalanche chains. The SDKs are available in Go and JavaScript, making it easy to add Ledger support to both desktop and web applications.

## Available SDKs

- **[Avalanche Ledger App](https://github.com/ava-labs/ledger-avalanche)**: Core application running on Ledger devices
- **[Go SDK](https://github.com/ava-labs/ledger-avalanche-go)**: Native Go implementation for backend and desktop applications
- **[JavaScript SDK](https://github.com/ava-labs/ledger-avalanche)**: Browser and Node.js support for web applications

## Integration Features

- **Multi-Chain Support**: Enable transaction signing across C-Chain, X-Chain, and P-Chain
- **Hardware-Based Security**: Leverage Ledger's secure element for key protection
- **Cross-Platform**: Support for both desktop and web applications
- **Transaction Signing**: Secure signing for transfers, staking, and smart contracts

## Getting Started

### Go SDK Integration

```go
import ledger "github.com/ava-labs/ledger-avalanche-go"

// Initialize connection
ledgerApp, err := ledger.NewLedgerApp()
if err != nil {
    // Handle connection error
}
```

### JavaScript SDK Integration

```javascript
import Ledger from '@avalabs/ledger-avalanche'

const ledger = new Ledger()
await ledger.connect()
```

## Use Cases

- **Wallet Applications**: Add hardware wallet support to cryptocurrency wallets
- **DeFi Applications**: Enable secure transaction signing for DeFi operations
- **Validator Tools**: Secure validator key management and staking operations
- **Cross-Chain Applications**: Support multi-chain operations with single device

## Documentation

- [Ledger Developer Portal](https://developers.ledger.com/)
- [Go SDK Documentation](https://pkg.go.dev/github.com/ava-labs/ledger-avalanche-go)
- [JavaScript SDK Documentation](https://github.com/ava-labs/ledger-avalanche)

## Conclusion

Ledger's SDKs provide the essential tools for integrating secure hardware wallet functionality into your Avalanche applications. Whether you're building a wallet, DeFi platform, or validator tools, Ledger's SDKs offer robust support for hardware-based key management and transaction signing across all Avalanche chains.



# Liquify (/integrations/liquify)

---
title: Liquify
category: Blockchain as a Service
available: ["All EVM L1s"]
description: Liquify is a bare-metal infrastructure provider offering high-performance, customizable solutions for launching and managing Avalanche L1s.
logo: /images/liquify_primary_icon.svg
developer: Liquify
website: https://www.liquify.com/
---

## Overview

Liquify, a bare-metal infrastructure provider, now supports Avalanche L1 deployment offering high-performance, customizable solutions for launching and managing custom L1s. With its own dedicated servers, Liquify delivers enterprise-grade deployments that prioritize security, scalability, and full customization, enabling builders to optimize their blockchain infrastructure without relying on shared cloud resources.

## Features

- **Bare-Metal Performance**: Maximum control, global coverage, low latency, and high throughput, free from the limitations of virtualized environments.
- **Full Customization**: Completely customizable deployments, with additional tooling like load-balanced RPC endpoints, custom indexing solutions, monitoring dashboards, and integration with third-party tools for seamless ecosystem connectivity.
- **Enterprise-Grade Security and Reliability**: Advanced security protocols, 99.9% uptime SLAs, and fault-tolerant architecture to support scalable, production-ready L1s.
- **Scalability and Monitoring**: Effortless scaling with built-in tools for real-time monitoring, analytics, and automated maintenance, allowing teams to focus on innovation rather than infrastructure management.

## Getting Started

The process for getting started with Liquify for Avalanche L1 deployments includes:

1. **Fill in the form**: Complete the deployment request form at [Liquify Avalanche L1 Deployment](https://www.liquify.com/avalanche-l1-deployment).
2. **Consultation**: Liquify will reach out to go over the setup and tooling options tailored to your needs.
3. **Scale and optimize**: Work with Liquify's expert team to scale and optimize your infrastructure as needed.

## Learn More

- **Website**: [https://www.liquify.com/](https://www.liquify.com/)
- **Twitter/X**: [https://x.com/liquify_ltd](https://x.com/liquify_ltd)

## Conclusion

Liquify delivers enterprise-grade, bare-metal infrastructure solutions designed specifically for Avalanche L1 deployments. With a focus on performance, security, and full customization, Liquify enables builders to launch production-ready L1s with the reliability and scalability needed for long-term success.



# Messiah (/integrations/messiah)

---
title: Messiah
category: Development Infrastructure
available: ["C-Chain"]
description: Messiah is a decentralized infrastructure platform that simplifies Web3 participation through one-click node deployment, fractional ownership, and AI-powered yield optimization.
logo: /images/messiah.png
developer: Messiah Network
website: https://messiah.network
documentation: https://messiah.network/whitepaper
---

## Overview

Messiah is building **accessible Web3 infrastructure for everyone**. With Messiah’s flagship platform, **NodeHub**, users can seamlessly plug in, fractionalize nodes, deploy dApps, or even become a miner — all with a single click.

Messiah removes the complexity and high costs typically associated with Web3 infrastructure by offering automated tools for deploying and managing **nodes, smart contracts, decentralized applications, and mining operations**.

The mission is clear: **Build, Deploy, Earn** — enabling mass adoption of Web3 by making participation frictionless, censorship-resistant, and rewarding.

### Messiah Offers:

* **One-Click Node Deployment**
  * Instantly run validator and RPC nodes across multiple chains.
  * No coding or server setup required.
* **Fractionalized Node Ownership**

  * Split expensive node ownership into tradable shares.
  * Co-own and earn rewards from high-yield nodes.

* **Messiah Yield Engine (MYE)**

  * AI-driven optimization to track real-time APYs.
  * Dynamically reallocates stake to maximize risk-adjusted yield.

* **Messiah Agent**

  * AI assistant for node deployment and monitoring.
  * Deploy nodes or request insights using natural text prompts.

* **Cross-Chain Infrastructure**

  * Support for 100+ blockchain networks planned.
  * Community-driven onboarding of new chains.

* **Sustainable Compute Layer**

  * Carbon-neutral operations with tokenized green credits.
  * ESG validator rewards for environmentally friendly practices.

* **Full Decentralization**

  * From censorship-resistant infrastructure to community-driven governance.
  * Powered by the Messiah Token for staking, gas, and governance.

In short, Messiah empowers anyone — from casual Web3 enthusiasts to institutional players — to participate in decentralized infrastructure without the usual financial and technical barriers.

## Getting Started

To get started with Messiah, follow these steps:

1. **Visit NodeHub**: Go to [NodeHub](https://app.messiah.network) to explore available nodes and features.
2. **Create an Account**: Sign up with your wallet or social login for instant access.
3. **Explore Fractionalized Nodes**: Buy shares in high-yield validator nodes without needing full capital.
4. **Check the Messiah Agent**: Use natural language prompts to deploy or manage nodes effortlessly.
5. **Review Documentation**: Read the [Messiah Whitepaper](https://messiah.network/whitepaper) for detailed guides and technical insights.
6. **Join the Community**: Connect on [Telegram](https://t.me/messiahnetwork), [X](https://x.com/messiah_network), and [LinkedIn](https://www.linkedin.com/company/messiahnetwork) for updates and governance participation.
7. **Earn Rewards**: Start earning yield from validator and compute nodes, powered by Messiah’s automated infrastructure.

## Documentation

For an in-depth look at Messiah’s architecture, tokenomics, and roadmap, check the [Messiah Whitepaper](https://messiah.network/whitepaper).

## Use Cases

Messiah unlocks new opportunities across the Web3 ecosystem:

**Fractional Node Ownership**

* Democratizes access to high-yield validators.
* Enables anyone to earn rewards without running full infrastructure.

**DeFi Applications**

* Integrate reliable validator nodes and data oracles into DeFi platforms.
* Automate yield allocation through MYE.

**AI Agents**

* Deploy autonomous AI agents with the Messiah Agent and LLM-powered infrastructure.
* Perfect for real-time monitoring, portfolio optimization, and automated decision-making.

**Developers & Enterprises**

* Use NodeHub’s one-click deployment for RPC nodes, testing environments, or CI/CD pipelines.
* Scale infrastructure with DevHub and MessiahCompute.

**Sustainable Web3 Infrastructure**

* Validators and node operators can earn ESG rewards for verifiable green practices.
* Every compute cycle is audited for carbon neutrality.

**Academia & Research**

* Messiah’s Nodes-as-a-Service model supports labs and funds with reliable compute and validator infrastructure.
* Tailored for collaborative projects and secure data management.

## Roadmap

**Phase 1: The Birth (MVP)**

* NodeHub MVP launched with one-click node setup.
* RPC nodes supported.
* Pre-seed round closed.
* Token and contracts audited by Hacken.
* Strategic partnerships onboarded.
* Fractionalized nodes & APY rewards live.
* Messiah Agent MVP released.

**Phase 2: Extended Capabilities (Beta)**

* Messiah Token launch & smart contract deployment.
* Multi-chain support expansion.
* Bulk node management & real-time APY tracking.
* MYE predictive models for yield optimization.
* MessiahCompute MVP with ZK support.
* Premium education, knowledge base & priority support.

**Phase 3: Scaling Intelligence and Infrastructure**

* CEX listing of Messiah Token.
* 100+ chains supported in NodeHub.
* Node Portfolio Manager with AI-powered insights.
* Passive yield strategies & mentorship programs.
* DevHub Beta for developers.
* Expanded token utility for governance, fees, and priority access.

**Phase 4: Owning the Edge (Messiah L1 & Autonomous Infrastructure)**

* Messiah Layer 1 chain launch (testnet & devnet).
* Validator staking, gas payments, and AI agent credits.
* Distributed LLM agent network.
* Automated Node Launchpad for startups.
* Fully automated deployment via natural language prompts.
* Quant Infra for trading venues & dark pools.
* ESG Validator Rewards & tokenized carbon credits.
* Cross-platform oracles to power governance and smart contracts.

## Conclusion

Messiah is more than infrastructure — it’s a **movement towards a decentralized, censorship-resistant, and sustainable digital future**. By combining one-click node deployment, fractionalized ownership, and AI-driven yield optimization, Messiah bridges the gap between today’s centralized limitations and tomorrow’s decentralized opportunities.

Whether you’re a casual user, developer, institution, or researcher — Messiah provides the **tools to Build, Deploy, and Earn** in the next era of Web3.


# MoonPay (/integrations/moonpay)

---
title: MoonPay
category: Fiat On-Ramp
available: ["C-Chain", "All EVM L1s"]
description: MoonPay is a financial technology company that provides payment infrastructure for cryptocurrencies, enabling easy fiat-to-crypto on-ramp and off-ramp solutions.
logo: /images/moonpay.png
developer: MoonPay
website: https://www.moonpay.com/
documentation: https://dev.moonpay.com/docs/on-ramp-overview
---

## Overview

MoonPay is a global payment infrastructure that enables seamless cryptocurrency purchases using traditional payment methods. It provides a comprehensive fiat-to-crypto and crypto-to-fiat solution that can be integrated into any application, allowing users to buy cryptocurrencies with credit cards, debit cards, bank transfers, Apple Pay, Google Pay, and other local payment methods. MoonPay handles the entire payment process, including compliance, fraud prevention, and liquidity, making it easy for developers to offer a smooth crypto experience to their users.

## Features

- **Global Reach**: Available in 160+ countries with support for 80+ fiat currencies.
- **Extensive Crypto Support**: Support for 100+ cryptocurrencies, including custom tokens for L1 networks.
- **Multiple Payment Methods**: Credit/debit cards, bank transfers, Apple Pay, Google Pay, and region-specific payment options.
- **Complete On/Off-Ramp Solution**: Both buy (on-ramp) and sell (off-ramp) functionality to create a full-circle user experience.
- **Crypto Swaps**: Allow users to exchange one cryptocurrency for another with competitive rates.
- **Customizable Widget**: White-label solution that can be styled to match your application's branding.
- **NFT Checkout**: Direct purchase of NFTs with fiat currencies.
- **Advanced Compliance**: Built-in KYC and AML processes with multiple verification levels.
- **Fraud Prevention**: Sophisticated risk management system to prevent fraudulent transactions.
- **Multi-Platform SDK Support**: Native SDKs for web, iOS, Android, and React Native applications.
- **Enterprise-Grade Security**: SOC 2 Type 2 certified infrastructure with the highest security standards.

## Getting Started

To integrate MoonPay into your application:

1. **Register for an Account**: Sign up on the [MoonPay Developer Dashboard](https://dashboard.moonpay.com/) to get your API credentials.

2. **Choose Integration Method**: MoonPay offers several integration options:

   - **Widget Integration**: The simplest approach, using a pre-built widget:
     ```javascript
     const moonpayUrl = new URL('https://buy.moonpay.com');
     moonpayUrl.searchParams.append('apiKey', 'YOUR_API_KEY');
     moonpayUrl.searchParams.append('currencyCode', 'avax');
     moonpayUrl.searchParams.append('walletAddress', userWalletAddress);
     
     window.open(moonpayUrl.href, '_blank');
     ```

   - **Web SDK Integration**: For more control and a seamless experience:
     ```bash
     npm install @moonpay/moonpay-web-sdk
     ```
     
     ```javascript
     import { MoonPayWebSdk } from '@moonpay/moonpay-web-sdk';
     
     const moonpay = new MoonPayWebSdk({
       flow: 'buy',
       environment: 'production', // or 'sandbox' for testing
       variant: 'overlay', // or 'embedded'
       params: {
         apiKey: 'YOUR_API_KEY',
         currencyCode: 'avax',
         walletAddress: userWalletAddress,
         baseCurrencyCode: 'usd',
         baseCurrencyAmount: 100,
         externalTransactionId: 'YOUR_TRANSACTION_ID', // Optional 
         theme: 'light', // or 'dark'
         showWalletAddressForm: true,
         lockAmount: false
       }
     });
     
     // Open the widget
     moonpay.show();
     
     // Listen to events
     moonpay.on('onClose', () => {
       console.log('Widget closed');
     });
     
     moonpay.on('onTransactionSuccess', (data) => {
       console.log('Transaction created:', data);
     });
     ```

   - **React SDK**:
     ```bash
     npm install @moonpay/moonpay-react-sdk
     ```
     
     ```jsx
     import { MoonPayProvider, useMoonPaySdk } from '@moonpay/moonpay-react-sdk';
     
     function BuyButton() {
       const { showWidget } = useMoonPaySdk();
       
       const handleClick = () => {
         showWidget({
           flow: 'buy',
           params: {
             apiKey: 'YOUR_API_KEY',
             currencyCode: 'avax',
             walletAddress: userWalletAddress
           }
         });
       };
       
       return <button onClick={handleClick}>Buy AVAX</button>;
     }
     
     function App() {
       return (
         <MoonPayProvider>
           <BuyButton />
         </MoonPayProvider>
       );
     }
     ```

3. **Implement Webhooks**: Set up webhooks to receive transaction status updates:
   ```javascript
   // Example server-side webhook handler (Express.js)
   app.post('/moonpay-webhook', (req, res) => {
     const event = req.body;
     
     if (event.type === 'transaction_complete') {
       // Handle completed transaction
     }
     
     res.sendStatus(200);
   });
   ```

4. **Test in Sandbox**: Use the sandbox environment to test your integration before going live.

## Documentation

For comprehensive integration guides, API references, and webhooks setup, visit the [MoonPay Developer Documentation](https://dev.moonpay.com/docs/on-ramp-overview).

## Use Cases

MoonPay can enhance various blockchain applications:

**Cryptocurrency Wallets**: Enable direct crypto purchases within your wallet application.

**NFT Marketplaces**: Allow users to purchase NFTs directly with credit cards and other payment methods.

**DeFi Platforms**: Provide a seamless on-ramp for users to acquire tokens needed for DeFi services.

**Web3 Applications**: Reduce friction in user onboarding by integrating a native fiat entry point.

**Blockchain Games**: Enable players to purchase in-game assets without navigating external exchanges.

## Pricing

MoonPay operates on a transaction fee model:

- **Fee Range**: Typically 1% to 4.5% per transaction, depending on payment method and region
- **Custom Fee Structure**: Enterprise solutions with customizable fee arrangements
- **White-Label Solutions**: Premium pricing for fully branded solutions
- **Volume Discounts**: Available for high-volume partners

For detailed pricing information and enterprise solutions, contact MoonPay's sales team.

## Conclusion

MoonPay provides a robust and comprehensive fiat-to-crypto infrastructure that can significantly enhance the user experience in blockchain applications. By handling the complex aspects of payment processing, compliance, and liquidity, MoonPay allows developers to focus on their core product while providing users with a seamless way to enter and exit the crypto ecosystem. With its global reach, extensive payment options, and customizable integration, MoonPay is an ideal solution for any blockchain project looking to reduce friction in the user onboarding process. 

# Moralis (/integrations/moralis)

---
title: Moralis
category: RPC Providers
available: ["C-Chain"]
description: Moralis is a leading crypto data provider that helps companies build great user experiences and drive engagement, growth, and revenue in their applications through Moralis’ suite of APIs and Moralis Nodes. 
logo: /images/moralis.png
developer: Moralis
website: https://moralis.io/
documentation: https://docs.moralis.io/
---

## Overview
Moralis is a leading crypto data provider that helps companies build great user experiences and drive engagement, growth, and revenue in their applications through Moralis’ suite of APIs and Moralis Nodes. These scalable, cross-chain data products - such as the NFT API, Wallet API, Token API, Price API, Blockchain API, Moralis Streams, and Moralis Nodes - seek to bridge the development gap between Web2 and Web3.

## Features
- **[NFT API](https://moralis.io/api/nft/)**: Seamlessly integrate NFT functionalities into your application with Moralis' NFT API. Access comprehensive data on NFTs across multiple blockchains, including metadata, ownership details, and transaction history, to create engaging and feature-rich NFT experiences for your users.
- **[Wallet API](https://moralis.io/api/wallet/)**: Empower your users with real-time access to their wallet data through Moralis' Wallet API. Retrieve information on balances, transaction history, and token holdings across different blockchains, enabling seamless wallet management and enhancing user engagement.
- **[Token API](https://moralis.io/api/token/)**: Leverage Moralis' Token API to fetch detailed information on any token, including prices, transfers, and historical data. This API supports a wide range of tokens across multiple blockchains, making it easier for you to build versatile applications that utilize token data.
- **[Price API](https://moralis.io/api/price/)**: Ensure your application always displays accurate and up-to-date market information with Moralis' Price API. Get real-time and historical price data for various cryptocurrencies, enabling your users to make informed decisions in a volatile market.
- **[Blockchain API](https://moralis.io/api/blockchain/)**: Simplify your development process with Moralis' Blockchain API, which provides seamless access to blockchain data such as blocks, transactions, and smart contract events.
- **[Moralis Streams](https://moralis.io/streams/)**: Keep your application up-to-date with real-time blockchain data using Moralis Streams. Receive instant notifications for transactions and events on your chosen blockchain, enhancing user engagement and application responsiveness.
- **[Moralis Nodes](https://moralis.io/nodes/)**: Experience superior performance with Moralis Nodes across a wide range of blockchains, featuring 99.9% uptime, response times as low as 70 ms, and SOC 2 Type II certification.
- **[SOC 2 Type II Compliance](https://moralis.io/Security/)**: Rely on Moralis for secure and compliant operations with SOC 2 Type II certification, ensuring top-tier data security and privacy.
- **[Cross-Chain Compatibility](https://moralis.io/chains/)**: Build on multiple blockchains effortlessly with Moralis, supporting seamless integration across various protocols to expand your app's reach.
- **[Scalability](https://moralis.io/scale/)**: Scale your application efficiently with Moralis' infrastructure, built to handle high transaction volumes and support millions of users with ease. With Moralis, companies have saved up to 87% on time-to-market and $86.4M in engineering costs, backed by 24/7 global support.


## Getting Started
1. **Sign Up**: Create a free account on the [Moralis website](https://moralis.io/).
2. **Access the Dashboard**: Log in to your Moralis account to access the admin dashboard.
3. **Get Your API Key**: Navigate to the settings section to find your API key, which is essential for making requests to Moralis services.
4. **Integrate with Your Project**: Use the API key and SDK to leverage Moralis' powerful suite of APIs. You can either use the provided SDKs or make direct HTTP requests to interact with Moralis APIs.
5. **Explore Moralis APIs**: Familiarize yourself with the various APIs available, such as Wallet API, NFT API, and Token API, by visiting the [Moralis Documentation](https://docs.moralis.io/) to enhance your application's functionality.

## Documentation
For more details on getting started, tutorials and API references, visit the [Moralis Documentation](https://docs.moralis.io/)

## Use Cases
- **[Crypto Tax & Accounting](https://moralis.io/solutions/crypto-tax/)**: Build accurate tax and accounting platforms with Moralis, leveraging precise blockchain data from APIs and nodes for reliable financial reporting.
- **[Wallet Portfolio Management](https://moralis.io/solutions/wallets/)**: Offer users a complete view of their wallet balances, including native assets, ERC-20 tokens, NFTs, and DeFi holdings with Moralis' comprehensive data.
- **[DeFi Applications](https://moralis.io/solutions/defi/)**: Enhance your DeFi dapp with fast, reliable on-chain data from Moralis, streamlining integration and improving user experience.
- **[Efficient Data Retrieval](https://moralis.io/api/)**: Use Moralis' enriched APIs to minimize API calls, enabling robust and feature-rich DeFi applications with efficient data handling.
- **[Multi-Chain Dapps](https://moralis.io/chains/)**: Develop versatile dapps with Moralis' cross-chain capabilities, supporting multiple blockchain networks for expanded functionality.
- **[NFT Marketplaces](https://moralis.io/api/nft/)**: Build engaging NFT marketplaces with Moralis' APIs, providing real-time data on NFT ownership, metadata, and transactions.
- **[GameFi Development](https://moralis.io/api/)**: Create blockchain-based games (GameFi) with Moralis, integrating NFTs, tokens, and smart contracts for interactive gameplay.
- **[Analytics & Insights](https://moralis.io/api/)**: Develop platforms offering detailed blockchain analytics and insights, including transaction data and market trends, with Moralis' tools.
- **[Real-Time Notifications](https://moralis.io/streams/)**: Implement instant updates for blockchain transactions and events with Moralis Streams, keeping users informed and engaged.


## Conclusion
The integration of Moralis into your blockchain projects offers a transformative approach to decentralized application development. By leveraging Moralis's powerful Web3 APIs and infrastructure, developers can significantly enhance their productivity and streamline the development process.

# AuditAgent (/integrations/nethermind-auditagent)

---
title: AuditAgent
category: Developer Tools
available: ["C-Chain", "All EVM L1s"]
description: AuditAgent is an AI-powered smart contract security agent that proactively detects vulnerabilities and provides continuous monitoring for Solidity projects.
logo: /images/auditagent.png
developer: Nethermind
website: https://auditagent.nethermind.io/
documentation: https://docs.auditagent.nethermind.io/
---

## Overview

AuditAgent is an autonomous, AI-driven security platform from **Nethermind** that helps developers discover and fix vulnerabilities in their smart contracts *before* they go live. Leveraging machine-learning models, symbolic execution, and a continuously-updated knowledge base of exploits, AuditAgent delivers rapid, actionable insights, making secure development a default rather than an after-thought.

## Features

- **AI-Driven Vulnerability Detection** – Combines static analysis, dynamic testing, and large-language-model reasoning to identify re-entrancy, arithmetic errors, access-control flaws, and more.
- **Continuous Monitoring** – Watches repositories and deployed addresses, rescanning automatically whenever code changes or new bytecode is detected.
- **Human-Readable Reports** – Generates detailed findings with severity classifications, PoC transactions, and clear remediation guidance.
- **CI/CD Integrations** – Native GitHub Actions workflow and REST API let teams fail builds on new critical issues and gate deployments behind security checks.
- **Multi-Chain Support** – Optimised for Avalanche’s C-Chain and any EVM-compatible Layer 1.

## Getting Started

1. **Sign Up / Log In** – Visit the [AuditAgent dashboard](https://auditagent.nethermind.io/) and authenticate with GitHub, GitLab, or email.
2. **Create a Project** – Point AuditAgent at a public repo, upload Solidity sources, or paste an address to analyse deployed bytecode.
3. **Run Your First Scan** – Click *Start Scan* and wait a few minutes while AuditAgent performs AI-backed analysis of your codebase.
4. **Review Findings** – Examine the vulnerability list, severity breakdown, and remediation tips. Export the report as JSON, PDF, or SARIF.
5. **Automate** – Add AuditAgent to your pipeline using the provided GitHub Action or REST API for on-push security gates.

## Documentation

For full API reference, configuration options, and CI/CD examples, visit the [AuditAgent Docs](https://docs.auditagent.nethermind.io/).

## Use Cases

- **Pre-Audit Preparation** – Catch low-hanging issues early and reduce the cost and turnaround time of formal audits.
- **Ongoing Security Monitoring** – Continuously track contract changes post-deployment to guard against new risks introduced by upgrades or dependencies.
- **Developer Education** – Leverage detailed explanations and code snippets to upskill engineers on secure-coding best practices.
- **Compliance & Reporting** – Export machine-readable SARIF results for governance dashboards and regulatory submissions.

## Conclusion

AuditAgent brings the speed of AI to smart-contract security, giving Avalanche builders instant feedback and continuous protection across the entire development lifecycle. Integrate it into your workflow to ship faster—confident that your contracts are battle-tested and secure.


# Nethermind (/integrations/nethermind)

---
title: Nethermind
category: Security Audits
available: ["C-Chain", "All EVM L1s"]
description: "Nethermind offers good-quality security audits with deep Ethereum expertise and a 20% discount for Avalanche ecosystem projects."
logo: /images/nethermind.png
developer: Nethermind
website: https://nethermind.io/
---

## Overview

Nethermind is a blockchain development company offering good-quality security audits for projects building on Avalanche. With deep expertise in Ethereum and EVM-compatible chains, their team provides comprehensive security assessments that leverage their experience as both security researchers and blockchain developers. Avalanche ecosystem projects can benefit from a 20% discount when working with Nethermind.

## Features

- **Smart Contract Audits**: Thorough code reviews and vulnerability assessments.
- **Protocol Security**: Comprehensive analysis of protocol design and implementation.
- **20% Ecosystem Discount**: Referral discount for Avalanche ecosystem projects.
- **Developer Perspective**: Security insights informed by active blockchain development experience.
- **EVM Expertise**: Deep understanding of EVM internals and security implications.
- **Ethereum Background**: Extensive experience with Ethereum and EVM-compatible chains.
- **Client Implementation Experience**: Unique insights from building Ethereum clients.

## Getting Started

To engage Nethermind for security audits:

1. **Initial Contact**: Reach out through their website to discuss your audit requirements.
2. **Mention Ecosystem**: Reference the Avalanche ecosystem for the available referral discount.
3. **Audit Process**: 
   - Scope definition and planning
   - Comprehensive code review
   - Vulnerability identification and classification
   - Detailed remediation recommendations
4. **Report Delivery**: Receive a detailed audit report with findings and security guidance.
5. **Implementation Support**: Optional assistance with addressing identified vulnerabilities.

## Use Cases

Nethermind security audits are particularly valuable for:

- **EVM-Based Projects**: Benefit from their deep EVM expertise.
- **Layer 2 Solutions**: Security assessment of layer 2 implementations.
- **Cross-Chain Applications**: Review of bridge and cross-chain mechanisms.
- **DeFi Protocols**: Thorough evaluation of financial smart contracts.
- **Avalanche Ecosystem Projects**: Access to quality audits with ecosystem discount.

## Conclusion

Nethermind provides good-quality security audits with particular strength in EVM expertise derived from their experience as blockchain developers. Their unique perspective as both security researchers and blockchain implementers offers valuable insights that may not be available from security-only firms. With a 20% discount available for Avalanche ecosystem projects, Nethermind delivers professional security services with a developer-informed approach to vulnerability assessment and remediation. 

# OKX OS (/integrations/okxos)

---
title: OKX OS
category: Wallet SDKs
available: ["C-Chain"]
description: A comprehensive onchain infrastructure suite for building and scaling applications.
logo: /images/okx.png
developer: OKX
website: https://www.okx.com/web3/build
documentation: https://www.okx.com/web3/build/docs/waas/okx-waas-what-is-waas
---

## Overview

OKX OS is the most comprehensive onchain infrastructure suite that provides developers with a full set of tools, SDKs, and APIs to build and scale applications across over 100 chains without limitations. It leverages the same technology that powers the OKX Wallet, serving millions of users and processing more than 400 million daily API calls.

## Features

- **One-stop solution**: The most extensive suite of tools and APIs for building complex onchain experiences across any chain, from wallets to games, exchanges, and collections.
- **Multi-chain support and liquidity aggregation**: Access to over 100 chains and aggregate liquidity across multiple networks, DEXs, and major marketplaces for maximum flexibility and faster market entry.
- **Bitcoin-friendly**: Unique tools for Inscriptions, Ordinals, Runes, Fractal Bitcoin, and other emerging Bitcoin-based innovations.
- **Industry-leading security**: Leverages OKX's robust security measures and audited processes, enabling developers to build with confidence.
- **Proven scalability**: Designed for fast-growth applications, as evidenced by OKX's ecosystem serving millions of users and handling over 400 million daily API calls.

## Getting Started

Developers can start using OKX OS for free today by visiting the [OKX Build Portal](https://www.okx.com/web3/build). The platform provides comprehensive tools, SDKs, and APIs to help you quickly build and scale your applications across multiple chains.

## Documentation

For detailed documentation and guides, please visit the [OKX OS Documentation](https://www.okx.com/web3/build).

## Use Cases

- Building multi-chain wallets with seamless transaction management.
- Integrating cross-chain swaps and liquidity aggregation into decentralized applications.
- Creating NFT marketplaces with real-time data and marketplace integrations.
- Developing blockchain games with in-game asset management across 100+ chains.
- Accessing comprehensive onchain data APIs for actionable insights.

### Building an On-Chain Data Dashboard for Avalanche C-Chain

This guide walks you through setting up a dashboard to track wallet assets and transactions on the Avalanche C-Chain. You'll use OKX OS's Wallet API to fetch and display this data.

#### Prerequisites
- [Node.js](https://nodejs.org/) installed on your system
- Basic understanding of JavaScript and async/await
- An OKX Developer account

#### Setting Up Your Development Environment

1. **Log in to the Developer Portal**: Sign up for an account on the [OKX Developer Portal](https://www.okx.com/web3/build/dev-portal).

2. **Create a New Project**: Click on the `Create new project` button and fill in the required details. Once the project is created, you will receive a `Project ID`. Keep it for future reference.

3. **Generate API Keys**: Once your project is created, click the `Manage` and then `Create API key` buttons to create a new API key. Fill in the required details and click `Create`. You will receive an `API Key` and `API Secret`. Keep your `API Key`, `API Secret`, and `Passphrase` for future use.

> **Note**: Keep your Project ID, API Key, Secret, and Passphrase secure by storing them in environment variables or a secure storage solution. It is recommended to never share these credentials publicly or commit them to your codebase.

4. **Initialize a New Project**:
Run the following commands to create a new directory and initialize a Node.js project with default settings and required dependencies:

```bash
mkdir avalanche-dashboard
cd avalanche-dashboard
npm init -y
npm install crypto-js
```

Create three script files:
```bash
touch createAccount.js getAssets.js getTx.js
```

## Create Wallet Account

You'll start by creating an account to track your Avalanche addresses with a simple Node.js script that interacts with the OKX Wallet API.

In the `createAccount.js` file:
   
```javascript
const CryptoJS = require("crypto-js");

const createWallet = async () => {
    // Generate timestamp in ISO format
    const timestamp = new Date().toISOString();
    const method = "POST";
    const path = "/api/v5/wallet/account/create-wallet-account";

    // Prepare the body first as we need it for signature
    const body = {
        addresses: [
            {
                chainIndex: "43114",
                address: "0x2eFB50e952580f4ff32D8d2122853432bbF2E204",
            },
            // You can add more addresses and chain indexes 
            // {
            //     chainIndex: "1",
            //     address: "0x2eFB50e952580f4ff32D8d2122853432bbF2E204",
            // },
            // {
            //     chainIndex: "43114",
            //     address: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
            // },
        ],
    };

    // Generate signature
    // timestamp + method + path + body
    const signString = timestamp + method + path + JSON.stringify(body);
    const signature = CryptoJS.enc.Base64.stringify(
        CryptoJS.HmacSHA256(signString, "YOUR API SECRET KEY"),
    );

    const response = await fetch(
        "https://www.okx.com/api/v5/wallet/account/create-wallet-account",
        {
            method: "POST",
            headers: {
                "Content-Type": "application/json",
                "OK-ACCESS-PROJECT": "YOUR PROJECT ID",
                "OK-ACCESS-KEY": "YOUR API KEY",
                "OK-ACCESS-SIGN": signature,
                "OK-ACCESS-PASSPHRASE": "YOUR API PASSPHRASE",
                "OK-ACCESS-TIMESTAMP": timestamp,
            },
            body: JSON.stringify(body),
        },
    );

    const data = await response.json();
    return data;
};

// Example usage:
createWallet()
    .then((response) => console.log("Success:", response))
    .catch((error) => console.error("Error:", error));
```

Before running the script, replace these placeholder values with your actual credentials:
```javascript
"YOUR API SECRET KEY" → Your API Secret
"YOUR PROJECT ID" → Your Project ID
"YOUR API KEY" → Your API Key
"YOUR API PASSPHRASE" → Your Passphrase
```

Run your script:
```bash
node createAccount.js
```

You should see a success message with the response data if the account is created successfully.

For example,
```bash
Success: { code: '0', message: 'success', data: { accountId : 'Y7489xxxx-xxxx-xxxx-xxxx-xxxxxxaa652c' } }
```

## Check Wallet Assets

Now that we have an account, you can fetch the token balances. This script will show you all tokens held by your tracked addresses.

In your `getAssets.js` file:

1. Copy this code to `getAssets.js`:

```javascript
const CryptoJS = require("crypto-js");

    const getRequestUrl = (baseUrl, path, params = null) => {
        const url = new URL(baseUrl + path);
        if (params) {
            Object.keys(params).forEach((key) =>
                url.searchParams.append(key, params[key]),
            );
        }
        return url.toString();
    };

    const apiBaseUrl = "https://www.okx.com";
    const getAssetsParams = {
        accountId: "ACCOUNT ID FROM PREVIOUS STEP", // Replace with your accountId
    };

    const timestamp = new Date().toISOString();
    const method = "GET";
    const path = "/api/v5/wallet/asset/wallet-all-token-balances";
    const queryString = `?accountId=${getAssetsParams.accountId}`;

    // Generate signature
    const signString = timestamp + method + path + queryString;
    const signature = CryptoJS.enc.Base64.stringify(
        CryptoJS.HmacSHA256(signString, "YOUR API SECRET KEY"),
    );

    const headersParams = {
        "Content-Type": "application/json",
        "OK-ACCESS-PROJECT": "YOUR PROJECT ID",
        "OK-ACCESS-KEY": "YOUR API KEY",
        "OK-ACCESS-SIGN": signature,
        "OK-ACCESS-PASSPHRASE": "YOUR API PASSPHRASE",
        "OK-ACCESS-TIMESTAMP": timestamp,
    };

    const getAssetsData = async () => {
        const apiRequestUrl = getRequestUrl(apiBaseUrl, path, getAssetsParams);

        const response = await fetch(apiRequestUrl, {
            method: "GET",
            headers: headersParams,
        });

        return response.json();
    };

    // Use it
    getAssetsData()
        .then(({ data }) => {
            console.log("\n=== Wallet Assets ===\n");

            data.forEach((wallet) => {
                // Convert timestamp to readable date
                const date = new Date(parseInt(wallet.timeStamp));
                console.log(`Last Updated: ${date.toLocaleString()}\n`);

                console.log("Token Assets:");
                wallet.tokenAssets.forEach((token) => {
                    console.log(`
    Token: ${token.symbol}
    Chain: ${token.chainIndex}
    Balance: ${token.balance}
    -----------------------------`);
                });
            });
        })
        .catch((error) => console.error("Error:", error));
```

Make sure to:
- Update the accountId with the one you received in Step 1
- Replace the API credentials with yours

Run the asset checker:
```bash
node getAssets.js
```

You should see the assets of the wallet account if the request is successful.

For example,
```bash
=== Wallet Assets ===

Last Updated: 10/24/2024, 7:23:20 PM

Token Assets:

Token: AVAX
Chain: 43114
Balance: 882338.9729422927
-----------------------------

Token: Sword
Chain: 43114
Balance: 100000
-----------------------------

Token: ERGC
Chain: 43114
Balance: 100000
-----------------------------


Token: MILO
Chain: 43114
Balance: 500000
-----------------------------
```


## View Transaction Details

Finally, you can set up transaction viewing. This script provides detailed information about any transaction on the Avalanche C-Chain.

In your `getTx.js` file:


```javascript
const CryptoJS = require("crypto-js");

const getRequestUrl = (baseUrl, path, params = null) => {
    const url = new URL(baseUrl + path);
    if (params) {
        Object.keys(params).forEach((key) =>
            url.searchParams.append(key, params[key]),
        );
    }
    return url.toString();
};

const apiBaseUrl = "https://www.okx.com";
const params = {
    txHash: '0xaf54d1cb2c21bed094095bc503ec76128f80c815db8631fd74c6e49781b94bd1', // Changed from txhash to txHash
    chainIndex: '43114'
};

const timestamp = new Date().toISOString();
const method = "GET";
const path = '/api/v5/wallet/post-transaction/transaction-detail-by-txhash';
const queryString = `?txHash=${params.txHash}&chainIndex=${params.chainIndex}`; // Changed from txhash to txHash

const signString = timestamp + method + path + queryString;
const signature = CryptoJS.enc.Base64.stringify(
    CryptoJS.HmacSHA256(signString, "YOUR API SECRET"),
);

const headersParams = {
    "Content-Type": "application/json",
    "OK-ACCESS-PROJECT": "YOUR PROJECT ID",
    "OK-ACCESS-KEY": "YOUR API KEY",
    "OK-ACCESS-SIGN": signature,
    "OK-ACCESS-PASSPHRASE": "YOUR API PASSPHRASE",
    "OK-ACCESS-TIMESTAMP": timestamp,
};

const getTransactionDetailData = async () => {
    const apiRequestUrl = getRequestUrl(apiBaseUrl, path, params);

    const response = await fetch(apiRequestUrl, {
        method: "GET",
        headers: headersParams,
    });

    return response.json();
};

const formatDate = (timestamp) => {
    return new Date(parseInt(timestamp)).toLocaleString();
};

const formatGas = (gas) => {
    return parseFloat(gas).toLocaleString();
};

getTransactionDetailData()
    .then((response) => {
        console.log('\n=== Transaction Details ===\n');

        if (response.code === "0" && response.data && response.data.length > 0) {
            const tx = response.data[0];

            // Transaction Basic Info
            console.log('📝 Basic Information');
            console.log('------------------');
            console.log(`Hash: ${tx.txhash}`);
            console.log(`Status: ${tx.txStatus.toUpperCase()}`);
            console.log(`Block: ${formatGas(tx.height)}`);
            console.log(`Time: ${formatDate(tx.txTime)}`);
            console.log(`Method ID: ${tx.methodId}`);
            console.log(`Chain: ${tx.chainIndex} (${tx.symbol})`);

            // Gas Info
            console.log('\n⛽ Gas Information');
            console.log('----------------');
            console.log(`Gas Limit: ${formatGas(tx.gasLimit)}`);
            console.log(`Gas Used: ${formatGas(tx.gasUsed)}`);
            console.log(`Gas Price: ${formatGas(tx.gasPrice)} Wei`);
            console.log(`Nonce: ${tx.nonce}`);

            // From Address
            console.log('\n📤 From Address');
            console.log('-------------');
            tx.fromDetails.forEach(from => {
                console.log(`Address: ${from.address}`);
                console.log(`Type: ${from.isContract ? 'Contract' : 'Wallet'}`);
            });

            // To Address
            console.log('\n📥 To Address');
            console.log('-----------');
            tx.toDetails.forEach(to => {
                console.log(`Address: ${to.address}`);
                console.log(`Type: ${to.isContract ? 'Contract' : 'Wallet'}`);
            });

            // Token Transfers
            if (tx.tokenTransferDetails && tx.tokenTransferDetails.length > 0) {
                console.log('\n🔄 Token Transfers');
                console.log('---------------');
                tx.tokenTransferDetails.forEach((transfer, index) => {
                    console.log(`\nTransfer #${index + 1}:`);
                    console.log(`Token: ${transfer.symbol}`);
                    console.log(`Amount: ${transfer.amount}`);
                    console.log(`From: ${transfer.from} ${transfer.isFromContract ? '(Contract)' : '(Wallet)'}`);
                    console.log(`To: ${transfer.to} ${transfer.isToContract ? '(Contract)' : '(Wallet)'}`);
                    console.log(`Contract: ${transfer.tokenContractAddress}`);
                });
            }

            // Internal Transactions (if any)
            if (tx.internalTransactionDetails && tx.internalTransactionDetails.length > 0) {
                console.log('\n💱 Internal Transactions');
                console.log('--------------------');
                tx.internalTransactionDetails.forEach((internal, index) => {
                    console.log(`\nInternal Transfer #${index + 1}:`);
                    console.log(`From: ${internal.from}`);
                    console.log(`To: ${internal.to}`);
                    console.log(`Amount: ${internal.amount} ${tx.symbol}`);
                    console.log(`Status: ${internal.state}`);
                });
            }

        } else {
            console.log('Status:', response.code);
            console.log('Message:', response.msg);
            console.log('Data:', response.data);
        }
    })
    .catch(error => console.error('Error:', error));
```

Update the script with:
- Your API credentials
- Any transaction hash you want to investigate

Check a transaction:
```bash
node getTx.js
```

You'll see a detailed breakdown including:
- Transaction basics
- Gas info
- Addresses involved
- Token transfers
- Internal transactions

## Conclusion

The Wallet API is one of 4 strong pillars within the OKX OS infrastructure, complemented by the [DEX API] for decentralized trading capabilities, the [Marketplace API] for NFT functionalities, and the [Explorer API] for comprehensive blockchain data access and analysis. Together, these APIs form a complete toolkit that enables developers to build sophisticated Web3 applications with enterprise-grade reliability and performance.

By leveraging OKX OS's powerful infrastructure suite, developers can build and scale innovative onchain applications quickly and efficiently. With its extensive tools, multi-chain support, and proven scalability, OKX OS continues to drive the future of Web3 development, making it easier than ever to create seamless experiences across the blockchain ecosystem.

[DEX API]: https://www.okx.com/web3/build/docs/waas/dex-introduction
[Marketplace API]: https://www.okx.com/web3/build/docs/waas/marketplace-introduction
[Explorer API]: https://www.oklink.com/docs/en/#introduction

# Olympix (/integrations/olympix)

---
title: "Olympix"
category: ["Security Tooling"]
available: ["C-Chain", "All EVM L1s"]
description: "Olympix is an institutional-grade proactive security suite for smart contract developers, providing automated vulnerability detection and testing integrated into developer workflows."
logo: /images/olympix.png
developer: "Olympix.ai"
website: https://olympix.ai
documentation: https://olympix.github.io
---

## Overview


[Olympix](https://www.olympix.ai) is the only institutional-grade proactive security suite for Web3, purpose-built to identify and prevent vulnerabilities before audits or deployment. Its proprietary architecture (including a custom compiler, intermediate representation (IR), and symbolic execution engine), not LLM-wrappers, powers tools like static analysis, unit test generation, mutation testing, and automated POC generation.


By integrating directly into developer environments (VS Code, GitHub CI/CD), Olympix helps teams catch vulnerabilities early, strengthen audit readiness, and reduce the time and cost of achieving secure deployment on Avalanche and other EVM-compatible chains.

## Features

- Static Analyzer: Detects critical vulnerabilities early in development using advanced symbolic execution and proprietary detectors.

- Unit Test Generation: Automatically generates test suites to improve coverage and resilience of smart contracts.
- Mutation Testing: Measures the robustness of unit tests by simulating bad commits and highlighting which edge cases go undetected.
- Internal Audit Agent: Generates and audit-style report complete with POCs to prove the exploitability of findings.
- Developer Integration: Embedded within IDEs and CI/CD for continuous, proactive security.
- Audit Readiness: Hardens test suites (out of scope of typical audit), reduces audit findings by up to 60%, and shortens remediation cycles.
- Institutional-Grade Precision: 300% better benchmarking performance versus open-source alternatives.


## Getting Started 


To start using Olympix:
1. Visit [Olympix](https://olympix.ai) to request access or schedule a demo.
2. Install the Olympix VS Code or GitHub CI/CD integration.
3. Run static analysis, unit test generation, mutation testing, and internal audit agent on your Avalanche-based smart contracts. 
4. Review findings and fix issues before audit and before deployment.


## Use Cases

Olympix is ideal for:
1. DeFi Protocols: Secure high-value contracts and mitigate risk before audits.
2. Bridges and Cross-Chain Projects: Identify logic and invariant vulnerabilities across EVM environments.
3. Enterprises and Financial Institutions: Embed compliance-grade security early in tokenization and on-chain deployments.
4. Developers on Avalanche: Leverage proactive tooling to minimize risk and accelerate secure releases.

## Conclusion

Olympix brings enterprise-grade, proactive security to Avalanche’s developer ecosystem. By identifying vulnerabilities early and automating testing, it helps projects reduce exploit risk, save audit costs, and build trust with users. Olympix is designed for builders who want to secure smart contracts before audits, enabling safer, faster, and more confident on-chain development.

## Contact us
For more information, please visit [Olympix](https://olympix.ai) and [contact](https://www.olympix.ai/get-started-enterprise) us.


# Omniscia (/integrations/omniscia)

---
title: Omniscia
category: Security Audits
available: ["C-Chain", "All EVM L1s"]
description: "Omniscia provides good-quality security audits with efficient processes and competitive rates for projects on Avalanche."
logo: /images/omniscia.jpeg
developer: Omniscia
website: https://omniscia.io/
---

## Overview

Omniscia is a security audit provider offering good-quality assessments for blockchain projects building on Avalanche. Known for their efficient processes and competitive rates, Omniscia delivers thorough security reviews while maintaining a focus on accessibility and practical value. Their team provides comprehensive audits with relatively low lead times, making them suitable for projects with time-sensitive deployment schedules.

## Features

- **Smart Contract Audits**: Comprehensive code reviews and vulnerability assessment.
- **Efficient Process**: Streamlined audit procedures with relatively low lead times.
- **Competitive Pricing**: Accessible rates with potential referral discounts.
- **20% Referral Discount**: Available referral discount for Avalanche ecosystem projects.
- **Protocol Security**: Analysis of protocol design and implementation.
- **Practical Remediation**: Actionable guidance for addressing security issues.
- **Verification Services**: Validation of security fixes after implementation.

## Getting Started

To engage Omniscia for security audits:

1. **Initial Contact**: Reach out through their website to discuss your security needs.
2. **Mention Referral**: Reference the Avalanche ecosystem for potential referral discounts.
3. **Audit Process**: 
   - Scope definition and planning
   - Comprehensive code review
   - Vulnerability identification and classification
   - Documentation of findings
4. **Report Delivery**: Receive a detailed audit report with security recommendations.
5. **Optional Follow-up**: Verification of implemented security improvements.

## Use Cases

Omniscia security audits are particularly suitable for:

- **Time-Sensitive Projects**: Benefit from relatively efficient audit processes.
- **DeFi Applications**: Security assessment of financial smart contracts.
- **NFT Platforms**: Audit of NFT-related contract implementations.
- **Budget-Conscious Projects**: Access to good-quality audits with competitive pricing.
- **Avalanche Ecosystem Projects**: Potential referral discounts available.

## Conclusion

Omniscia provides good-quality security audits with a focus on efficiency and accessibility. Their competitive rates and 20% referral discount for Avalanche ecosystem projects make professional security services available to a wider range of projects. While their audit process is relatively efficient, Omniscia maintains good technical standards in their security assessments, helping projects identify and address vulnerabilities before deployment. 

# OnFinality (/integrations/onfinality)

---
title: OnFinality
category: RPC Providers
available: ["C-Chain","P-Chain","X-Chain"]
description: Blockchain Infrastructure Made Smarter. OnFinality empowers web3 developers with easy-to-use, reliable, and scalable blockchain infrastructure.
logo: /images/onfinality.png
developer: OnFinality
website: https://onfinality.io
---

## Overview

OnFinality empowers web3 developers with easy-to-use, reliable, and scalable blockchain infrastructure. OnFinality supports an enormous range of networks across a broad suite of blockchain tooling including RPC Nodes, Dedicated Nodes, Validators, Data Indexers, and AI Agents - making OnFinality your complete blockchain infrastructure platform

## Features

- **Generous Free Tier**: Try for free with our generous [free plan](https://onfinality.io/en/pricing)
- **Avalanche Native**: Complete set of Avalanche endpoints including all chains, web sockets, and ETH + AVAX
- **Lightning Fast**: Our Avalanche RPC endpoints are served by a global fleet of nodes, ensuring the lowest possible latency for time sensitive tasks and a snappy user experience
- **Enterprise Nodes**: Dedicated Avalanche nodes and [load balanced clusters](https://blog.onfinality.io/onfinality-enterprise-nodes-series-blockchain-load-balancer/) for the most demanding enterprise needs like bridges and exchanges.
- **Data Indexers**: Deploy Subgraph and SubQuery data indexers on [OnFinality Indexing](https://indexing.onfinality.io/login)
- **Endpoint Security**: Secure your private endpoint to only accept requests from specific origins or IP addresses.
- **Analytics and Insights**: Gain insights into how your application is performing and where your users are.

## Getting Started

To start using OnFinality:

1. **Sign Up**: Create an account with [OnFinality](https://app.onfinality.io/signup)
2. **Create your API App**: After signing in, create an API App and select the Avalanche network
4. **Copy your Private Avalanche Endpoint**: Copy your C-chain, P-Chain, or X-Chain endpoints. Web Socket is also supported.
5. **Monitor and Optimize**: Utilize OnFinality's Network Insights to track your app's performance and make changes - with analytics down to the method.

## Documentation

[OnFinality Documentation](https://documentation.onfinality.io/support/api-service)

## Use Cases

- **Bridges** requiring high availability connections between Avalanche and other blockchain networks.
- **Explorers and Scanners** who need full archive access with high throughput for historical backfills.
- **Decentralized Applications (dApps)** serving global Avalanche users 24/7
- **Exchanges and Custodial Services** who know that downtime and delays cost their customers

## Conclusion

OnFinality is the right choice for teams of all sizes who need a complete suite of Avalanche infrastructure and exceptional, personalised support.

Talk to us now at support@onfinality.io, we'd love to hear from you!

# Openfort (/integrations/openfort)

---
title: Openfort
category: ["Account Abstraction"]
available: ["C-Chain", "All EVM L1s"]
description: "Create secure embedded wallets with seamless authentication flows and gas sponsorship capabilities."
logo: /images/openfort.png
developer: Openfort
website: https://openfort.io
documentation: https://www.openfort.io/docs
---

## Overview
[Openfort](https://openfort.io) is an open-source alternative to wallet infrastructure solutions. The core offerings—Openfort Kit, Invisible Wallet, and Cross-app Wallet - enable rapid integration of wallet functionality, intuitive onboarding, and flexible user journeys for any application or ecosystem.

### [Openfort Kit](https://www.openfort.io/docs/products/kit/react/quickstart)

Openfort Kit is a developer toolkit that streamlines the integration of wallet authentication and connectivity into any web application. It provides:

- **Plug-and-play UI Components**: Prebuilt, customizable authentication and wallet connection flows that can be deployed in minutes, not weeks, with support for major authentication providers and wallet connector
- **Developer Experience**: TypeScript-ready, ecosystem-standard libraries (wagmi, viem), and easy integration with frameworks like React, Next.js, and Create React App.
- **Full Customization**: Predesigned themes or the ability to fully tailor the UI to match your brand.

### [Invisible Wallet](https://www.openfort.io/docs/products/embedded-wallet/javascript)

Invisible Wallet enables applications to onboard users without requiring them to interact directly with traditional wallet interfaces. Features include:

- **Embedded Non-custodial Signer**: Secure, self-custodied wallet creation and signing for users, with no need for browser extensions or external apps.
- **Fundign Support**: Users can onramp their newly created wallets with traditional methods or depositing crypto. 
- **Key Export**: Users can always export private keys, allowing them to take the wallet with them.

### [Cross-app Wallet](https://www.openfort.io/docs/products/cross-app-wallet/setup)

The Cross-app Wallet empowers ecosystems and platforms to offer branded, interoperable wallets that work across multiple apps and services. Key capabilities:

- **Ecosystem SDK**: Build your own wallet SDK that can be integrated across your suite of apps, ensuring users have a consistent identity and asset management experience everywhere.
- **No App or Extension Required**: Users can create and use wallets instantly via iFrames or embedded flows, compatible with any EVM chain.
- **Modern Standards**: Supports the latest Ethereum standards (EIP-1193, 6963, 7702, 4337, and more) for broad compatibility and future-proofing.

## Getting Started

### 1. Installation

```bash
# Install dependencies
npm install @openfort/openfort-js @openfort/openfort-node
npm install ethers viem
```

### 2. Configuration

```typescript
// Initialize Openfort with client and server configurations
// Client side
const openfortClient = new Openfort({
  baseConfiguration: {
    publishableKey: "YOUR_OPENFORT_PUBLISHABLE_KEY",
  },
  shieldConfiguration: {
    shieldPublishableKey: "YOUR_SHIELD_PUBLISHABLE_KEY",
  },
});

// Server side
const openfortServer = new Openfort("YOUR_SECRET_KEY");
```

### 3. Basic Implementation

```typescript
// Authentication
const authResponse = await openfort.logInWithEmailPassword({
  email: "user@example.com",
  password: "password123"
});

// Initialize Provider
const provider = await openfort.getProvider();
await provider.request({ 
  method: 'wallet_switchEthereumChain',
  params: [{ chainId: `0x${avalancheChain.id.toString(16)}` }]
});

// Create a gas sponsorship policy (server-side)
const policy = await openfortServer.policies.create({
  chainId: 43114, // Avalanche C-Chain
  name: "Gas Sponsorship Policy",
  strategy: {
    sponsorSchema: "pay_for_user"
  }
});

// Create transaction intent with sponsorship (server-side)
const transactionIntent = await openfortServer.transactionIntents.create({
  player: "PLAYER_ID",
  chainId: 43114,
  optimistic: true,
  policy: policy.id,
  interactions: [{
    contract: "CONTRACT_ADDRESS",
    functionName: "transfer",
    functionArgs: [recipientAddress, amount]
  }]
});

// Sign and send the sponsored transaction (client-side)
const response = await openfortClient.sendSignatureTransactionIntentRequest(
  transactionIntent.id,
  transactionIntent.nextAction.payload.userOperationHash
);
```

## Documentation
For detailed implementation guides and API references, visit [Openfort Documentation](https://www.openfort.io/docs)


# OpenZeppelin (/integrations/openzeppelin)

---
title: OpenZeppelin
category: Security Audits
available: ["C-Chain", "All EVM L1s"]
description: "OpenZeppelin provides high-quality security audits for smart contracts with additional auditing hours for community contributions."
logo: /images/openzeppelin.png
developer: OpenZeppelin
website: https://www.openzeppelin.com/security-audits
documentation: https://docs.openzeppelin.com/
---

## Overview

OpenZeppelin is a leading security firm specializing in smart contract security, best known for their widely-used secure contract libraries and security tools. They provide high-quality audits for projects building on Avalanche, combining manual code review with automated analysis. OpenZeppelin's team includes smart contract experts with extensive experience in identifying vulnerabilities and recommending secure development practices.

## Features

- **Smart Contract Audits**: Comprehensive review of smart contract code and architecture.
- **Security Research**: Continuous research on smart contract vulnerabilities and security patterns.
- **Architecture Review**: Assessment of system architecture and security design.
- **Best Practice Guidance**: Recommendations aligned with industry security standards.
- **Community Contributions**: Additional auditing hours available for community-focused projects.
- **Library Expertise**: Deep knowledge of secure smart contract patterns and libraries.
- **Custom Tooling**: Development and use of specialized security tools.

## Getting Started

To engage OpenZeppelin for security audits:

1. **Request an Audit**: Contact OpenZeppelin through their website to initiate the process.
2. **Scope Definition**: Collaborate to define the audit scope, timeline, and objectives.
3. **Audit Process**: 
   - Manual code review by security experts
   - Automated analysis using proprietary and open-source tools
   - Vulnerability identification and classification
   - Detailed remediation guidance
4. **Report Delivery**: Receive a comprehensive audit report with detailed findings.
5. **Optional Follow-up**: Post-audit verification of implemented fixes.

## Use Cases

OpenZeppelin security audits are particularly suitable for:

- **DeFi Protocols**: Thorough validation of financial smart contracts.
- **Open Source Projects**: Security reviews with potential for additional community-focused audit hours.
- **Projects Using OpenZeppelin Libraries**: Specialized expertise in reviewing implementations that build on their libraries.
- **EVM-Based Smart Contracts**: Deep expertise in EVM specifics and security implications.
- **Governance Systems**: Review of DAO and governance contract implementations.

## Conclusion

OpenZeppelin provides high-quality security audits with specific expertise in smart contract security and EVM environments. Their deep understanding of secure contract patterns and experience with their widely-used libraries make them particularly valuable for projects building smart contracts on Avalanche's C-Chain and EVM-compatible L1s. For community-oriented projects, they may offer additional auditing hours, providing extended value and thorough security coverage. 

# Paladin (/integrations/paladin)

---
title: Paladin
category: Security Audits
available: ["C-Chain", "All EVM L1s"]
description: "Paladin provides high-quality security audits for blockchain projects with competitive pricing and specialized expertise."
logo: /images/paladin.png
developer: Paladin
website: https://paladinsec.co/
---

## Overview

Paladin is a high-quality security auditor offering comprehensive smart contract and protocol audits for projects building on Avalanche. They combine technical expertise with competitive pricing, providing accessibility to professional security services. Projects can reach out to Paladin directly and may be eligible for referral discounts when working with them through the Avalanche ecosystem.

## Features

- **Smart Contract Audits**: Thorough code reviews and vulnerability assessments.
- **Protocol Security**: Comprehensive analysis of protocol design and implementation.
- **Competitive Pricing**: Professional audit services at accessible price points.
- **Referral Program**: 10% referral discount available through Avalanche ecosystem.
- **Technical Expertise**: Team with deep knowledge of blockchain security challenges.
- **Remediation Support**: Guidance on addressing identified vulnerabilities.
- **Verification Services**: Confirmation of security fixes and improvements.

## Getting Started

To engage Paladin for security audits:

1. **Initial Outreach**: Projects can reach out to Paladin through their website.
2. **Mention Avalanche**: Reference the Avalanche ecosystem for potential referral discounts.
3. **Audit Process**: 
   - Scope definition and planning
   - Comprehensive code review
   - Vulnerability identification and classification
   - Detailed findings documentation
4. **Report Delivery**: Receive a comprehensive audit report with findings and recommendations.
5. **Fix Verification**: Optional validation of implemented security fixes.

## Use Cases

Paladin security audits are particularly suitable for:

- **DeFi Applications**: Smart contract and protocol audits for financial applications.
- **NFT Projects**: Security assessment of NFT-related contracts and marketplaces.
- **Governance Systems**: Review of governance and voting contract implementations.
- **Startup Projects**: Access to professional security audits with competitive pricing.
- **Avalanche Ecosystem Projects**: Benefit from referral discounts and Avalanche-specific expertise.

## Conclusion

Paladin provides high-quality security audits with a focus on accessibility and comprehensive assessment. Their competitive pricing model and referral program make professional security services more accessible to projects of various sizes building on Avalanche. With technical expertise and a thorough approach to security auditing, Paladin helps projects identify and address potential vulnerabilities before they can be exploited. 

# PancakeSwap (/integrations/pancakeswap)

---
title: PancakeSwap
category: DEX Liquidity
available: ["C-Chain"]
description: "PancakeSwap is a leading DEX offering token swaps, yield farming, and perpetual trading on Avalanche's C-Chain with gamified features."
logo: /images/pancakeswap.jpeg
developer: PancakeSwap
website: https://pancakeswap.finance/
documentation: https://docs.pancakeswap.finance/
---

## Overview

PancakeSwap is a popular decentralized exchange that has expanded to Avalanche's C-Chain, bringing its comprehensive suite of DeFi services including token swaps, yield farming, and perpetual trading. Known for its user-friendly interface and gamified features, PancakeSwap combines serious DeFi functionality with an engaging user experience.

## Features

- **Smart Router**: Intelligent routing system for optimal trade execution and better rates.
- **Perpetual Trading**: Up to 100x leverage trading with competitive fees.
- **Stable Swaps**: Optimized pools for stablecoin trading with minimal slippage.
- **Yield Farming**: Multiple opportunities to earn CAKE and other tokens.
- **Fixed-Term Staking**: Flexible and fixed-term staking options for CAKE.
- **NFT Ecosystem**: Integration of NFTs with trading and farming features.
- **IFO (Initial Farm Offering)**: Launch platform for new projects.

## Getting Started

To begin using PancakeSwap on Avalanche:

1. **Access Platform**: Visit [PancakeSwap](https://pancakeswap.finance/) and switch to Avalanche network.
2. **Connect Wallet**: Link your Web3 wallet and ensure you have AVAX for gas fees.
3. **Start Trading**: 
   - Select tokens for swapping
   - Review exchange rate and slippage
   - Confirm transaction
4. **Explore Features**: Discover farming, staking, and perpetual trading options.

## Documentation

For detailed guides and technical documentation, visit the [PancakeSwap Documentation](https://docs.pancakeswap.finance/).

## Use Cases

PancakeSwap serves various DeFi needs:

- **Token Swapping**: Efficient token exchanges with competitive rates.
- **Perpetual Trading**: Access to leveraged trading with deep liquidity.
- **Yield Generation**: Multiple farming and staking opportunities.
- **Project Launches**: Platform for new token launches through IFO.
- **Stablecoin Trading**: Optimized pools for stablecoin swaps.

## Conclusion

PancakeSwap brings its proven DEX model to Avalanche's C-Chain, offering users a full suite of DeFi services with an engaging interface. Whether you're looking to trade tokens, provide liquidity, or engage in perpetual trading, PancakeSwap provides a comprehensive platform that combines serious DeFi functionality with an accessible user experience.

# Pangolin (/integrations/pangolin)

---
title: Pangolin
category: DEX Liquidity
available: ["C-Chain"]
description: "Pangolin is a community-driven decentralized exchange for Avalanche and Ethereum assets with fast settlement, low transaction fees, and a democratic distribution."
logo: /images/pangolin.jpeg
developer: Pangolin DAO
website: https://pangolin.exchange/
documentation: https://docs.pangolin.exchange/
---

## Overview

Pangolin is a decentralized exchange (DEX) built on Avalanche, offering fast and cost-effective trading of Avalanche and Ethereum assets. As a community-driven platform, Pangolin emphasizes democratic governance and fair token distribution while providing essential DeFi services including swapping, yield farming, and liquidity provision.

## Features

- **Fast Settlement**: Leverage Avalanche's quick finality for near-instant trade settlement.
- **Low Transaction Fees**: Benefit from Avalanche's C-Chain efficiency for reduced trading costs.
- **Cross-Chain Trading**: Trade both Avalanche-native and Ethereum assets.
- **Yield Farming**: Earn rewards through liquidity provision and farming opportunities.
- **Community Governance**: Participate in platform decisions through the PNG governance token.
- **User-Friendly Interface**: Simple and intuitive trading interface for all user levels.

## Getting Started

To begin using Pangolin:

1. **Connect Wallet**: Visit [Pangolin Exchange](https://pangolin.exchange/) and connect your Web3 wallet.
2. **Fund Your Wallet**: Ensure you have AVAX for transaction fees.
3. **Start Trading**: 
   - Select tokens to trade
   - Review rates and slippage
   - Confirm transaction
4. **Provide Liquidity**: Optionally, add liquidity to earn trading fees and PNG rewards.

## Documentation

For detailed guides and technical documentation, visit the [Pangolin Documentation](https://docs.pangolin.exchange/).

## Use Cases

Pangolin serves various DeFi needs:

- **Token Swaps**: Quick and efficient token exchanges on Avalanche.
- **Liquidity Provision**: Earn yields by providing liquidity to trading pairs.
- **Yield Farming**: Access additional rewards through farming programs.
- **Cross-Chain Access**: Trade Ethereum-based assets on Avalanche.
- **DAO Participation**: Engage in platform governance through PNG token.

## Conclusion

Pangolin provides a robust, community-driven DEX solution on Avalanche's C-Chain, combining efficient trading with democratic governance. Whether you're looking to swap tokens, provide liquidity, or participate in yield farming, Pangolin offers a comprehensive suite of DeFi services with the speed and cost advantages of the Avalanche network.

# Parallel Markets (/integrations/parallel-markets)

---
title: Parallel Markets
category: KYC / Identity Verification
available: ["C-Chain"]
description: Parallel Markets provides comprehensive KYC/AML solutions with a portable identity system ideal for crypto platforms implementing txAllowlist precompiles.
logo: /images/parallel-markets.png
developer: Parallel Markets
website: https://parallelmarkets.com/
documentation: https://developer.parallelmarkets.com/
---

## Overview

Parallel Markets offers a suite of streamlined identity verification and compliance solutions designed for financial institutions and blockchain platforms. Their innovative KYC (Know Your Customer) and AML (Anti-Money Laundering) tools verify user identities without the traditional friction in onboarding processes. For blockchain applications implementing txAllowlist precompiles, Parallel Markets provides a portable identity solution that enables users to verify once and access multiple platforms, creating a seamless experience while maintaining robust compliance.

## Features

- **Portable Identity Verification**: Users can complete KYC verification once and reuse their verified credentials across platforms in the Parallel Markets ecosystem.
- **Comprehensive KYC/AML Screening**: Automated verification against global sanctions lists, PEP (Politically Exposed Persons) databases, and adverse media sources.
- **Business Verification (KYB)**: Verify corporate entities, map beneficial ownership structures, and perform due diligence checks for institutional users.
- **No-Code Integration**: Implement identity verification with minimal development resources through their JavaScript SDK or API integration.
- **Real-Time Monitoring**: Continuous monitoring of user profiles for changes in risk status or sanctions exposure.
- **Customizable Verification Flows**: Design verification journeys specific to your platform's risk profile and regulatory requirements.
- **Dashboard Analytics**: Access verification results and monitor compliance metrics through a unified dashboard.

## Getting Started

To integrate Parallel Markets into your Avalanche-based application with txAllowlist precompiles, follow these steps:

1. **Account Setup**: Contact Parallel Markets to create an account and obtain API credentials.
2. **Integration Planning**: Choose between JavaScript SDK for frontend integration or direct API calls from your backend.
3. **Configure Verification Flow**: Set up your verification requirements based on your compliance needs.
4. **Implementation**: Follow the [documentation](https://developer.parallelmarkets.com/) to add the verification flow to your application.
5. **Testing**: Verify the integration in a sandbox environment before going live.
6. **Verification-to-Allowlist Mapping**: Connect user verification status to your txAllowlist management to ensure only verified users can transact.

## Integration with txAllowlist

Parallel Markets is particularly well-suited for platforms implementing txAllowlist precompiles because:

1. **Streamlined Allowlisting**: When a user completes verification through Parallel Markets, your application can automatically add their wallet address to the txAllowlist.
2. **Verification Status Monitoring**: If a user's compliance status changes (e.g., they appear on a sanctions list), your application can receive webhook notifications and remove their address from the allowlist.
3. **Programmatic Control**: The API-driven approach allows for complete automation of the allowlist management based on identity verification results.
4. **Reduced Onboarding Friction**: Users who have already verified with another platform in the Parallel Markets ecosystem can be fast-tracked through your verification process.

## Documentation

Comprehensive integration guides and API documentation are available in the [Parallel Markets Developer Documentation](https://developer.parallelmarkets.com/). The documentation includes details on:

- JavaScript SDK implementation
- Server-side API integration
- Webhook setup for status notifications
- Testing and sandbox environments
- Handling verification results

## Use Cases

Parallel Markets' identity verification solutions are ideal for various Avalanche-based applications:

- **Permissioned DeFi Protocols**: Ensure participants in lending or trading pools meet regulatory requirements.
- **Tokenized Securities**: Verify investor accreditation status and identity for compliant security token offerings.
- **Enterprise Blockchains**: Create permissioned networks with verified corporate and individual participants.
- **Regulated Exchanges**: Build compliant DEXs that satisfy regulatory requirements while maintaining a good user experience.
- **Cross-Chain Applications**: Apply consistent compliance standards across multiple blockchain networks.

## Conclusion

Parallel Markets offers a powerful solution for blockchain platforms looking to implement identity verification alongside txAllowlist precompiles. By providing a portable, user-friendly verification system that maintains high compliance standards, Parallel Markets enables platforms to create secure, regulated environments without sacrificing the user experience. The combination of their verification tools with Avalanche's txAllowlist functionality creates a comprehensive solution for building compliant blockchain applications. 

# Particle Network (/integrations/particle-network)

---
title: Particle Network
category: Chain Abstraction
available: ["C-Chain"]
description: Chain abstraction powered by Universal Accounts. One account, one balance, any chain.
logo: /images/particle-network.png
developer: Particle Network
website: https://particle.network/
documentation: https://developers.particle.network/intro/introduction
---

## **Overview**

Particle Network enables **chain abstraction** through its **Universal Accounts** infrastructure, giving users a unified account and balance. This allows them to interact with your Avalanche dApp with assets from any supported chain (EVM chains and Solana) without bridging. 

Universal Accounts also abstract away network switching and gas management, allowing users to pay gas with any token. Thanks to this, Particle Network delivers a truly chain-agnostic experience where liquidity can be deployed on any chain, independently of where the user holds funds.

Within Universal Accounts users’ assets are also automatically combined, allowing them to deposit tokens from multiple chains and spend them as if they were in the same chain.

## **Features**

* **Universal Accounts**: One account and one balance across all supported chains—no need to bridge or switch networks.  
* **Chain Abstraction**: Handle multi-chain logic like transfers, payments, and smart contract interactions at the account level, not the chain level.  
* **Multi-Chain Support**: Works with nearly all EVM chains and Solana, with new integrations added frequently.  
* **Developer Flexibility**: Compatible with common tools like ethers, wagmi, and viem.

## **Getting Started**

To integrate **Universal Accounts** into your application:

1. **Initialize the Universal Accounts SDK** using your API key from the [Particle Dashboard](https://dashboard.particle.network/).  
2. **Fetch the user’s universal address and unified balance** – a single address and balance valid across all chains.  
3. **Build and send UserOperations** using any supported network.  
4. **Deploy your chain-agnostic app** – users can now transact across ecosystems with a single unified account.

[Check out the Quickstart](https://developers.particle.network/universal-accounts/cha/web-quickstart) for more details.

## **Use Cases**

Particle Network empowers developers to create frictionless, multi-chain applications for a wide variety of use cases. These, and the benefits of UAs for them, include: 

* **DeFi Platforms**: Multi-chain deposits, cross-chain swaps, paying gas in any currency, and allowing users to combine their liquidity from different chains.  
* **Blockchain Games**: Web2-like onboarding via social logins, with full on-chain settlement and deposits/withdrawals to/from any chain.  
* **NFT Marketplaces**: Cross-chain spending (deposit assets from one chain, buy/mint in another) and combined ownership/listing of NFTs from multiple chains.  
* **Fintech & Payments**: Allowing users to pay gas in any token, simplified stablecoin-centric interfaces.  
* **Others**: Given Universal Accounts multi-dApp ecosystem, ability for users to use their UAs across a number of apps.

## **Supported Chains**

Universal Accounts currently support most **EVM chains and Solana**, and will soon support all major Avalanche L1s.

View the full list: [Network Coverage](https://developers.particle.network/universal-accounts/cha/chains)

## **Community**

* **Universal Accounts on Avalanche**: [Retail-friendly UX: Accepting stablecoins from any chain on Avalanche dapps](https://blog.particle.network/retail-friendly-ux-accepting-stablecoins-from-any-chain-on-avalanche-dapps/)  
* **Slack**: [Join Particle’s Slack](https://join.slack.com/t/particlenetworkhq/shared_invite/zt-3blxdzcd2-7skD8MNWUn_20eOrp9SICA)  
* **GitHub**: [Particle Network GitHub](https://github.com/particle-network)

## **TL;DR for Developers**

If you want your users to:

* Log in once  
* Use a single account and balance across all chains  
* Skip network switching, bridging, and gas management

Then you’re looking for **chain abstraction**.

You’re looking for **Universal Accounts**.

Start building → [Universal Accounts SDK](https://developers.particle.network/universal-accounts/cha/overview)

# PayAI (/integrations/payai)

---
title: PayAI
category: x402
available: ["C-Chain"]
description: PayAI offers the x402 protocol, a payment infrastructure that enables monetization of AI agents and services on Avalanche.
logo: /images/payai.svg
developer: PayAI
website: https://payai.network/
documentation: https://docs.payai.network/introduction
---

## Overview

PayAI provides the x402 protocol, a comprehensive payment infrastructure designed specifically for AI agent monetization and service payments on Avalanche's C-Chain.

The x402 protocol standardizes how AI agents and services can accept payments, making it easier for developers to build monetized AI applications without worrying about complex payment infrastructure.

## What is x402?

The x402 protocol is a payment standard that facilitates transactions between:
- **Merchants**: AI service providers and agents that offer paid services
- **Clients**: Users or applications that consume AI services
- **Facilitators**: Infrastructure that handles payment processing on Avalanche

## Key Features

- **Avalanche Native**: Built to leverage Avalanche's fast finality and low transaction costs
- **Simple Integration**: SDKs available in TypeScript and Python for both merchants and clients
- **Facilitator Network**: PayAI operates facilitators that handle payment routing on Avalanche
- **AI-First Design**: Built specifically for AI agent monetization and service payments

## Getting Started

### For Merchants (AI Service Providers)

If you're building an AI service or agent that needs to accept payments on Avalanche:

1. **Choose Your SDK**: PayAI provides SDKs in both TypeScript and Python
2. **Set Up Payment Endpoints**: Configure your service to accept x402 protocol payments on Avalanche
3. **Configure for Avalanche**: Use the `avalanche` network string for mainnet or `avalanche-fuji` for testnet
4. **Start Accepting Payments**: Your AI agent can now receive payments for services in AVAX

### For Clients (Service Consumers)

If you're building an application that consumes paid AI services on Avalanche:

1. **Install the Client SDK**: Available in TypeScript and Python
2. **Configure for Avalanche**: Set up payments using Avalanche C-Chain
3. **Connect to Services**: Start paying for AI services through the x402 protocol with AVAX

## Use Cases

### AI Agent Monetization
Enable your AI agents to charge for their services on a per-request or subscription basis.

### Freelance AI Services
Build marketplaces where AI agents can offer specialized services and receive payment automatically.

### Token-Gated AI Access
Create premium AI services that require payment to access, with automated payment verification.

### CT (Crypto Twitter) Agent Monetization
Monetize AI agents that provide crypto analysis, trading signals, or social media insights.

## Documentation

For detailed implementation guides and API references:
- [PayAI Documentation](https://docs.payai.network/introduction)
- [Supported Networks](https://docs.payai.network/x402/supported-networks)

## Integration Examples

### Express Server Example

Set up an Express server that accepts x402 payments on Avalanche:

**Environment Variables (.env)**

```bash
FACILITATOR_URL=https://facilitator.payai.network
NETWORK=avalanche-fuji # or avalanche for mainnet
ADDRESS=0x... # wallet public address you want to receive payments to
```

**Server Code (index.ts)**

```typescript
import { config } from "dotenv";
import express from "express";
import { paymentMiddleware, Resource } from "x402-express";
config();

const facilitatorUrl = process.env.FACILITATOR_URL as Resource;
const payTo = process.env.ADDRESS as `0x${string}`;

if (!facilitatorUrl || !payTo) {
  console.error("Missing required environment variables");
  process.exit(1);
}

const app = express();

app.use(
  paymentMiddleware(
    payTo,
    {
      "GET /weather": {
        // USDC amount in dollars
        price: "$0.001",
        network: "avalanche-fuji", // or "avalanche" for mainnet
      },
      "/premium/*": {
        // Define atomic amounts in any EIP-3009 token
        price: {
          amount: "100000",
          asset: {
            address: "0xabc",
            decimals: 18,
            eip712: {
              name: "WETH",
              version: "1",
            },
          },
        },
        network: "avalanche-fuji", // or "avalanche" for mainnet
      },
    },
    {
      url: facilitatorUrl,
    },
  ),
);

app.get("/weather", (req, res) => {
  res.send({
    report: {
      weather: "sunny",
      temperature: 70,
    },
  });
});

app.get("/premium/content", (req, res) => {
  res.send({
    content: "This is premium content",
  });
});

app.listen(4021, () => {
  console.log(`Server listening at http://localhost:${4021}`);
});
```

## Avalanche C-Chain Integration

When deploying x402 on Avalanche's C-Chain:

- **Network String**: Use `avalanche` for mainnet or `avalanche-fuji` for testnet
- **Native Token**: AVAX is used for gas fees
- **Fast Finality**: Benefit from Avalanche's sub-second transaction finality
- **Low Fees**: Enable micropayments for AI services with minimal transaction costs

## Conclusion

PayAI's x402 protocol makes it simple to build monetized AI services on Avalanche. Whether you're creating AI agents that need to earn revenue or building applications that consume paid AI services, x402 provides the payment infrastructure you need to get started quickly. With Avalanche C-Chain's fast finality and low transaction costs, you can enable seamless micropayments for AI services.



# Privy (/integrations/privy)

---
title: Privy
category: Wallet SDKs
available: ["C-Chain", "All EVM L1s"]
description: "Spin up embedded wallets and beautiful authentication flows for all users."
logo: /images/privy.png
developer: Privy
website: https://privy.io/
documentation: https://docs.privy.io/
---

## What is Privy?
Privy is a simple tool to easily onboard all your users to web3, regardless of whether they already have a wallet, across mobile and desktop.

## Terminology
Before we dive into the guide, let's first understand the terminology.


| Term | Meaning |
| -------- | ------- |
| Social Login | Social Login is a form of single sign-on (SSO) that allows users to log into a third-party website or app using their existing credentials from a social media platform, such as Google, X (formerly Twitter), or Apple. Instead of creating a new username and password, users can authenticate themselves through their social media accounts, streamlining the login process. |
| Magic Link | A Magic Link is a form of passwordless authentication where users can log into an application or website by clicking a unique, time-sensitive link sent to their email address. This method eliminates the need for a traditional username and password combination, making the login process simpler and more user-friendly. |
| Next.js  | Next.js’ Pages Router is a full-stack React framework. It’s versatile and lets you create React apps of any size—from a mostly static blog to a complex dynamic application. |


## Prerequisites and Recommended Knowledge

- Privy account
- Basic understanding of EVM, and transaction data
- Basic understanding of frontend development

## Preparation

### Create Application and Retrieve API Keys

- Log in to [Privy Dashboard](https://dashboard.privy.io/)
- Click on `New App` on the Applications page.
- Click on the Settings button on the left pane. Under the Basic tab, you'll find the API keys.

### Start a New React Project with Next.js

To create a new Next.js project, run in your terminal:

```bash
npx create-next-app@latest
```

### Install Dependencies

After the React project is created, we need to install some dependencies: to use Privy (its own package), to add a custom chain, to create and use an HTTP client (viem), and to include utilities (ethers).

```bash
npm install @privy-io/react-auth@latest
npm i viem@latest
npm i ethers@latest
```

### Define Your Avalanche L1

In this guide, we are using the `Echo L1` as an example Avalanche L1. However, you can use any Avalanche L1 that has a public RPC URL. If the L1 has an explorer page, you can see better what is happening, but it is not required.

```typescript
export const echo = defineChain({
  id: 173750,
  name: 'Echo L1',
  network: 'echo',
  nativeCurrency: {
    decimals: 18,
    name: 'Ech',
    symbol: 'ECH',
  },
  rpcUrls: {
    default: {
      http: ['https://subnets.avax.network/echo/testnet/rpc']
    },
  },
  blockExplorers: {
    default: {name: 'Explorer', url: 'https://subnets-test.avax.network/echo'},
  },
});
```

### Import Privy into Your App 

After the React project is created, navigate to `page.tsx`. Inside the `Home` function, wrap your content with `PrivyProvider`.

```typescript title="page.tsx"
export default function Home() {

  return (
    <PrivyProvider
      appId="your-privy-app-id"
      config={{
        appearance: {
          theme: 'dark',
          accentColor: '#e84242',
          logo: 'https://your-logo-url',
        },
        embeddedWallets: {
          createOnLogin: 'users-without-wallets',
        },
        defaultChain: echo,
        supportedChains: [echo],
        loginMethods: ['email', 'wallet', 'google', 'apple']
      }}
    >
      { content }
    </PrivyProvider>
  );

}
```

## Walkthrough

So far in the guide, we have installed the necessary dependencies, created our Privy application, and obtained our API key. Now, we are ready to use Privy.

Here is our walkthrough:

- We will create a simple login flow.
- We will create a welcome page for users who have logged in, showing their embedded wallet address and balance.
- We will trigger a test transfer of the `ECH` token via Privy.

### Login Flow

To onboard your users into your application, you just need to know the following hooks:

```typescript
const { ready, authenticated } = usePrivy();
const { login } = useLogin();
```

It's really that simple!

- `ready`: Checks whether the `PrivyProvider` is `ready` to be used.
- `authenticated`: Returns `true` if the user is `authenticated`, `false` otherwise.
- `login`: Opens the Privy login modal and prompts the user to log in.

```typescript
<button onClick={login}>Login via Privy</button>
```

We've only added a button to trigger `login` function, and Privy handles the rest.


When we click on the `Login via Privy` button, this modal appears.


You can choose any login method to log in. We’ve already defined these options in the `PrivyProvider` when we wrapped our content.

### Welcome Page

After checking whether the user is authenticated or not, we display the following information to the user who has logged in.


As you can see, Privy has generated an embedded wallet for our user. We’ve displayed the following properties on the screen: Privy ID, embedded wallet address, and embedded wallet balance.

```typescript
<span>{user.id}</span>
<span>{user.wallet.address}</span>
<span>{balance} ECH</span>
```

We’ve used the user object of Privy to retrieve the user ID and wallet address. To fetch the user’s balance, we need to create an HTTP client for our Avalanche L1, which we’ve already defined earlier.

```typescript
const client = createPublicClient({
    chain: echo,
    transport: http(),
});
// get native asset balance
client.getBalance({
    address: address,
}).then(balance => {
    setBalance(ethers.formatEther(balance));
});
```

We can allow users to log out using the following hook:

```typescript
const { logout } = useLogout();
```

### Fund the New Wallet Using the Faucet

We’ve funded the new wallet that was generated for our user with some ECH tokens from the [Echo AWM Testnet Faucet](https://test.core.app/tools/testnet-faucet/?avalanche-l1=echo&token=echo).

After the ECH tokens were sent, our balance updated accordingly.


### Send Test Transfer via Privy

Now that we have a balance, we can send some ECH tokens to another recipient via Privy to test Privy's `sendTransaction` flow. Privy provides the following hook for this:

```typescript
const { sendTransaction } = useSendTransaction();
```

We’ve already added the following button to trigger the `transfer` function, which will, in turn, trigger the `sendTransaction` function provided by Privy.

```typescript
<button onClick={transfer}>Send Test Transfer via Privy</button>
```

We have built a simple transaction that sends some ECH tokens to another recipient.


```typescript
const transfer = () => {
    if (authenticated === false || address === undefined) {
        return;
    }
    let receiver = "0x..."; // receiver address
    sendTransaction({
        "value": ethers.parseUnits("0.01", "ether"),
        "to": receiver, // destination address
        "from": address, // logged in user's embedded wallet address
    }).catch(() => {
        // handle err 
    });
}
```

When we click on the `Send Test Transfer via Privy` button, this modal appears. Users can see the following details related to the transaction.


## Conclusion

What we achieved is the creation of a simple React project that integrates Privy. Our application can now easily onboard new users to our Web3 application without needing them to install a Web3 wallet extension, regardless of which chain they are on


# Pyth Network (/integrations/pyth)

---
title: Pyth Network
category: Oracles
available: ["C-Chain"]
description: Pyth Network is a decentralized oracle solution that provides high-fidelity data for DeFi applications.
logo: /images/pyth.png
developer: Pyth Network
website: https://pyth.network/
documentation: https://docs.pyth.network/
---

## Overview

Pyth Network is a decentralized oracle solution designed to provide high-fidelity data for decentralized finance (DeFi) applications. By leveraging a network of data providers and validators, Pyth Network delivers accurate and reliable real-world data, crucial for executing smart contracts and ensuring the integrity of DeFi platforms.

## Features

- **High-Fidelity Data**: Pyth Network aggregates and validates data from a diverse set of sources to ensure accuracy and reliability.
- **Decentralized Network**: Operates as a decentralized oracle network, reducing reliance on any single data source and increasing trustworthiness.
- **Real-Time Data**: Provides up-to-date data feeds for various assets, including cryptocurrencies, commodities, and equities.
- **Integration with DeFi**: Seamlessly integrates with DeFi applications, offering essential data for trading, lending, and other financial activities.

## Getting Started

To integrate Pyth Network into your application:

1. **Visit the Pyth Network Website**: Explore the [Pyth Network website](https://pyth.network/) to understand its offerings and capabilities.
2. **Access the Documentation**: Refer to the [Pyth Network Documentation](https://docs.pyth.network/) for detailed guides on integration, data feeds, and API usage.
3. **Integrate Data Feeds**: Use the provided APIs to integrate Pyth Network’s data feeds into your smart contracts and DeFi applications.
4. **Test and Deploy**: Test the integration in a development environment to ensure data accuracy and application functionality before deploying to production.

## Documentation

For detailed integration instructions, data feed options, and API references, visit the [Pyth Network Documentation](https://docs.pyth.network/).

## Use Cases

Pyth Network is ideal for applications that require accurate and timely real-world data:

- **Decentralized Finance (DeFi)**: Utilize Pyth Network’s data feeds for trading, lending, and other financial operations in DeFi platforms.
- **Risk Management**: Integrate real-time data into risk management systems for better decision-making and risk assessment.
- **Market Analytics**: Provide accurate market data for analysis and forecasting in various financial and trading applications.

## Conclusion

Pyth Network offers a robust decentralized oracle solution that provides high-fidelity data essential for DeFi applications. With its real-time data feeds and decentralized nature, Pyth Network ensures the accuracy and reliability of data used in smart contracts and financial operations. Whether you are building a DeFi platform or integrating market data, Pyth Network delivers the tools and resources needed for successful data management and application development.



# QuickNode (/integrations/quicknode)

---
title: QuickNode
category: RPC Providers
available: ["C-Chain"]
description: QuickNode is a blockchain developer platform that provides a suite of APIs and tools for building and scaling blockchain applications.
logo: /images/quicknode.png
developer: QuickNode
website: https://www.quicknode.com/
documentation: https://www.quicknode.com/docs
---

## Overview

QuickNode is a blockchain developer platform that offers a comprehensive suite of APIs and tools for building and scaling blockchain applications. It provides developers with reliable and scalable infrastructure to interact with blockchain networks, enabling efficient and effective development of decentralized applications.

## Features

- **Scalable APIs**: Access a range of APIs designed to handle high-throughput and low-latency requirements for blockchain interactions.
- **Multi-Chain Support**: Connect with various blockchain networks, including Ethereum, Binance Smart Chain, and others, through a unified platform.
- **Developer Tools**: Utilize advanced tools and services for building, monitoring, and optimizing blockchain applications.
- **Reliable Infrastructure**: Benefit from QuickNode’s high-performance infrastructure, ensuring reliable and consistent access to blockchain networks.
- **Analytics and Monitoring**: Track and analyze blockchain interactions with built-in monitoring and analytics tools.

## Getting Started

To start using QuickNode:

1. **Visit the QuickNode Website**: Explore the [QuickNode website](https://www.quicknode.com/) to understand its features and offerings.
2. **Access the Documentation**: Refer to the [QuickNode Documentation](https://www.quicknode.com/docs) for detailed guides on setting up and using QuickNode’s APIs and tools.
3. **Create an Account**: Sign up for a QuickNode account to gain access to API keys and start integrating blockchain functionality into your applications.
4. **Integrate APIs**: Use the provided APIs to interact with your desired blockchain networks, and implement features such as data retrieval, transaction submission, and more.
5. **Monitor and Optimize**: Utilize QuickNode’s monitoring and analytics tools to track performance and optimize your blockchain applications.

## Documentation

For detailed integration instructions, API references, and setup guides, visit the [QuickNode Documentation](https://www.quicknode.com/docs).

## Use Cases

QuickNode is suitable for various blockchain development scenarios:

- **Decentralized Applications (dApps)**: Build and scale dApps with QuickNode’s APIs and tools for efficient blockchain interactions.
- **Blockchain Analytics**: Use QuickNode’s monitoring and analytics tools to gain insights into blockchain data and application performance.
- **Smart Contract Development**: Develop, test, and deploy smart contracts with reliable infrastructure and scalable API access.
- **Transaction Management**: Manage and monitor blockchain transactions with high performance and low latency.

## Conclusion

QuickNode provides a powerful and flexible blockchain developer platform, offering a suite of APIs and tools for building and scaling blockchain applications. With its scalable infrastructure, multi-chain support, and advanced developer tools, QuickNode ensures efficient and effective blockchain development. Whether you’re creating dApps, analyzing blockchain data, or managing transactions, QuickNode delivers the resources and capabilities needed for success.



# Ramp Network (/integrations/ramp-network)

---
title: Ramp Network
category: Fiat On-Ramp
available: ["C-Chain", "All EVM L1s"]
description: Ramp Network is a global provider of fiat-to-crypto on-ramp and off-ramp infrastructure, enabling users to purchase and sell cryptocurrencies directly within applications.
logo: /images/ramp-network.png
developer: Ramp Network
website: https://ramp.network/
documentation: https://docs.ramp.network/
---

## Overview

Ramp Network is a leading fiat-to-crypto infrastructure provider that enables users to purchase and sell cryptocurrencies directly within blockchain applications. With a focus on regulatory compliance and user experience, Ramp offers a seamless on-ramp and off-ramp solution that can be integrated into any application with minimal developer effort. Ramp supports multiple payment methods across 150+ countries and provides a customizable widget that can be tailored to match your application's design.

## Features

- **Global Coverage**: Available in 150+ countries with localized payment methods and support for multiple currencies.
- **Diverse Payment Options**: Bank transfers, credit/debit cards, Apple Pay, Google Pay, and region-specific payment methods.
- **Full Off-Ramp Solution**: Complete selling experience allowing users to convert crypto back to fiat with direct bank deposits.
- **Customizable Widget**: White-labeled solution that can be styled to match your application's branding.
- **Low Integration Effort**: Simple SDK integration requiring just a few lines of code.
- **Multi-Platform Support**: Web SDK, React SDK, and mobile SDKs for iOS and Android.
- **Robust Compliance**: Built-in KYC and AML processes that meet regulatory requirements across jurisdictions.
- **Competitive Fees**: Transparent fee structure with some of the lowest rates in the industry.
- **Advanced Developer Tools**: Webhooks, callbacks, and detailed documentation for seamless integration.
- **Advanced Purchase Flows**: Support for automatic purchases and recurring purchases.

## Getting Started

To integrate Ramp into your application:

1. **Create an Account**: Register on the [Ramp Developer Dashboard](https://app.ramp.com/sign-in) to get your API key.

2. **Install the SDK**: For web applications, add the Ramp SDK to your project:
   ```bash
   npm install @ramp-network/ramp-instant-sdk
   ```

3. **Initialize the On-Ramp Widget**: Implement the widget in your application:
   ```javascript
   import { RampInstantSDK } from '@ramp-network/ramp-instant-sdk';
   
   const ramp = new RampInstantSDK({
     hostAppName: 'Your App Name',
     hostLogoUrl: 'https://yourdomain.com/logo.png',
     swapAsset: 'AVAX',
     swapAmount: '100000000000000000', // Optional, in wei
     userAddress: '0x...', // User's wallet address
     hostApiKey: 'YOUR_API_KEY',
     variant: 'auto', // or 'desktop', 'mobile', 'embedded'
     webhookStatusUrl: 'https://your-webhook-endpoint.com', // Optional
     defaultFlow: 'ONRAMP', // or 'OFFRAMP'
   });
   
   ramp.show();
   ```

4. **Implement Off-Ramp** (if needed):
   ```javascript
   import { RampInstantSDK } from '@ramp-network/ramp-instant-sdk';
   
   const ramp = new RampInstantSDK({
     hostAppName: 'Your App Name',
     hostLogoUrl: 'https://yourdomain.com/logo.png',
     swapAsset: 'AVAX',
     userAddress: '0x...', // User's wallet address
     hostApiKey: 'YOUR_API_KEY',
     variant: 'auto',
     defaultFlow: 'OFFRAMP',
   });
   
   ramp.show();
   ```

5. **Handle Events**: Listen for purchase events:
   ```javascript
   ramp.on('PURCHASE_CREATED', (event) => {
     console.log(`User started purchase: ${event.purchase.id}`);
   });
   
   ramp.on('PURCHASE_SUCCESSFUL', (event) => {
     console.log(`Purchase successful: ${event.purchase.id}`);
   });
   
   ramp.on('WIDGET_CLOSE', () => {
     console.log('Widget closed');
   });
   ```

6. **Test in Sandbox**: Use the sandbox environment to test your integration before going live:
   ```javascript
   const ramp = new RampInstantSDK({
     // ...your configuration
     url: 'https://ri-widget-staging.firebaseapp.com/', // Use staging environment
   });
   ```

## Documentation

For comprehensive integration guides, API references, and webhook setup, visit the [Ramp Documentation](https://docs.ramp.network/).

## Use Cases

Ramp can enhance various blockchain applications:

**Crypto Wallets**: Enable users to purchase crypto directly within your wallet application and cash out to their bank accounts.

**DeFi Platforms**: Provide a seamless entry and exit point for users to acquire and liquidate tokens needed for DeFi protocols.

**NFT Marketplaces**: Allow direct purchase of NFTs with fiat, simplifying the user journey.

**Blockchain Games**: Let players purchase in-game tokens or assets without needing to understand crypto exchanges.

**Enterprise Solutions**: Offer a compliant on/off-ramp solution for corporate blockchain applications.

## Pricing

Ramp operates on a transaction fee model:

- **Standard Fee Range**: 0.49% to 2.9% per transaction, depending on payment method and region
- **Volume Discounts**: Available for applications with high transaction volumes
- **Revenue Sharing**: Partnership opportunities for qualified integrators
- **No Monthly Fees**: Pay only for processed transactions

For specific pricing details and potential custom arrangements, contact Ramp's sales team.

## Conclusion

Ramp Network provides a comprehensive fiat-to-crypto infrastructure solution that can significantly enhance user experience in blockchain applications. By handling the complex compliance, payment processing, and liquidity management, Ramp allows developers to focus on their core product while providing users with a seamless way to enter and exit the crypto ecosystem. With its competitive fees, extensive global coverage, and flexible integration options, Ramp is an ideal solution for any project looking to reduce friction in user onboarding and provide a complete crypto experience. 

# Reactive Network (/integrations/reactive-network)

---
title: Reactive Network
category: Crosschain Solutions
available: ["C-Chain"]
description: "Reactive Network is a fully on-chain, EVM-compatible, events-driven if-this-then-that network for decentralized automation of on-chain workflows through enabling reactivity between contracts deployed either on the same or different chains."
logo: /images/Symbol_ColorBlack_H32.png
developer: PARSIQ
website: https://reactive.network/
documentation: https://dev.reactive.network
---

## Overview

Reactive Network is a fully on-chain, EVM-compatible, events-driven if-this-then-that network for decentralized automation of on-chain workflows through enabling reactivity between contracts deployed either on the same or different chains. Core purpose of Reactive is to enable more autonomous, self-sufficient and user friendly dApps.

## Features

- **Decentralized automation**: Web3’s first IFTTT infrastructure. Automate multi-chain workflows with event-driven logic – execute actions without compromising decentralization.
- **Cost-efficient Execution**: Offload heavy computations to Reactive’s parallelized EVM. Complex logic at minimal cost.
- **Inversion of Control**: RSCs invert the traditional execution model by allowing the contract itself to decide when to execute based on predefined events, eliminating the need for external triggers like bots or users.
- **DeFAI-Ready Infrastructure**: Create autonomous DeFi agents with on-chain data triggers and off-chain AI intelligence that trade, optimize, and adapt.

## Getting Started

To start using Reactive Network:

1. **Review Documentation**: Study the [Reactive Network Documentation](https://dev.reactive.network).
2. **Check out Reactive's [origins and destinations](https://dev.reactive.network/origins-and-destinations)**, along with their Callback Proxy addresses. 
3. **Connect to [Reactive Mainnet or Kopli Testnet](https://dev.reactive.network/reactive-mainnet)**.
4. **Explore what can be built**:
    - Hands-on [demonstrations](https://dev.reactive.network/demos) for the Reactive Network.
    - Clone the [GitHub](https://github.com/Reactive-Network/reactive-smart-contract-demos) project and start building.
5. **Learn more** about Reactive Smart Contracts in our [educational course](https://dev.reactive.network/education/introduction).

## Documentation

For comprehensive integration guides and technical details, visit the [Reactive Network Documentation](https://dev.reactive.network).

## Use Cases

Reactive Network supports a wide range of cross-chain automations:

- **Decentralized Trading Automation**: Automate gasless cross-chain swaps, enabling a frictionless P2P crypto trading experience.
- **Dynamic NFT Royalty System**: Enable real-time royalty adjustments, automate cross-chain transactions, and ensure transparent, fair revenue distribution for creators, buyers, and marketplaces.
- **Flash Profit Extractor**: Automate token swaps, dynamic pricing, and real-time price tracking, making DeFi arbitrage accessible and efficient.
- **Cross-Chain Lending**: Borrow assets across multiple blockchains.

## Conclusion

Reactive Network is an EVM-compatible execution layer that allows developers to create dApps using reactive contracts. These contracts differ from traditional smart contracts by using inversion-of-control for the transaction lifecycle, driven by data flows across blockchains rather than user input. Put simply - fully onchain, events driven if-this-then-that network for decentralized automation or simplification of workflows. Whether you're a seasoned or new blockchain developer, all you need is knowledge of Solidity. Reactive is not just a toolkit — it’s a new execution paradigm for Avalanche and beyond.


# RedStone Oracles (/integrations/redstone-oracles)

---
title: RedStone Oracles
category: Data Feeds
available: ["C-Chain"]
description: RedStone is a modular, gas-optimized oracle providing diverse and reliable price feeds for dApps.
logo: /images/RedStone.png
developer: RedStone Oracles
website: https://redstone.finance/
documentation: https://docs.redstone.finance/docs/introduction
---

## Overview

RedStone Oracles is a fast-growing modular oracle solution designed to provide gas-optimized and reliable price feeds across over 50 blockchain networks and rollups. Specializing in supporting yield-bearing collateral for lending markets, such as liquid staking tokens (LSTs) and liquid restaking tokens (LRTs), RedStone offers a scalable and flexible solution for decentralized finance (DeFi) platforms.

## Features

- **Modular and Flexible Oracle System**: RedStone’s architecture allows seamless integration of data feeds across multiple Layer 1 (L1), Layer 2 (L2), app chains, and non-EVM chains.
- **Gas-Optimized Data Feeds**: RedStone minimizes gas costs, reducing the expenses associated with putting data on the blockchain.
- **Diverse and Reliable Data Sources**: Data is aggregated from a wide range of sources, including directly from liquidity pools, ensuring accuracy of data.

## Getting Started

To integrate RedStone Oracles into your application:

1. **Visit the RedStone Website**: Explore the [RedStone Oracle website](https://redstone.finance/) to understand the range of services and integrations available.
2. **Access the Documentation**: Review the [RedStone Documentation](https://docs.redstone.finance/docs/introduction) for detailed guidance on selecting the right oracle model for your dApps.
3. **Integrate and Expand**: Implement RedStone’s data feeds in your smart contracts and reach out to the RedStone team for any support needed during the integration process.

## Documentation

For in-depth integration instructions, oracle model selection, and data feed details, visit the [RedStone Documentation](https://docs.redstone.finance/docs/introduction).

## Use Cases

RedStone Oracles is ideal for applications that require reliable and cost-efficient data feeds:

- **Traditional DeFi Platforms**: Easily integrate RedStone's Push model into existing DeFi protocols.
- **Liquid Staking and Restaking Platforms**: Manage LSTs and LRTs with precise and timely data not supported by other oracles.
- **Bitcoin in DeFi**: Unlock Bitcoin’s potential in DeFi.

## Conclusion

RedStone Oracles provides a modular, flexible, and gas-optimized solution for decentralized applications, backed by some of the most respected names in the Web3 ecosystem. Whether you're working with LSTs, integrating Bitcoin into DeFi, or seeking a reliable oracle across multiple blockchains, RedStone offers the tools and resources necessary for successful data integration and application development.


# Routescan (/integrations/routescan)

---
title: Routescan
category: Block Explorers
available: ["C-Chain", "All EVM L1s"]
description: Routescan provides block explorer as a service for Avalanche L1s, offering real-time data on transactions, blocks, validators, and more.
logo: /images/routescan.avif
developer: Routescan
website: https://routescan.io/explorer-as-a-service
documentation: https://routescan.io/documentation
---

## Overview

Routescan is a block explorer service tailored for Avalanche Layer 1 (L1) networks. It provides a comprehensive solution for monitoring blockchain activity, offering real-time data on transactions, blocks, validators, and other critical metrics. Routescan is designed to be scalable and customizable, making it an ideal choice for developers and enterprises looking to integrate block explorer capabilities into their Avalanche-based solutions.

## Features

- **Real-Time Data**: Access up-to-date information on transactions, blocks, and validators across Avalanche L1s.
- **Explorer as a Service**: Utilize Routescan’s block explorer as a service to integrate blockchain monitoring into your own platform or application.
- **Customizable Solutions**: Tailor the explorer to fit specific needs, offering flexibility for different use cases.
- **Detailed Validator Information**: Get insights into validator performance, staking details, and historical data.
- **Scalable Infrastructure**: Routescan’s infrastructure is built to handle large volumes of data and transactions, ensuring reliability and performance.
- **API Integration**: Leverage Routescan’s API to fetch and display blockchain data within your own applications.

## Getting Started

To begin using Routescan:

1. **Visit the Routescan Website**: Explore the [Routescan website](https://routescan.io/explorer-as-a-service) to learn more about their block explorer as a service and its features.
2. **Access Documentation**: Check out the [Routescan Documentation](https://routescan.io/documentation) for detailed guides on setting up and using their services.
3. **Integrate the API**: Obtain an API key and start integrating Routescan’s data into your own applications or platforms.
4. **Customize Your Explorer**: Tailor the block explorer service to meet the specific needs of your Avalanche L1 project.
5. **Monitor Network Activity**: Use Routescan to monitor transactions, blocks, and validators in real-time, ensuring that your network is functioning optimally.

## Documentation

For comprehensive information on setting up, customizing, and using Routescan, visit the [Routescan Documentation](https://routescan.io/documentation).

## Use Cases

Routescan is ideal for:

- **Blockchain Developers**: Integrate a scalable block explorer into your Avalanche L1 projects, providing users with real-time network data.
- **Enterprises**: Leverage Routescan’s customizable explorer service to monitor and manage blockchain activity at scale.
- **Validators**: Track validator performance and optimize operations using detailed real-time and historical data.
- **Platform Providers**: Offer block explorer functionality as a value-added service on your own platforms using Routescan’s infrastructure.

## Conclusion

Routescan provides a powerful, scalable block explorer service for Avalanche L1 networks, enabling developers, enterprises, and validators to monitor and manage blockchain activity with precision. Whether you need a standalone explorer or an integrated service within your own platform, Routescan delivers the tools and flexibility required to support your blockchain monitoring needs. With real-time data, customizable options, and robust infrastructure, Routescan is an essential resource for any Avalanche L1 project.



# Sherry (/integrations/sherry-protocol)

---
title: Sherry
category: Mini-Apps
available: ["C-Chain"]
description: "Sherry is the publishing layer that turns any interaction — from a tweet to a chatbot message — into a verifiable, tappable onchain action."
logo: /images/sherry.png
developer: Sherry Labs
website: https://sherry.social
documentation: https://docs.sherry.social/docs/intro
---

## Overview

Sherry Protocol enables decentralised, verifiable distribution and execution of onchain actions. As the publishing layer for Web3, it allows anyone to create, embed, and amplify interactive Web3 actions anywhere on the internet and execute complex multi-step flows directly from their context.

Our SDK empowers developers to create rich, composable mini-apps called Triggers that seamlessly integrate into social networks making blockchain interactions as simple as sharing a link. Sherry is building the foundation for a universal communication standard between AI Agents and Web3 applications.

## Features

- **Interactive Triggers**: Transform static posts into dynamic Web3 experiences with built-in validation and cross-chain support.
- **Multi-Chain Support**: Native integration across Avalanche, Ethereum, and more blockchain networks.
- **Multiple Action Types**: 
  - **Blockchain Actions**: Smart contract interactions with rich parameter configuration
  - **Transfer Actions**: Native token and ERC20 transfers with customizable UIs
  - **Dynamic Actions**: User-defined actions with flexible parameters for custom logic
  - **HTTP Actions**: API calls and form submissions
  - **Nested Action Flows**: Complex multi-step processes with conditional logic
- **Frictionless UX**: Users can interact with Web3 applications without leaving their social feed.
- **Developer-Friendly SDK**: Full TypeScript support with comprehensive type definitions and built-in validation.
- **AI Agent Ready**: Structured metadata designed to become a common language for AI agents to discover and execute blockchain capabilities.

## Getting Started

To begin building with Sherry:

1. **Install the SDK**:
   ```bash
   npm install @sherrylinks/sdk
   # or
   yarn add @sherrylinks/sdk
   ```

2. **Create Your First Trigger**:
   ```typescript
   import { createMetadata, Metadata } from '@sherrylinks/sdk';

   const metadata: Metadata = {
     url: 'https://myapp.example',
     icon: 'https://example.com/icon.png',
     title: 'Send AVAX',
     description: 'Quick AVAX transfer',
     actions: [
       {
         label: 'Send 0.1 AVAX',
         description: 'Transfer 0.1 AVAX to recipient',
         to: '0x1234567890123456789012345678901234567890',
         amount: 0.1,
         chains: { source: 'avalanche' },
       },
     ],
   };

   const validatedMetadata = createMetadata(metadata);
   ```

3. **Deploy and Share**: Embed your trigger into social media posts and let users interact directly.

## Documentation

For comprehensive guides and technical documentation, visit [Sherry Documentation](https://docs.sherry.social/docs/intro). Key resources include:

- **[SDK Introduction](https://docs.sherry.social/docs/intro)**: Getting started with the Sherry SDK
- **[Action Types](https://docs.sherry.social/docs/api/action-types)**: Learn about different interaction types
- **[Parameters Guide](https://docs.sherry.social/docs/api-reference/parameters/)**: Configure user inputs and validation
- **[Chain Support](https://docs.sherry.social/docs/core-concepts/chains)**: Multi-chain deployment guide
- **[Guides](https://docs.sherry.social/docs/getting-started/examples)**: Guides and code samples for common use cases

## Use Cases

Sherry serves diverse Web3 integration needs:

- **Social DeFi**: Enable token swaps, staking, and yield farming directly within social posts.
- **DAO Governance**: Create voting interfaces and proposal submission forms embedded in community posts.
- **NFT Experiences**: Allow minting, trading, and showcasing NFTs without leaving social platforms.
- **Fundraising Campaigns**: Build donation and crowdfunding triggers with real-time progress tracking.
- **Cross-Chain Operations**: Execute seamless asset transfers between different blockchain networks.
- **AI Agent Integration**: Provide structured interfaces for AI agents to interact with Web3 protocols.
- **Community Engagement**: Create interactive experiences that boost social media engagement while driving Web3 adoption.

## Supported Chains

Sherry currently supports the following blockchain networks:

- **Avalanche C-Chain** (`avalanche`)
- **Avalanche Fuji Testnet** (`fuji`)

Additional L1 chains are continuously being added to expand the platform's reach and capabilities.

## Recent Milestones

**Avalanche Codebase **: Part of Avalanche Codebase S25.

## Vision & Roadmap

Sherry aims to be the performance layer of the permissionless internet — where every link, post, or message can carry embedded economic intent.  We're building the foundation for a universal standard of communication between AI Agents and blockchain applications. Our structured metadata is designed to become a common language that allows AI Agents to:

- **Discover Blockchain Capabilities**: Enable AI agents to understand available actions in each Web3 application
- **Execute Complex Actions**: Make it easier for agents to compose and execute sequences of blockchain actions
- **Universal Interoperability**: Establish bridges between different AI and blockchain ecosystems
- **Complexity Abstraction**: Hide technical details so agents can focus on meeting user needs

## Conclusion

Sherry represents the next evolution of how Web3 is experienced and adopted. Whether you're a developer building the next generation of social DApps, a community manager looking to engage your audience, or an AI agent seeking to interact with blockchain protocols, Sherry provides the infrastructure to make it happen.

# SnowScan (/integrations/snowscan)

---
title: SnowScan
category: Block Explorers
available: ["C-Chain", "All EVM L1s"]
description: SnowScan is a block explorer for the Avalanche network, providing real-time data on transactions, blocks, validators, and more.
logo: /images/snowscan.png
developer: Etherscan
website: https://snowscan.xyz/
documentation: https://docs.snowscan.xyz/
---

## Overview

SnowScan is a comprehensive block explorer for the Avalanche network, developed by Etherscan. It provides users with real-time data on transactions, blocks, validators, and other crucial metrics within the Avalanche ecosystem. With its reliable infrastructure and intuitive interface, SnowScan is a valuable tool for developers, validators, and anyone interested in exploring the Avalanche blockchain.

## Features

- **Real-Time Data**: Access up-to-the-minute information on transactions, block confirmations, and validator activities on the Avalanche network.
- **Detailed Analytics**: Get in-depth analytics on blocks, transactions, and addresses to better understand blockchain activity.
- **Validator Monitoring**: Track validator performance and staking information with detailed insights and historical data.
- **User-Friendly Interface**: Navigate the Avalanche blockchain with an intuitive, easy-to-use interface similar to Etherscan.
- **API Integration**: Utilize the SnowScan API to integrate blockchain data into your applications and services.
- **Comprehensive Search Tools**: Easily find specific transactions, addresses, or blocks with advanced search functionalities.

## Getting Started

To start using SnowScan:

1. **Visit the SnowScan Website**: Explore the [SnowScan website](https://snowscan.xyz/) to begin navigating the Avalanche network.
2. **Search and Analyze**: Use the search functionality to find transactions, addresses, and block information, or dive into detailed analytics.
3. **Monitor Validators**: Access performance data for validators, including staking details and historical metrics.
4. **Use the API**: For developers, refer to the [SnowScan Documentation](https://docs.snowscan.xyz/) to learn how to integrate SnowScan’s API into your projects.
5. **Explore the Avalanche Network**: Leverage SnowScan’s tools to monitor and analyze network activity, ensuring you stay informed on the latest developments.

## Documentation

For more detailed information on using SnowScan and integrating its features, visit the [SnowScan Documentation](https://docs.snowscan.xyz/).

## Use Cases

SnowScan is ideal for:

- **Blockchain Developers**: Monitor and analyze transactions, blocks, and validators to support development and deployment on the Avalanche network.
- **Validators**: Optimize performance and track staking activities with real-time data and insights.
- **Researchers and Analysts**: Conduct detailed analyses of the Avalanche blockchain using comprehensive data provided by SnowScan.
- **General Users**: Explore and verify transactions, blocks, and network activities with a user-friendly block explorer.

## Conclusion

SnowScan offers a powerful and reliable block explorer experience tailored for the Avalanche network. Whether you’re a developer, validator, or blockchain enthusiast, SnowScan provides the tools and data you need to effectively monitor and analyze blockchain activity on Avalanche. With its real-time data, intuitive interface, and robust API, SnowScan is an essential resource for anyone involved with Avalanche.



# SnowTrace (/integrations/snowtrace)

---
title: SnowTrace
category: Block Explorers
available: ["C-Chain"]
description: SnowTrace is a block explorer for the Avalanche network, providing real-time data on transactions, blocks, validators, and more.
logo: /images/snowtrace.jpg
developer: Routescan
website: https://snowtrace.io/
documentation: https://snowtrace.io/documentation
---

## Overview

SnowTrace is a powerful block explorer for the Avalanche network, developed by Ava Labs. It provides users with detailed, real-time data on transactions, blocks, validators, and other essential blockchain metrics. SnowTrace is designed to be user-friendly while offering robust features for developers, validators, and anyone interested in tracking Avalanche network activities.

## Features

- **Real-Time Blockchain Data**: Access up-to-date information on transactions, block confirmations, and validator activities.
- **Comprehensive Search Tools**: Easily search for specific transactions, addresses, blocks, and more using advanced search functionality.
- **Validator Insights**: Get detailed information on validator performance, including staking details and historical data.
- **Network Overview**: View a holistic overview of the Avalanche network, including key metrics and network status.
- **User-Friendly Interface**: Navigate through blockchain data with a clean, intuitive interface suitable for both beginners and advanced users.
- **API Access**: Integrate SnowTrace data into applications via its API, providing developers with reliable access to blockchain data.

## Getting Started

To start using SnowTrace:

1. **Visit SnowTrace**: Navigate to the [SnowTrace website](https://snowtrace.io/) to begin exploring the Avalanche network.
2. **Search and Explore**: Use the search functionality to find specific transactions, addresses, or blocks, and explore detailed blockchain data.
3. **Validator Data**: Dive into validator statistics to analyze performance and staking information.
4. **Check Network Status**: Monitor the overall health and status of the Avalanche network with real-time metrics.
5. **API Documentation**: Refer to the [SnowTrace Documentation](https://snowtrace.io/documentation) for information on using the API, including endpoints and usage examples.

## Documentation

For more information on using SnowTrace and integrating its features into your projects, visit the [SnowTrace Documentation](https://snowtrace.io/documentation).

## Use Cases

SnowTrace is ideal for:

- **Blockchain Developers**: Analyze transactions and blocks for development purposes, debugging, and smart contract interaction.
- **Validators**: Monitor validator operations and optimize performance based on real-time and historical data.
- **Blockchain Enthusiasts**: Explore the Avalanche network and track transactions, blocks, and network activity.
- **Analysts and Researchers**: Access comprehensive data for in-depth blockchain analysis and research.

## Conclusion

SnowTrace is an essential tool for anyone working with or interested in the Avalanche network. With its detailed real-time data, user-friendly interface, and robust API, SnowTrace offers comprehensive insights into the blockchain. Whether you’re a developer, validator, or blockchain enthusiast, SnowTrace provides the resources and tools you need to effectively monitor and analyze the Avalanche network.



# Space and Time (/integrations/spaceandtime)

---
title: Space and Time
category: Analytics & Data
available: ["C-Chain", "Subnet"]
description: "SpaceandTime is a decentralized data warehouse for indexing blockchain data and supporting onchain/offchain analytics."
logo: /public/images/SpaceandTime.jpg
developer: Space and Time
website: https://www.spaceandtime.io
documentation: https://docs.spaceandtime.io
---

## Overview
Space and Time is a decentralized data warehouse that provides a blockchain indexing services for major blockchains, including Bitcoin, Ethereum, Avalanche etc., for developers to access real-time data and build data-driven apps.

## Key Features.

- **Integration with Major Chains**: Space and Time integrates with major blockchains like Ethereum, Polygon, and Avalanche, enabling developers to easily connect data to smart contracts.
- **Zero-Knowledge Proofs**: Space and Time leverages zero-knowledge proofs to enhance data privacy and integrity, allowing for secure and verifiable computations.
- **Proof of SQL**: This protocol ensures that off-chain compute results are cryptographically verifiable, enhancing data integrity and trust.
- **Smart Contract Indexing**: Allows developers to generate custom tables in Space and Time from their own smart contract events.

## Getting Started

To begin exploring Avalanche data from Space and Time;

1. **Create UserID**: Create a new user with a username and password by registering via [Dreamspace](https://app.spaceandtime.ai).
2. **Create API key**: To authenticate your app queries, create an API key. 
- Go to "My Account" then click on "Account settings" 
- Add a label (e.g., "AvalancheApp") and click add.
- Copy the API key shown; it will not be displayed again.
3. **Explore Indexed Avalanche Data Sets**: Go to the "Datasets" tab where you'll see all tables.
4. **Run your first avalanche Query**: Use the Query Editor to run queries directly on Avalanche chain data.
5. **Use Avalanche Data in your App**: Once your query works, you can fetch the results from your app via Space and Time's REST API.

Here is a detailed quick-start guide: https://docs.makeinfinite.com/docs/gettingstarted

## Documentation

For a comprehensive and detailed guide on querying data and building with Space and Time, visit [SpaceandTimeDocumentatio](https://docs.makeinfinite.com)

## Use-Cases

1. **Sub-second ZK Coprocessor**: Space and Time pioneered the first sub-second ZK coprocessor so that your smart contract can ask data-driven questions about indexed data from every major chain and offchain data from any source in a realtime, ZK-proven way.
2. **Onchain app development**: Build data-driven apps with pre-built APIs for SQL operations. Run SQL against your own offchain data tables and tables with realtime blockchain data that we've indexed from major chains.
3. **DeFi/lending**: With Space and Time, you can combine real-world credit scores with onchain transactions to create new Web3 credit scores for decentralized lending platforms.
4. **Gaming/NFTs**: Power your game with extremely low-latency transactions and run scale-out analytics against terabytes of data. 
5. **Tamperproof SQL ledger**: Space and Time lets you prove compliance, track supply chain history, maintain an auditable record of financial transactions, and more by ensuring that your data is accurate, verifiable, and traceable at all times.
6. **Verifiable LLMs**: Build transparent, tamperproof, and provably neutral LLMs. 

## Conclusion
Space and Time (SXT Chain) is the first trustless database for the EVM, enabling smart contracts to interact with historical, cross-chain, or offchain data as if it were natively accessible onchain.


# SubQuery (/integrations/subquery)

---
title: SubQuery
category: Indexers
available: ["C-Chain"]
description: SubQuery's decentralized infrastructure makes your dApp lightning quick, infinitely scalable, and absolutely unstoppable.
logo: /images/subquery.webp
developer: SubQuery
website: https://subquery.network/indexer
documentation: https://academy.subquery.network/
---

## Overview

SubQuery is a decentralized data indexing and querying solution designed to provide fast, scalable, and reliable infrastructure for decentralized applications (dApps). Tailored for EVM-compatible chains like Avalanche's C-Chain, SubQuery empowers developers to create high-performance dApps with seamless access to blockchain data.

## Features

- **Decentralized Infrastructure**: SubQuery operates on a decentralized network, ensuring high availability and resilience against failures.
- **Lightning-Fast Performance**: Optimized for speed, SubQuery enables dApps to access and query blockchain data quickly and efficiently.
- **Infinite Scalability**: Built to scale with your application, SubQuery handles increasing loads and data volumes without compromising performance.
- **Custom Indexing**: Create custom data indexing solutions that cater to the specific needs of your application.

## Getting Started

To start using SubQuery:

1. **Visit the SubQuery Website**: Explore the features and offerings on the [SubQuery website](https://subquery.network/indexer).
2. **Access the Documentation**: Follow the [SubQuery Documentation](https://academy.subquery.network/) for detailed setup guides and tutorials.
3. **Set Up Indexing**: Implement custom indexing solutions using SubQuery’s tools and infrastructure.
4. **Deploy on C-Chain**: Use SubQuery to index and query data on the Avalanche C-Chain, ensuring high performance for your dApp.
5. **Monitor and Scale**: Utilize SubQuery’s scalable infrastructure to keep your dApp running smoothly as it grows.

## Documentation

For comprehensive guides, tutorials, and support, visit the [SubQuery Academy](https://academy.subquery.network/).

## Use Cases

SubQuery is suitable for:

- **Avalanche Developers**: Build efficient and scalable dApps on the Avalanche C-Chain using SubQuery's indexing solutions.
- **High-Performance dApps**: Ensure your decentralized application can quickly and efficiently query blockchain data.
- **Custom Data Indexing**: Create and deploy custom indexing solutions tailored to your project’s needs.

## Conclusion

SubQuery provides a robust and decentralized solution for data indexing and querying on EVM-compatible blockchains, particularly the Avalanche C-Chain. With its lightning-fast performance and infinite scalability, SubQuery is an essential tool for developers looking to build high-performance decentralized applications.



# Sumsub (/integrations/sumsub)

---
title: Sumsub
category: KYC / Identity Verification
available: ["C-Chain"]
description: Sumsub is a comprehensive identity verification platform that offers KYC/AML solutions for compliant user onboarding, perfect for txAllowlist implementations.
logo: /images/sumsub.png
developer: Sumsub
website: https://sumsub.com/
documentation: https://docs.sumsub.com/
---

## Overview

Sumsub is a powerful identity verification platform that provides comprehensive KYC (Know Your Customer) and AML (Anti-Money Laundering) solutions for blockchain projects. It offers a streamlined verification process to help businesses ensure regulatory compliance while maintaining a seamless user experience. Sumsub's solutions can be particularly valuable for projects implementing txAllowlist precompiles that need to verify user identities before granting transaction permissions.

## Features

- **Automated Verification Checks**: Sumsub provides a suite of automated verification tools including ID verification, proof of address checks, and watchlist screening.
- **Multi-Channel Verification**: Offers various verification methods including document verification, biometric verification, and liveness detection.
- **AML Screening**: Screens users against global sanctions lists, PEP (Politically Exposed Persons) databases, and adverse media listings.
- **Customizable Workflows**: Build custom verification flows tailored to your specific risk profile and regional requirements.
- **No-Code Integration**: Integrates easily with your platform through WebSDK, MobileSDK, or API connections.
- **Global Compliance**: Ensures compliance with regulations across different jurisdictions worldwide.
- **Fraud Prevention**: Advanced fraud detection technologies to prevent identity theft and account takeovers.

## Getting Started

To integrate Sumsub into your Avalanche-based application, follow these steps:

1. **Sign Up**: Create an account on the [Sumsub website](https://sumsub.com/).
2. **Configure Verification Flow**: Set up your verification requirements and customize the user flow.
3. **Integrate**: Choose your preferred integration method (WebSDK, MobileSDK, or API) and follow the implementation guides in the [documentation](https://docs.sumsub.com/).
4. **Test**: Use Sumsub's testing environment to ensure the integration works as expected.
5. **Go Live**: Once testing is complete, move to the production environment and begin verifying users.

## Integration with txAllowlist

Sumsub is an excellent choice for projects implementing txAllowlist precompiles on Avalanche. The txAllowlist precompile restricts who can issue transactions to the chain, making it ideal for permissioned networks where user verification is required. By integrating Sumsub:

1. **KYC/AML Verification**: Users complete verification through Sumsub's interface.
2. **Allowlist Approval**: Upon successful verification, your backend can automatically add the user's address to the txAllowlist.
3. **Transaction Permission**: Verified users can then submit transactions to the chain, while unverified users are blocked.

This creates a compliant, permissioned environment where only KYC-verified users can interact with your blockchain.

## Documentation

For detailed integration guides, API references, and customization options, visit the [Sumsub Documentation](https://docs.sumsub.com/).

## Use Cases

Sumsub is ideal for a variety of Avalanche-based applications requiring identity verification:

- **Financial Services**: DeFi protocols requiring regulatory compliance.
- **Enterprise Blockchains**: Private or consortium networks that need to verify participant identities.
- **Regulated Markets**: Applications operating in jurisdictions with strict KYC requirements.
- **High-Value Transactions**: Platforms handling significant asset values that need enhanced security.

## Conclusion

Sumsub provides a robust, flexible identity verification solution that integrates seamlessly with Avalanche's txAllowlist functionality. By combining these technologies, developers can build compliant applications that maintain high security standards while providing a smooth onboarding experience for legitimate users. 

# Supra dVRF (/integrations/supra-vrf)

---
title: Supra dVRF
category: VRF
available: ["C-Chain", "EVM L1s"]
description: Supra dVRF work behind the scenes to make dApps more engaging, fair, and secure.
logo: /images/supra.png
developer: Supra Labs
website: https://supra.com/
documentation: https://docs.supra.com/dvrf
---

## Overview

For Web3 dApps, you need randomness that's decentralized and verifiably recorded on-chain.

That’s exactly what Supra dVRF solves. With a novel on-chain randomness generation mechanism, Supra’s decentralized dVRF is designed to power dApps with effectively random outcomes that are responsive, scalable, and easily verifiable.

- **Low-Latency Response**: The novel architecture of Supra dVRFs can compute and ship random outcomes in just moments, not minutes.

- **Designed to Scale**: Our network leverages batching to achieve greater network efficiency as well as lower costs.

- **Truly Decentralized**: Supra dVRFs use a secret sharing algorithm to distribute power across multiple nodes, so no one node has the power to compromise your apps or users.

- **Natively Cross-chain**: Supra dVRF solves on-chain randomness for Web3 at large, not just a few networks. We’re already on 27 networks like Aptos, Arbitrum, Avalanche, Ethereum, Optimism, and Polygon.

## Documentation

1. **Supra dVRF**: Integrate [Supra dVRF](https://docs.supra.com/dvrf/build-with-supra-dvrf/getting-started) for tamper-proof, unbiased, and cryptographically verifiable random numbers to be employed by smart contracts. You can also explore Supra dVRF dashboard [HERE.](https://supra.com/data/dvrf)

2. **Explore Supra's Layer 1**: Check [Docs](https://docs.supra.com/) to start building with the Full Supra Stack.

## Get Started

Supra’s dVRF can provide the exact properties required for a random number generator (RNG) to be fair with tamper-proof, unbiased, and cryptographically verifiable random numbers to be employed by smart contracts.

- **Unbiased and Unpredictable** - The threshold signature of the nonce, client-provided input, and blockhash of the transaction that requests the randomness (which is unknown at the time of request) is used as the seed for the RNG function.

- **Tamper Proof and Verifiable** - Cryptographic proof will be provided to verify that random numbers were generated and communicated with the highest fidelity.

## How to subscribe to consume random numbers:

#### Subscription Model

Think of it like a prepaid phone plan, but for random numbers. You deposit funds upfront, and Supra uses them to pay gas fees for your VRF callbacks.

- **Predictable costs:** Set gas limits upfront, no surprises

- **Simplified contracts:** Your VRF consumer contracts don't need to handle payments

- **Bulk management:** One subscription can serve multiple contracts

- **Reliability:** Reserved minimum balance ensures your requests don't fail due to insufficient funds

#### Why use subscriptions?

- You create a subscription with your wallet address as the manager.

- Deposit funds into your subscription account.

- Register (whitelist) your smart contracts under this subscription.

- When your contracts request random numbers, Supra automatically pays the callback gas fees from your subscription balance.

- No need to handle gas payments in your contract code - it's all automated!

**To start using dVRF, you need to create a subscription that will manage your random number requests and handle gas payments for callbacks. You can create a subscription in two ways: using the new web interface or through on-chain functions.**

1. **Via the web interface**: The easiest way to create your dVRF subscription is through subscription manager UI at [supra.com/data/dvrf.](https://supra.com/data/dvrf)


2. **Via Onchain functions**: For developers who prefer programmatic subscription creation, you can interact directly with the smart contracts.

- EVM Chains

```
// Interface for dVRF 3.0 Deposit Contract
interface IDeposit {
    function addClientToWhitelist(
        uint128 maxGasPrice, 
        uint128 maxGasLimit
    ) external payable;
}
```

- Supra L1

```
// Create subscription on Supra L1
public entry fun create_subscription(
    sender: &signer,
    max_gas_fee: u64,
    initial_deposit: u64
) {
    // Call the deposit module to create subscription
    deposit::add_client_to_whitelist(sender, max_gas_fee);
    deposit::deposit_fund(sender, initial_deposit);
}
```

- **Verification**: Use web interface or getSubscriptionByClient() function, After creating your subscription, verify it's working correctly.

You can explore more on how to Integrate and learn more from our broader [Documentation.](https://docs.supra.com/dvrf/build-with-supra-dvrf/create-your-subscription)


# Supra (/integrations/supra)

---
title: Supra
category: Oracles
available: ["C-Chain"]
description: "Supra is the first MultiVM Layer 1 with full vertical integration of Native Oracles, dVRF, bridging, automation — creating a unified platform for building Super dApps."
logo: /images/supra.png
developer: Supra Labs
website: https://supra.com/
documentation: https://docs.supra.com/
---

## Overview

Supra is a MultiVM Layer 1. It recorded 500k TPS on 300 nodes with sub-second consensus latency. It's the first chain with full vertical integration of native oracles, DVRF, bridging, automation creating a unified platform for building Super dApps.

## Features

- **Lightning Fast Speeds:** Get better data with near-instant refresh rates with full on-chain finality. We’re on track to become the world’s fastest-to-finality oracle Reaching finality in 600-900ms.
- **Truly Decentralized:** Our oracles are designed to be decentralized at every level, from multi-source data collection to a globally distributed node network.
- **Toughened Security:** Our oracles are designed with a randomized node network along with inbuilt fail-safes to maximize security guarantees.
- **Natively Interoperable:** We’re blockchain agnostic and compatible with over 58 networks like Aptos, Arbitrum, Avalanche, Ethereum, Optimism, Polygon, and more.
- **Massive Scalability:** We've devised a novel consensus algorithm that can process hundreds of thousands of transactions per second without compromising security.

## Getting Started

1. **Start Building using Supra Oracle**: Refer to the [docs](https://docs.supra.com/oracles) to gain a deeper understanding and detailed guides on integration.
2. **Explore Supra's Layer 1**: Check [Docs](https://docs.supra.com/) to start building with the Full Supra Stack.
3. **Supra dVRF**: Integrate [Supra dVRF](https://docs.supra.com/dvrf/build-with-supra-dvrf/getting-started) for tamper-proof, unbiased, and cryptographically verifiable random numbers to be employed by smart contracts.
4. **Supra Automation**: Check Supra's block level [Automation Docs](https://docs.supra.com/automation) to create financial systems that are responsive, intelligent, and user-friendly without sacrificing decentralization.
5. **SupraNova Bridge**: SupraNova is a cross-chain communication framework developed by Supra. Check [Docs Here](https://docs.supra.com/supranova)

## Documentation

Explore our detailed Oracle Docs for more info on:
- Data Feeds: [CHECK HERE](https://docs.supra.com/oracles/data-feeds)
- APIs For Real time and Historical data: [CHECK HERE](https://docs.supra.com/oracles/apis-real-time-and-historical-data)
- Indices: [CHECK HERE](https://docs.supra.com/oracles/indices)

## Use Cases

1. **For DeFi**
- Instant price feeds for decentralized exchanges
- Monitoring stablecoin collateral values in real-time
- Automatic portfolio rebalancing with accuracy
- Instant tradFi prices for synthetics trading

2. **Gaming**
- Real-time real-world data for prediction markets
- Dynamic and evolving in-game assets
- Monitoring floor prices and marketplaces

3. **Supply Chain**
- Tracking product origin and provenance
- Managing inventory levels and reordering triggers
- Accurate and secure inventory management

4. **Web3 Identity**
- Decentralized identity verification
- Credit scoring and lending risk assessment
- Reputation systems for community platforms

Explore how oracles can help your Web3 project from [HERE](https://supra.com/oracles-product/)

## Conclusion

Supra Oracles is a powerful cross-chain oracle network designed to power dApps across blockchain ecosystems with fast, secure, decentralized, and scalable data solutions. From DeFi to GameFi, our network delivers the data feeds and connections Web3 needs to reach its full potential.



# SushiSwap (/integrations/sushiswap)

---
title: SushiSwap
category: DEX Liquidity
available: ["C-Chain"]
description: "SushiSwap is a multichain automated market maker (AMM) that enables users to trade, earn, and build on Avalanche's C-Chain."
logo: /images/sushiswap.jpeg
developer: Sushi
website: https://www.sushi.com/
documentation: https://docs.sushi.com/
---

## Overview

SushiSwap is a leading decentralized exchange (DEX) that operates across multiple chains, including Avalanche's C-Chain. It offers users a comprehensive DeFi ecosystem with features including token swapping, yield farming, and liquidity provision. Built on the proven AMM model, SushiSwap provides reliable and efficient trading services while maintaining deep liquidity across various trading pairs.

## Features

- **Multi-Chain Support**: Seamlessly trade assets across different blockchain networks.
- **Trident AMM**: Advanced AMM framework offering multiple pool types for optimal trading.
- **BentoBox**: Innovative vault system for capital efficient lending and borrowing.
- **Yield Strategies**: Various farming opportunities for liquidity providers.
- **Route Processor**: Optimized trading routes for better rates and reduced slippage.
- **Concentrated Liquidity**: Enhanced capital efficiency through targeted liquidity provision.

## Getting Started

To begin using SushiSwap on Avalanche:

1. **Access Platform**: Visit [Sushi](https://www.sushi.com/) and select Avalanche network.
2. **Connect Wallet**: Link your Web3 wallet and ensure you have AVAX for fees.
3. **Start Trading**: 
   - Choose tokens to swap
   - Review rates and slippage settings
   - Confirm transaction
4. **Earn Yields**: Explore liquidity provision and farming opportunities.

## Documentation

For comprehensive guides and technical documentation, visit the [Sushi Documentation](https://docs.sushi.com/).

## Use Cases

SushiSwap accommodates various DeFi activities:

- **Token Trading**: Efficient swaps with competitive rates and minimal slippage.
- **Liquidity Provision**: Earn fees by providing liquidity to trading pairs.
- **Yield Farming**: Access additional rewards through SUSHI token emissions.
- **Cross-Chain Operations**: Trade and manage assets across multiple networks.
- **DeFi Integration**: Build on top of Sushi's infrastructure using their SDK.

## Conclusion

SushiSwap brings its battle-tested DEX infrastructure to Avalanche's C-Chain, offering users access to deep liquidity, efficient trading, and diverse yield opportunities. With its comprehensive feature set and multichain capabilities, SushiSwap provides a robust platform for both casual users and sophisticated DeFi participants on Avalanche.

# Suzaku (/integrations/suzaku)

---
title: Suzaku
category: Validator Marketplace
available: ["All Avalanche L1s"]
description: Suzaku is the (re)staking protocol for sovereign networks.
logo: /images/suzaku.png
developer: Suzaku
website: https://suzaku.network
documentation: https://docs.suzaku.network
---

## Overview

Suzaku is the (re)staking protocol for sovereign networks. With the Suzaku Framework, you can bootstrap and increase the cryptoeconomic security of your Avalanche L1, as well as scale and decentralize its validator set.

## Features

- **Cryptoeconomic security to bootstrap**: Suzaku allows users to secure Avalanche L1s through (re)staking, enabling liquid staking of L1s' native tokens and dual staking security models with blue-chip tokens like AVAX, BTC, and ETH as collateral.
- **Operators to scale and decentralize**: High-tier infrastructure providers and validators offer their services to Avalanche L1s through Suzaku.
- **An ecosystem of decentralized services**: Some networks, like the [Suzaku Relayer Network](https://docs.suzaku.network/suzaku-rn), are purpose-built to provide critical services (i.e. censorship-resistant interoperability) to other Avalanche L1s.

## Getting Started

The best way to get started with Suzaku is to go through the [Restaking Guide](https://docs.suzaku.network/suzaku-restaking/for-stakers/restaking-guide).

## Documentation

The Suzaku documentation is available at [https://docs.suzaku.network](https://docs.suzaku.network).

## Use Cases

Avalanche L1 builders can leverage Suzaku in many different ways. Here are some examples of what you can do with Suzaku:

- **Validator set management**: Open-source security modules to manage your L1 validator set using PoA, PoS, dual-staking, etc.
- **L1 liquid staking**: LST-as-a-service for your Avalanche L1 and multi-LST liquidity pools.
- **Scaling and decentralization**: Suzaku helps you to scale and decentralize your L1 with high-tier infrastructure providers and validators.
- **Suzaku Relayer Network**: Supercharging Avalanche Warp Messaging with censorship-resistance and enhanced security for Avalanche L1 bridges

## Conclusion

Suzaku is the go-to protocol for L1 builders looking to decentralize their network while keeping a high degree of security through (re)staking.


# Tenderly (/integrations/tenderly)

---
title: Tenderly
category: Development Infrastructure
available: ["C-Chain", "All EVM L1s"]
description: Tenderly is a full-stack Web3 infrastructure platform that combines high-performance node services, mainnet-like development environments, and comprehensive developer tools for building, testing, debugging, and scaling decentralized applications with features like real-time monitoring, transaction simulation, and automated security responses.
logo: /images/tenderly.png
developer: Tenderly
website: https://tenderly.co/
documentation: https://docs.tenderly.co/
---

## Overview
Tenderly provides a comprehensive Web3 infrastructure platform designed for developing, testing, and scaling decentralized applications (dApps). 
The platform offers high-performance node RPC services, development environments that mirror mainnet conditions, and an extensive suite of developer tools for monitoring and debugging smart contracts.

## Features
- **[Virtual TestNets](https://docs.tenderly.co/virtual-testnets?mtm_campaign=ext-docs&mtm_kwd=avalanche)**: Provides mainnet-like development environments for testing and staging smart contracts with unlimited faucet access.
- **[Simulator UI & Debugger](https://docs.tenderly.co/debugger?mtm_campaign=ext-docs&mtm_kwd=avalanche)**: Offers visual transaction debugging tools that reduce debugging time from hours to minutes.
- **[Simulation RPC](https://docs.tenderly.co/simulations/single-simulations#simulate-via-rpc?mtm_campaign=ext-docs&mtm_kwd=avalanche)**: Enables accurate prediction of transaction outcomes and gas costs before on-chain execution.
- **[Alerts & Web3 Actions](https://docs.tenderly.co/alerts/intro-to-alerts?mtm_campaign=ext-docs&mtm_kwd=avalanche)**: Deliver real-time monitoring and automated responses to on-chain events.
- **[Node RPC](https://docs.tenderly.co/node/rpc-reference?mtm_campaign=ext-docs&mtm_kwd=avalanche)**: Ensures high-performance, low-latency access across multiple regions with enterprise-grade reliability.

## Getting Started
1. **Create an Account**: Sign up at [Tenderly Dashboard](https://dashboard.tenderly.co/register/?mtm_campaign=ext-docs&mtm_kwd=avalanche)
2. **Set Up a TestNet**: Create a virtual TestNet for your development environment
3. **Access Faucet**: Utilize the unlimited faucet for testing purposes
4. **Explore Documentation**: Review the [official documentation](https://docs.tenderly.co/?mtm_campaign=ext-docs&mtm_kwd=avalanche)
5. **Integrate Tools**: Implement Tenderly's tools into your development workflow

## Documentation
For comprehensive integration guides, API references, and developer resources, visit [Tenderly Documentation](https://docs.tenderly.co/?mtm_campaign=ext-docs&mtm_kwd=avalanche).

## Use Cases
Tenderly supports various Web3 development scenarios:
- **Smart Contract Development**: Test and debug contracts in isolated environments
- **Protocol Updates**: Validate protocol upgrades and DAO proposals safely
- **dApp Development and Staging**: Develop, stage, and test smart contracts and entire dApps
- **Security Monitoring**: Implement automated security responses and real-time alerts
- **Transaction Optimization**: Predict and optimize transaction outcomes and gas costs

## Conclusion
Tenderly offers a robust, full-stack Web3 infrastructure solution that enables developers to build, test, and scale decentralized applications efficiently. With its comprehensive toolset and focus on development experience, Tenderly provides essential capabilities for modern Web3 development, from local testing to production deployment and monitoring.

# The Graph (/integrations/the-graph)

---
title: The Graph
category: Indexers
available: ["C-Chain"]
description: The Graph is a decentralized indexing protocol that enables easy querying of blockchain data using GraphQL.
logo: /images/thegraph.png
developer: The Graph
website: https://thegraph.com/
documentation: https://thegraph.com/docs/
---

## Overview

Getting historical data on a smart contract can be frustrating when building a dapp. [The Graph](https://thegraph.com/) provides an easy way to query smart contract data through APIs known as **subgraphs**. The Graph’s infrastructure relies on a decentralized network of indexers, enabling your dapp to become truly decentralized.


## Features

- **Decentralized Indexing**: Enables indexing blockchain data through multiple indexers, thus eliminating any single point of failure
- **GraphQL Queries**: Provides a powerful GraphQL interface for querying indexed data, making data retrieval super simple.
- **Customizable & Reusable**: Define your own logic for transforming & storing blockchain data. Reuse subgraphs published by other developers.
- **Data Aggregation**: Aggregates data from multiple blockchain sources, offering a unified view for easier access and analysis.
- **Scalability**: Designed to handle large volumes of data and scale with the needs of growing dApps and data requirements.


## Getting Started

Building a subgraph only takes a few minutes. It primarily consists of the following steps:

1. Initialize your subgraph project
2. Deploy & Publish
3. Query from your dapp

Here’s a detailed quick-start guide:
https://thegraph.com/docs/en/quick-start/



## Documentation

For detailed instructions on creating subgraphs, querying data, and integrating with The Graph, visit the [The Graph Documentation](https://thegraph.com/docs/).


## Use Cases

The Graph is ideal for a variety of blockchain data needs:

- **Decentralized Applications (dApps)**: Efficiently index and query data for dApps, enabling enhanced functionality and user experiences.
- **Data Aggregation**: Aggregate data from multiple blockchain sources for comprehensive insights and analytics.
- **Data Retrieval**: Provide fast and reliable data retrieval for applications that require access to blockchain data.
- **Analytics and Reporting**: Use The Graph to collect and analyze blockchain data, supporting reporting and decision-making processes.

## Conclusion

The Graph provides a robust solution for indexing and querying blockchain data. It effectively tackles the challenge of reading blockchain data without creating a centralized bottleneck. With its network of indexers, The Graph offers increased redundancy and quicker query responses. Using GraphQL queries, your dApp can pinpoint exactly the fields it requires.



# The TIE (/integrations/thetie)

---
title: The TIE
category: Analytics & Data
available: ["C-Chain"]
description: "The TIE provides real-time and historical data APIs for Avalanche, offering sentiment analysis, trading signals, and on-chain metrics through their SigDev Terminal."
logo: /images/thetie.jpg
developer: The TIE
website: https://thetie.io/
documentation: https://docs.thetie.io/
---

## Overview

The TIE's SigDev platform provides developers with access to comprehensive crypto data APIs including Avalanche-specific metrics, sentiment analysis, and on-chain data. Their SDK enables integration of both real-time and historical data for applications built on Avalanche.

## Features

- **Data APIs**:
  - Real-time market data
  - Social sentiment analysis
  - On-chain metrics
  - Trading signals
- **Integration Options**:
  - REST API
  - WebSocket feeds
  - Python SDK
  - R SDK
- **Data Types**:
  - Price data
  - Volume analytics
  - Social metrics
  - News sentiment
  - On-chain activity
- **Developer Tools**:
  - API authentication
  - Rate limiting options
  - Data filtering
  - Custom endpoints

## Getting Started

To integrate The TIE's data:

1. **Access Setup**:
   - Register for API access
   - Get API credentials
   - Choose data endpoints
2. **Implementation**:
```python
from thetie import TieClient

client = TieClient(api_key='your-api-key')

# Fetch Avalanche metrics
avalanche_data = client.get_metrics(
    asset='AVAX',
    metrics=['price', 'volume', 'sentiment'],
    interval='1h'
)
```

## Documentation

For comprehensive API documentation and integration guides, visit [The TIE Documentation](https://docs.thetie.io/).

## Use Cases

The TIE enables:

- **Market Analysis**: Access comprehensive market data
- **Sentiment Tracking**: Monitor social sentiment metrics
- **Trading Applications**: Integrate trading signals and metrics
- **Research Tools**: Build research and analysis platforms
- **Portfolio Analytics**: Track and analyze asset performance

## Conclusion

The TIE provides robust data infrastructure for developers building on Avalanche, offering comprehensive APIs and SDKs for accessing market, social, and on-chain data. Their tools enable developers to integrate sophisticated data analytics into their applications with reliable and scalable access to multiple data types. 

# Thirdweb x402 (/integrations/thirdweb-x402)

---
title: Thirdweb x402
category: x402
available: ["C-Chain"]
description: Thirdweb provides an x402 facilitator service that handles verifying and submitting x402 payments on Avalanche.
logo: /images/thirdweb.png
developer: Thirdweb
website: https://thirdweb.com/
documentation: https://portal.thirdweb.com/payments/x402/facilitator
---

## Overview

Thirdweb's x402 facilitator is a service that handles verifying and submitting x402 payments on Avalanche's C-Chain. It uses your own server wallet and leverages EIP-7702 to submit transactions gaslessly, making it easy to integrate payment-gated APIs and AI services.

The thirdweb facilitator is compatible with any x402 backend and middleware libraries like `x402-hono`, `x402-next`, `x402-express`, and more.

## How It Works

- **Verification**: Validates payment signatures and requirements
- **Settlement**: Submits the payment transaction on-chain
- **Gasless**: Uses EIP-7702 for gasless transactions
- **Your Wallet**: Uses your own server wallet for receiving payments

You can view all transactions processed by your facilitator in your thirdweb project dashboard.

## Chain and Token Support

The thirdweb facilitator supports payments on **any EVM chain**, including Avalanche C-Chain, as long as the payment token supports either:

- **ERC-2612 permit** (most ERC20 tokens)
- **ERC-3009 sign with authorization** (USDC on all chains)

## Key Features

- **Multi-Chain Support**: Works on Avalanche C-Chain and all EVM-compatible chains
- **Gasless Transactions**: Leverages EIP-7702 for user-friendly payment experience
- **Your Own Wallet**: Use your own server wallet to receive payments directly
- **Dashboard Monitoring**: Track all facilitator transactions in your thirdweb dashboard
- **Compatible Middleware**: Works with all x402 middleware libraries

## Getting Started

### Creating a Facilitator

Create a facilitator instance to use with x402 payments:

```typescript
import { facilitator } from "thirdweb/x402";
import { createThirdwebClient } from "thirdweb";

const client = createThirdwebClient({
  secretKey: "your-secret-key",
});

const thirdwebFacilitator = facilitator({
  client: client,
  serverWalletAddress: "0x1234567890123456789012345678901234567890",
});
```

### Configuration Options

```typescript
const thirdwebFacilitator = facilitator({
  // Required: Your thirdweb client with secret key
  client: client,
  
  // Required: Your server wallet address that will execute transactions
  // get it from your project dashboard
  serverWalletAddress: "0x1234567890123456789012345678901234567890",
  
  // Optional: Wait behavior for settlements
  // - "simulated": Only simulate the transaction (fastest)
  // - "submitted": Wait until transaction is submitted
  // - "confirmed": Wait for full on-chain confirmation (slowest, default)
  waitUntil: "confirmed",
});
```

## Integration Examples

### Usage with settlePayment()

Use the facilitator with the `settlePayment()` function on Avalanche:

```typescript
import { settlePayment, facilitator } from "thirdweb/x402";
import { createThirdwebClient } from "thirdweb";
import { avalanche } from "thirdweb/chains";

const client = createThirdwebClient({
  secretKey: process.env.THIRDWEB_SECRET_KEY,
});

const thirdwebFacilitator = facilitator({
  client,
  serverWalletAddress: "0x1234567890123456789012345678901234567890",
});

export async function GET(request: Request) {
  const paymentData = request.headers.get("x-payment");
  
  const result = await settlePayment({
    resourceUrl: "https://api.example.com/premium-content",
    method: "GET",
    paymentData,
    payTo: "0x1234567890123456789012345678901234567890",
    network: avalanche, // Use Avalanche C-Chain
    price: "$0.10",
    facilitator: thirdwebFacilitator, // Pass the facilitator here
  });
  
  if (result.status === 200) {
    return Response.json({ data: "premium content" });
  } else {
    return Response.json(result.responseBody, {
      status: result.status,
      headers: result.responseHeaders,
    });
  }
}
```

### Usage with x402-hono Middleware

Use the facilitator with Hono middleware on Avalanche:

```typescript
import { Hono } from "hono";
import { paymentMiddleware } from "x402-hono";
import { facilitator } from "thirdweb/x402";
import { createThirdwebClient } from "thirdweb";

const client = createThirdwebClient({
  secretKey: "your-secret-key",
});

const thirdwebFacilitator = facilitator({
  client: client,
  serverWalletAddress: "0x1234567890123456789012345678901234567890",
});

const app = new Hono();

// Add the facilitator to the x402 middleware
app.use(
  paymentMiddleware(
    "0xYourWalletAddress",
    {
      "/api/paywall": {
        price: "$0.01",
        network: "avalanche", // Use Avalanche mainnet
        config: {
          description: "Access to paid content",
        },
      },
    },
    thirdwebFacilitator, // Pass the facilitator to the middleware
  ),
);

app.get("/api/paywall", (c) => {
  return c.json({ message: "This is premium content!" });
});

export default app;
```

### Usage with x402-express Middleware

Use the facilitator with Express middleware on Avalanche:

```typescript
import express from "express";
import { paymentMiddleware } from "x402-express";
import { facilitator } from "thirdweb/x402";
import { createThirdwebClient } from "thirdweb";

const client = createThirdwebClient({
  secretKey: "your-secret-key",
});

const thirdwebFacilitator = facilitator({
  client: client,
  serverWalletAddress: "0x1234567890123456789012345678901234567890",
});

const app = express();

app.use(
  paymentMiddleware(
    "0xYourWalletAddress",
    {
      "GET /api/premium": {
        price: "$0.05",
        network: "avalanche", // Use Avalanche mainnet
      },
    },
    thirdwebFacilitator,
  ),
);

app.get("/api/premium", (req, res) => {
  res.json({ content: "Premium AI content" });
});

app.listen(3000);
```

## Getting Supported Payment Methods

Query which payment methods are supported by the facilitator on Avalanche:

```typescript
// Get all supported payment methods
const allSupported = await thirdwebFacilitator.supported();

// Filter by Avalanche C-Chain
const avalancheSupported = await thirdwebFacilitator.supported({
  chainId: 43114, // Avalanche C-Chain
});

// Filter by chain and token (e.g., USDC on Avalanche)
const usdcOnAvalanche = await thirdwebFacilitator.supported({
  chainId: 43114,
  tokenAddress: "0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E", // USDC on Avalanche
});
```

## Avalanche C-Chain Integration

When using thirdweb's x402 facilitator on Avalanche's C-Chain:

- **Chain ID**: 43114 for mainnet, 43113 for Fuji testnet
- **Network String**: Use `"avalanche"` for mainnet or `"avalanche-fuji"` for testnet
- **Fast Settlement**: Benefit from Avalanche's sub-second transaction finality
- **Low Costs**: Enable micropayments with minimal gas fees
- **Dashboard Tracking**: Monitor all Avalanche transactions in your thirdweb dashboard

## Use Cases

### AI Agent Monetization
Use thirdweb's facilitator to enable AI agents to charge for services on a pay-per-use basis.

### Payment-Gated APIs
Protect your API endpoints with automatic payment verification and settlement.

### Micropayment Services
Enable micropayments for content, data, or compute resources with minimal overhead.

### Multi-Chain AI Services
Build AI services that accept payments across Avalanche and other EVM chains.

## Documentation

For detailed implementation guides and API references:
- [Thirdweb x402 Facilitator Documentation](https://portal.thirdweb.com/payments/x402/facilitator)
- [Thirdweb Portal](https://portal.thirdweb.com/)

## Conclusion

Thirdweb's x402 facilitator provides a robust infrastructure for handling payment-gated services on Avalanche's C-Chain. With gasless transactions, automatic payment verification, and seamless integration with popular middleware libraries, it's the perfect solution for developers building monetized AI services and APIs. Whether you're using Express, Hono, Next.js, or custom implementations, thirdweb's facilitator makes it easy to accept x402 payments on Avalanche.



# ThirdWeb (/integrations/thirdweb)

---
title: ThirdWeb
category: Wallet SDKs
available: ["C-Chain", "All EVM L1s"]
description: ThirdWeb provides a low-latency API for generating keys and signing transactions within secure hardware.
logo: /images/thirdweb.avif
developer: ThirdWeb
website: https://thirdweb.com/
documentation: https://portal.thirdweb.com/
---

## Overview

ThirdWeb offers a low-latency API designed for generating keys and signing transactions within secure hardware. This SDK is ideal for developers looking to integrate secure wallet functionalities into their applications, ensuring robust security and efficient performance for managing blockchain transactions.

## Features

- **Low-Latency API**: Provides fast and responsive API access for generating keys and signing transactions.
- **Secure Hardware Integration**: Utilizes secure hardware to protect sensitive information and enhance security.
- **User-Friendly SDK**: Easy-to-integrate SDK with comprehensive documentation and support.
- **Cross-Platform Support**: Compatible with various platforms and blockchain networks, allowing for flexible integration.
- **Enhanced Security**: Ensures high levels of security for key management and transaction signing, reducing vulnerabilities.

## Getting Started

To integrate ThirdWeb into your application:

1. **Visit the ThirdWeb Website**: Explore the [ThirdWeb website](https://thirdweb.com/) to learn more about its SDK and features.
2. **Access the Documentation**: Refer to the [ThirdWeb Documentation](https://portal.thirdweb.com/) for detailed integration guides and API references.
3. **Install the SDK**: Follow the instructions in the documentation to install and configure the ThirdWeb SDK for your project.
4. **Implement Key Generation and Signing**: Use the API to implement key generation and transaction signing functionalities within your application.
5. **Test and Deploy**: Test the integration thoroughly to ensure functionality and security before deploying your application.

## Documentation

For in-depth integration instructions, API details, and support resources, visit the [ThirdWeb Documentation](https://portal.thirdweb.com/).

## Use Cases

ThirdWeb is suitable for various applications requiring secure key management and transaction signing:

- **Wallet Applications**: Integrate secure key management and signing functionalities into digital wallet applications.
- **DeFi Platforms**: Enhance the security and efficiency of transactions within decentralized finance (DeFi) applications.
- **Blockchain Games**: Implement secure transaction signing for in-game assets and interactions.
- **Financial Services**: Provide secure transaction management for blockchain-based financial services.

## Conclusion

ThirdWeb delivers a powerful SDK for integrating low-latency key generation and transaction signing within secure hardware. With its focus on security and performance, ThirdWeb is a valuable tool for developers seeking to enhance the safety and efficiency of blockchain transactions across various applications. Whether you're building a wallet app, a DeFi platform, or a blockchain-based game, ThirdWeb provides the tools needed for secure and effective integration.



# Traceye (/integrations/traceye)

---
title: Traceye
category: Indexers
available: ["C-Chain"]
description: Traceye is a full-stack Blockchain indexing platform supporting multiple indexing protocols like 'The Graph' and 'Subquery Network'.
logo: /images/traceye.png
developer: Traceye
website: https://traceye.io/
documentation: https://doc.traceye.io
---

## Overview

Traceye is an indexing platform designed specifically to address the needs Avalanche L1s. The platform leverages popular indexing protocols like 'The Graph' and 'Subquery Network' on shared and dedicated infrastructure to provide both cost-effective & enterprise grade indexing solutions. Traceye also provides a host of developer addons built on top of indexers to aid in app development.

## Features

- **Zero-Cost Indexer Development**: Traceye offer free consulting and development of data indexers tailored exclusively for Avalanche Layer 1 chains. Get started without upfront costs or vendor lock-in.
- **High Availability**: Enjoy ultra-fast indexing, minimal data lag, and 99.99% uptime — all without the hassle of infrastructure maintenance.
- **Configurable Webhooks**: Set up real-time webhooks on any indexed entity.
- **BI Reporting & Charts Engine**: Built-in business intelligence engine for creating visual reports, dashboards, and charts directly from indexed data.
- **One-Click Web3 API Launch**: Instantly generate and deploy Web3 Data APIs with a single click — optimized for L1 chains, no backend coding required.
- **Bring Your Own RPC**: Connect your preferred Avalanche RPC endpoints for enhanced flexibility and control over indexing behavior.
- **Custom Business Logic & Direct DB Access**: Define custom entities, apply business logic, and access your data directly from the underlying database.
- **Query & Database Optimizer**: Leverage our smart query optimizer and schema tuning tools for low-latency responses and efficient data retrieval.
- **Observability & Tracking**: Built-in notifications, versioning, logs, and entity tracking.
- **Infrastructure Monitoring & Alerts**: Real-time infrastructure health checks, performance metrics, and alerting system to keep your deployment healthy and responsive.

## Getting Started

To begin using Traceye, follow these steps:

1. Visit the [Traceye website](https://app.traceye.io/) : Sign-up or log-in to access the platform.
2. Left-side menu provides options for shared and dedicated indexing along with 1-click Web3 data APIs for L1 chains.
3. Scroll to the appropriate option based on requirement and access the dashboard. Use the 'Buy Subscription' option to purchase subscription or get a free plan.
4. Once subscription is set, launch the indexer or Web3 data APIs.
5. Connect with us for free consulting & indexer development on L1.

## Documentation

For detailed guides and API references visit the [Traceye documentation](https://doc.traceye.io).

## Use Cases

Traceye is ideal for various blockchain projects and applications:

- **Public L1 Chains**: Expose GraphQL and REST APIs for core Web3 data including NFTs, Tokens, Wallets, Blocks & Transactions. Perfect for explorers, analytics platforms, and dApps needing standardized access to on-chain data.
- **Appchains**: Enable custom indexers tailored to the specific data requirements of appchains — whether it's gaming, identity, or specialized DeFi use cases.
- **DeFi & dApps**: Index and serve data from custom smart contracts powering DeFi protocols or decentralized applications.
- **Blockchain Analytics**: Leverage Traceye’s BI and reporting engine to generate insights through comprehensive dashboards covering chain-wide activity, DeFi/dApp usage, and historical on-chain trends.
- **Programmable On-Chain Actions**: Trigger real-time workflows using webhooks on top of Indexers configured on specific on-chain events.

## Conclusion

Traceye is user-friendly essentially one stop shop for all your L1 blockchain data requirements whether is standard Web3 Data APIs like NFT, Token, Transaction, Wallet APIs etc. or custom data requirements based on Smart-contract, it has got you covered. Moreover, Traceye offers free of cost consulting and indexer development exclusively for L1s so you can get started immediately.


# Trader Joe (/integrations/trader-joe)

---
title: Trader Joe
category: DEX Liquidity
available: ["C-Chain"]
description: "Trader Joe is a leading decentralized exchange (DEX) on Avalanche, offering trading, lending, and yield farming capabilities."
logo: /images/traderjoe.jpeg
developer: Trader Joe Team
website: https://traderjoexyz.com/
documentation: https://docs.traderjoexyz.com/
---

## Overview

Trader Joe is a comprehensive decentralized trading platform native to the Avalanche ecosystem. It provides users with a one-stop-shop for trading, lending, and yield farming on Avalanche's C-Chain. The platform is known for its user-friendly interface, deep liquidity pools, and innovative features like their Liquidity Book AMM model.

## Features

- **Liquidity Book (LB)**: An innovative AMM model that offers concentrated liquidity with customizable price ranges and multiple fee tiers.
- **Token Swaps**: Efficient token exchanges with competitive rates and minimal slippage.
- **Yield Farming**: Opportunities to earn rewards by providing liquidity to trading pairs.
- **Lending Markets**: Users can lend and borrow assets through isolated lending markets.
- **Real Yield**: Protocol revenue is distributed to token stakers and liquidity providers.
- **Cross-Chain Trading**: Access to trading across multiple chains through their v2.1 deployment.

## Getting Started

To begin using Trader Joe:

1. **Connect Wallet**: Visit [Trader Joe](https://traderjoexyz.com/) and connect your Web3 wallet (MetaMask, Core, etc.).
2. **Fund Your Wallet**: Ensure you have AVAX in your wallet for transaction fees.
3. **Start Trading**: 
   - Select the tokens you want to trade
   - Review the transaction details
   - Confirm the swap in your wallet
4. **Provide Liquidity**: Optionally, provide liquidity to earn trading fees and rewards.

## Documentation

For detailed guides and technical documentation, visit the [Trader Joe Documentation](https://docs.traderjoexyz.com/). Key resources include:
- Integration guides for developers
- Smart contract addresses and audits
- Liquidity provision tutorials
- API documentation

## Use Cases

Trader Joe serves various DeFi needs:

- **Token Swaps**: Quick and efficient token exchanges on Avalanche.
- **Liquidity Provision**: Earn yields by providing liquidity to trading pairs.
- **Yield Farming**: Participate in incentivized liquidity mining programs.
- **Asset Management**: Access to a wide range of Avalanche-based tokens.
- **Cross-Chain Trading**: Execute trades across multiple blockchain networks.

## Conclusion

Trader Joe stands as a cornerstone of the Avalanche DeFi ecosystem, providing essential trading infrastructure and innovative features through their Liquidity Book model. Whether you're a trader, liquidity provider, or developer, Trader Joe offers the tools and liquidity needed to participate in decentralized finance on Avalanche's C-Chain.

# Trail of Bits (/integrations/trailofbits)

---
title: Trail of Bits
category: Security Audits
available: ["C-Chain", "All EVM L1s"]
description: "Trail of Bits provides top-tier security audits for smart contracts and blockchain protocols with deep technical expertise."
logo: /images/trailofbits.png
developer: Trail of Bits
website: https://www.trailofbits.com/
---

## Overview

Trail of Bits is a top-tier security research firm specializing in advanced security assessments for blockchain protocols and smart contracts. With one of the most respected technical teams in the industry, they provide comprehensive audits that identify vulnerabilities and potential attack vectors in projects building on Avalanche. Their team includes experts in cryptography, formal verification, and low-level systems security.

## Features

- **Smart Contract Audits**: Rigorous code reviews with manual and automated techniques.
- **Protocol Security**: Comprehensive analysis of blockchain protocols and infrastructure.
- **Custom Tool Development**: Creation of specialized security tools for specific project needs.
- **Formal Verification**: Mathematical verification of critical security properties.
- **Security Research**: Publication of industry-leading blockchain security research.
- **Security Training**: Educational resources for developer teams.
- **Continuous Security Testing**: Ongoing security assessment programs.

## Getting Started

To engage Trail of Bits for security audits:

1. **Initial Contact**: Reach out through their website to discuss your project requirements.
2. **Scoping Phase**: Define the scope, objectives, and timeline for the audit engagement.
3. **Audit Process**: 
   - In-depth manual code review by security experts
   - Automated analysis using proprietary and open-source tools
   - Vulnerability identification and severity classification
   - Detailed recommendations for remediation
4. **Final Reporting**: Comprehensive reports suitable for public release when required.
5. **Follow-up Support**: Optional post-audit support and verification of fixes.

## Use Cases

Trail of Bits security audits are ideal for:

- **High-Value DeFi Protocols**: Thorough security verification for protocols managing significant assets.
- **Novel Blockchain Mechanisms**: Validation of new consensus or cryptographic implementations.
- **Cross-Chain Bridges**: Security assessment of complex bridge infrastructure.
- **Custom Avalanche L1s**: Comprehensive security review of custom blockchain implementations.
- **Critical Infrastructure**: Security verification for foundational blockchain infrastructure.

## Conclusion

Trail of Bits represents the gold standard in blockchain security assessments. Their technical depth and comprehensive approach make them particularly well-suited for complex, high-value, or novel blockchain projects on Avalanche. While their services typically involve longer lead times due to high demand, projects that require the highest level of security assurance will benefit from their industry-leading expertise and thorough approach to security auditing. 

# Transak (/integrations/transak)

---
title: Transak
category: Fiat On-Ramp
available: ["C-Chain", "All EVM L1s"]
description: Transak is a global fiat-to-crypto payment gateway that enables users to buy cryptocurrencies with fiat directly within your application.
logo: /images/transak.png
developer: Transak
website: https://transak.com/
documentation: https://docs.transak.com/
---

## Overview

Transak is a global fiat-to-crypto payment gateway that provides a seamless and compliant on-ramp solution for blockchain applications. It enables users to purchase cryptocurrencies using traditional payment methods directly within your application, eliminating the need to navigate external exchanges. With support for 130+ cryptocurrencies across 100+ countries, Transak offers extensive global coverage and regulatory compliance.

## Features

- **Global Coverage**: Support for users in 100+ countries with local payment methods, currencies, and languages.
- **Multiple Payment Methods**: Credit/debit cards, bank transfers, Apple Pay, Google Pay, and regional payment options.
- **Extensive Crypto Support**: On-ramp to 130+ cryptocurrencies, including native tokens for custom L1s.
- **Flexible Integration Options**: Widget, SDK, and API solutions to fit your application's needs.
- **Customizable Widget**: White-labeled integration that matches your application's design.
- **KYC/AML Compliance**: Built-in compliance processes that meet regulatory requirements across jurisdictions.
- **Risk Management**: Advanced fraud prevention systems that protect both users and merchants.
- **Automated Payouts**: Direct deposit of purchased crypto to user wallets.
- **Fiat Off-Ramp**: Select regions support converting crypto back to fiat (where permitted by regulations).
- **NFT Checkout**: Allow users to purchase NFTs directly with fiat payment methods.
- **Partner Dashboard**: Analytics and management tools to track conversions and optimize performance.

## Getting Started

To integrate Transak into your application:

1. **Sign Up**: Visit the [Transak Partner Dashboard](https://docs.transak.com/docs/setup-your-partner-account) and create an account to get your API key.

2. **Choose Integration Method**:
   
   - **Direct URL Integration**: The simplest approach:
     ```javascript
     const transakUrl = new URL('https://global.transak.com/');
     transakUrl.searchParams.append('apiKey', 'YOUR_API_KEY');
     transakUrl.searchParams.append('defaultCryptoCurrency', 'AVAX');
     transakUrl.searchParams.append('network', 'avalanche');
     transakUrl.searchParams.append('walletAddress', userWalletAddress);
     
     window.open(transakUrl.href, '_blank');
     ```

   - **SDK Integration**: For web applications, add the Transak SDK to your project:
     ```bash
     npm install @transak/transak-sdk
     ```
     
     ```javascript
     import transakSDK from '@transak/transak-sdk';
     
     const transak = new transakSDK({
       apiKey: 'YOUR_API_KEY',
       environment: 'PRODUCTION', // or 'STAGING' for testing
       defaultCryptoCurrency: 'AVAX',
       network: 'avalanche',
       walletAddress: userWalletAddress, // Pre-fill user's wallet
       themeColor: '000000', // Custom color in hex
       hostURL: window.location.origin,
       widgetHeight: '650px',
       widgetWidth: '450px',
       hideMenu: false,
       exchangeScreenTitle: 'Buy Crypto',
       disableWalletAddressForm: false,
     });
     
     transak.init();
     ```

3. **Handle Events**: Listen for transaction events:
   ```javascript
   transak.on(transak.EVENTS.TRANSAK_WIDGET_CLOSE, () => {
     // Handle widget close
   });
   
   transak.on(transak.EVENTS.TRANSAK_ORDER_SUCCESSFUL, (orderData) => {
     // Handle successful purchase
     console.log(orderData);
   });
   
   transak.on(transak.EVENTS.TRANSAK_ORDER_FAILED, (orderData) => {
     // Handle failed purchase
     console.log(orderData);
   });
   ```

4. **Set Up Webhooks** (Optional): Implement server-side webhooks to receive transaction updates:
   ```javascript
   // Example Express.js webhook handler
   app.post('/transak-webhook', (req, res) => {
     const payload = req.body;
     
     if (payload.status === 'COMPLETED') {
       // Process completed transaction
     }
     
     res.status(200).send('Webhook received');
   });
   ```

5. **Test in Staging**: Use the staging environment with test cards to verify your integration before going live.

## Documentation

For detailed implementation guides, API references, and webhook setup, visit the [Transak Documentation](https://docs.transak.com/).

## Use Cases

Transak can be integrated into various blockchain applications:

**Wallets**: Allow users to purchase crypto directly within your wallet application without leaving the interface.

**DeFi Platforms**: Provide a seamless on-ramp for users to acquire tokens needed for your DeFi services.

**NFT Marketplaces**: Enable direct purchase of NFTs with fiat, abstracting away the crypto acquisition step.

**GameFi Applications**: Let gamers purchase in-game assets or tokens without needing prior crypto knowledge.

**Decentralized Applications**: Reduce friction in your dApp's user experience by integrating a native fiat entry point.

## Pricing

Transak operates on a transaction fee model:

- **Fee Range**: Typically 0.5% to 3% per transaction
- **Custom Fee Structure**: Enterprise solutions with custom fee arrangements available
- **Revenue Sharing**: Partnership opportunities with revenue sharing for qualified partners
- **No Monthly Fees**: Pay only for successful transactions

The fee structure can vary by region, payment method, and transaction volume. For detailed pricing information, contact Transak's sales team.

## Conclusion

Transak provides a comprehensive fiat on-ramp solution that can significantly improve user experience in blockchain applications. By handling the complex compliance requirements and payment processing infrastructure, Transak allows developers to focus on building their core application features while providing users with a seamless way to enter the crypto ecosystem. With its extensive global coverage, multiple payment options, and customizable integration, Transak is an ideal solution for any blockchain project looking to reduce friction in the user onboarding process. 

# Ultravioleta DAO (/integrations/ultravioletadao)

---
title: Ultravioleta DAO
category: x402
available: ["C-Chain"]
description: Ultravioleta DAO offers the x402 protocol, a payment infrastructure that enables monetization of AI agents and APIs on Avalanche.
logo: /images/ultravioletadao.png
developer: Ultravioleta DAO
website: https://ultravioletadao.xyz
documentation: https://facilitator.ultravioletadao.xyz
---

## Overview

Ultravioleta DAO, a leading Web3 DAO in Latin America, offers the x402 protocol - a payment infrastructure that enables monetization of AI agents and APIs on Avalanche. The protocol solves a critical challenge: autonomous agents cannot operate without gas money. The x402 facilitator acts as a payment intermediary that verifies transactions, covers gas fees, and settles payments on-chain, allowing agents and services to operate autonomously using USDC payments.

The facilitator is available on both Avalanche C-Chain (Mainnet) and Avalanche Fuji (Testnet), enabling developers to test their integrations before deploying to production.

## What is x402?

x402 is an HTTP-based payment protocol built on the standard HTTP 402 "Payment Required" status code. It enables micropayments between services without requiring the paying party to hold native gas tokens. The protocol uses ERC-3009 meta-transactions to allow third-party facilitators to sponsor gas fees while maintaining cryptographic proof of payment authorization.

**Key participants:**
- **Merchants**: Service providers who monetize their APIs or agent services
- **Clients**: Users or agents who pay for access to services
- **Facilitators**: Infrastructure providers who verify payments and cover gas fees

## Features

- **Gasless Payments**: Clients don't need AVAX for gas fees - the facilitator sponsors all transactions
- **Stablecoin Settlement**: Payments settled in USDC for predictable pricing
- **Cryptographic Security**: EIP-712 signatures ensure payment authenticity and prevent replay attacks
- **Stateless Verification**: All payment verification happens on-chain without requiring databases
- **Fast & Free**: Sub-second payment verification with no fees for using the facilitator service
- **Load Balanced**: Auto-scalable infrastructure ensures high availability and reliability
- **Community Operated**: Fully decentralized and community-governed payment infrastructure

## Getting Started for Merchants

To monetize your API or agent service using x402:

1. **Set up your service endpoint** that you want to monetize
2. **Configure the x402 middleware** to protect your endpoint with a price tag
3. **Specify your payment address** where USDC payments should be received
4. **Deploy your service** - the facilitator handles all payment verification and settlement

Example middleware configuration:
```typescript
import { Hono } from "hono";
import { paymentMiddleware } from "x402-hono";

const app = new Hono();

// Configure payment middleware
app.use(paymentMiddleware(
  "0xYourWalletAddress",
  {
    "/api/service": {
      price: "$0.01",
      network: "avalanche-c-chain",  // or "avalanche-fuji" for testnet
      config: {
        description: "Access to your API service"
      }
    }
  },
  {
    url: 'https://facilitator.ultravioletadao.xyz'
  }
));
```

## Getting Started for Clients

To pay for x402-protected services:

1. **Initialize the x402 client** with your private key and the facilitator URL
2. **Make requests** to protected endpoints - payment happens automatically
3. **Receive the response** once payment is verified and settled on-chain

Example client usage:
```typescript
import { X402Client } from "x402-client";

const client = new X402Client({
  privateKey: process.env.CLIENT_PRIVATE_KEY,
  facilitatorUrl: 'https://facilitator.ultravioletadao.xyz',
  network: 'avalanche-c-chain'  // or 'avalanche-fuji' for testnet
});

// Make a paid request
const response = await client.post('https://api.example.com/service', {
  data: { query: 'your request' }
});
```

## Use Cases

### AI Agent Monetization
Allow autonomous AI agents to offer services and receive payments without manual intervention. Agents can charge per request, per computation, or per resource consumed.

### Pay-Per-Use APIs
Monetize API endpoints with micropayment pricing. Instead of subscription tiers, charge users only for what they consume at granular levels.

### Agent-to-Agent Marketplaces
Build trustless marketplaces where autonomous agents buy and sell services from each other, creating self-sustaining AI economies.

### Token-Gated Services
Provide access to premium services, data feeds, or computational resources based on per-use payments rather than upfront subscriptions.

## Avalanche Integration

The x402 facilitator is optimized for Avalanche deployment on both mainnet and testnet:

### Avalanche C-Chain (Mainnet)
- **Chain ID**: 43114
- **Native Token**: AVAX (used by facilitator for gas fees)
- **Payment Token**: USDC
- **Finality**: Sub-second transaction finality for fast payment confirmation
- **EVM Compatibility**: Full support for ERC-3009 meta-transactions

### Avalanche Fuji (Testnet)
- **Chain ID**: 43113
- **Native Token**: AVAX (used by facilitator for gas fees)
- **Payment Token**: USDC
- **Purpose**: Test your integration before deploying to mainnet

The facilitator maintains a hot wallet funded with AVAX to sponsor gas fees for all USDC payment settlements. Clients only need USDC in their wallets - no AVAX required.

## How It Works

1. **Client Request**: Client signs payment authorization using EIP-712 and sends request to merchant
2. **Merchant Verification**: Merchant forwards payment proof to facilitator for verification
3. **Facilitator Check**: Facilitator verifies signature, checks on-chain balance and nonce
4. **Settlement**: Facilitator submits `transferWithAuthorization()` transaction, paying gas fees
5. **Response**: Once settled, merchant receives confirmation and responds to client

All settlements happen on Avalanche using the ERC-3009 standard, ensuring cryptographic security and on-chain auditability.

## Documentation

For complete API documentation, integration guides, and example implementations, visit the [Ultravioleta DAO facilitator](https://facilitator.ultravioletadao.xyz).

## About Ultravioleta DAO

Ultravioleta DAO is a leading Web3 DAO in Latin America, focused on building decentralized infrastructure for autonomous agent economies. The organization develops open-source protocols and tools that enable trustless interactions between AI agents, with a focus on payment infrastructure, decentralized governance, and blockchain-based monetization. Learn more at [ultravioletadao.xyz](https://ultravioletadao.xyz/).

## Conclusion

Ultravioleta DAO's x402 facilitator provides production-ready payment infrastructure for building autonomous agent economies and monetized APIs on Avalanche. By abstracting away gas fee management and providing a simple HTTP protocol for payments, it enables developers to focus on building valuable services while maintaining security through cryptographic signatures and on-chain settlement. Start testing on Fuji testnet today, then deploy to C-Chain mainnet when ready.

# Vector Finance (/integrations/vectorfinance)

---
title: Vector Finance
category: Lending Protocols
available: ["C-Chain"]
description: "Vector Finance is an Avalanche-native yield management and optimization protocol, offering automated strategies for maximizing returns on deposited assets."
logo: /images/vectorfinance.jpeg
developer: Vector Finance
website: https://vectorfinance.io/
documentation: https://docs.vectorfinance.io/
---

## Overview

Vector Finance is an Avalanche-native yield optimization protocol that automates DeFi strategies to maximize returns for users. It specializes in managing lending positions and yield farming strategies across various Avalanche protocols, with a focus on capital efficiency and risk management.

## Features

- **Automated Strategies**: Optimized yield farming across multiple protocols.
- **Smart Vaults**: Automated position management for maximum yields.
- **VTX Staking**: Earn protocol revenues through token staking.
- **Risk Management**: Diversified strategies with built-in risk controls.
- **Leverage Integration**: Optional leveraged yield farming strategies.
- **Cross-Protocol Optimization**: Automated yield switching across Avalanche DeFi.
- **Impermanent Loss Protection**: Strategies designed to minimize IL risk.

## Getting Started

To begin using Vector Finance:

1. **Access Platform**: Visit [Vector Finance](https://vectorfinance.io/).
2. **Connect Wallet**: Link your Web3 wallet with AVAX for transactions.
3. **Choose Strategy**: 
   - Select from available yield strategies
   - Deposit supported assets
   - Monitor performance
4. **Stake VTX**: Optionally stake VTX tokens for additional rewards.

## Documentation

For detailed protocol documentation and guides, visit the [Vector Finance Documentation](https://docs.vectorfinance.io/).

## Use Cases

Vector Finance serves various DeFi needs:

- **Passive Yield**: Automated yield optimization for passive investors.
- **Liquidity Provision**: Optimized LP strategies with managed risk.
- **Token Staking**: Earn protocol revenues through VTX staking.
- **Portfolio Management**: Automated management of DeFi positions.
- **Risk-Managed Farming**: Access to curated yield farming strategies.

## Conclusion

Vector Finance provides an innovative approach to yield optimization on Avalanche, offering users automated strategies for maximizing returns while managing risks. As a native Avalanche protocol, it leverages the network's speed and efficiency to deliver sophisticated DeFi strategies accessible to both newcomers and experienced users. Whether you're seeking passive yield opportunities or optimized farming strategies, Vector Finance offers a comprehensive suite of tools for maximizing returns in the Avalanche ecosystem. 

# VIA Labs (/integrations/vialabs)

---
title: VIA Labs
category: Crosschain Solutions
available: ["C-Chain"]
description: "VIA Labs enables Avalanche L1s to integrate cross-chain USDC with Proto-USD, leveraging Avalanche's ICM infrastructure and Circle's CCTP."
logo: /images/vialabs.png
developer: VIA Labs
website: https://vialabs.io/
documentation: https://developer.vialabs.io/general/package
---

## Overview

VIA Labs provides Avalanche L1s with Proto-USD, a solution that enables seamless USDC integration across multiple blockchain networks. By combining Avalanche's native Interchain Messaging (ICM) infrastructure with Circle's Cross-Chain Transfer Protocol (CCTP), VIA Labs allows any Avalanche L1 to receive and utilize USDC from networks like Ethereum, Base, Solana, and other CCTP-enabled chains.

## Features

- **Native ICM Integration**: Utilizes Avalanche's built-in cross-chain messaging infrastructure.
- **USDC Cross-Chain Support**: Enables transfer of USDC between Avalanche L1s and other major blockchains.
- **Bridged USDC Standard**: Implements standardized approach for USDC representation across chains.
- **CCTP Compatibility**: Leverages Circle's Cross-Chain Transfer Protocol for secure token transfers.
- **Testnet-Ready**: Available on testnet for all Avalanche L1s.
- **Path to Native Issuance**: Sets Avalanche L1s on an onboarding path to potential native USDC issuance.
- **Multi-Chain Support**: Compatible with Ethereum, Base, Solana (coming soon), and other CCTP-enabled chains.

## Getting Started

To begin using VIA Labs' Proto-USD:

1. **Access Documentation**: Review the [VIA Labs Developer Documentation](https://developer.vialabs.io/general/package).
2. **Explore Demo**: Visit the [Proto-USD demo](https://avax.protousd.com/) to see the technology in action.
3. **Integration Steps**: 
   - Set up ICM infrastructure on your Avalanche L1
   - Configure CCTP message passing
   - Implement Proto-USD contracts
   - Test cross-chain USDC transfers
4. **Deployment**: Deploy to testnet first, then to mainnet after thorough testing.

## Documentation

For comprehensive developer documentation and integration guides, visit the [VIA Labs Developer Portal](https://developer.vialabs.io/general/package).

## Use Cases

Proto-USD enables various cross-chain scenarios:

- **Cross-Chain DeFi**: Access USDC liquidity from other chains for DeFi applications.
- **Multi-Chain dApps**: Build applications that can use USDC across different blockchains.
- **Simplified Treasury Management**: Manage USDC treasury across multiple networks.
- **Enhanced Liquidity**: Tap into USDC liquidity from major blockchains.
- **Seamless User Experience**: Provide users with cross-chain stablecoin functionality.

## Official Launch Update
[See the official announcement on X](https://x.com/VIA_Labs/status/1895156949467161060)

## Conclusion

VIA Labs' Proto-USD provides Avalanche L1s with essential infrastructure for cross-chain USDC integration. By leveraging Avalanche's ICM capabilities and Circle's CCTP, Proto-USD enables seamless stablecoin transfers across blockchain ecosystems. This solution not only enhances the utility of Avalanche L1s but also positions them for potential native USDC issuance in the future, significantly expanding their cross-chain capabilities and accessibility.

# Wormhole (/integrations/wormhole)

---
title: Wormhole
category: Crosschain Solutions
available: ["C-Chain"]
description: "Wormhole is a generic message passing protocol that connects multiple chains, enabling secure cross-chain messaging and asset transfers on Avalanche."
logo: /images/wormhole.png
developer: Wormhole Foundation
website: https://wormhole.com/
documentation: https://docs.wormhole.com/
---

## Overview

Wormhole is a cross-chain messaging protocol that enables secure communication and asset transfers between Avalanche and other blockchain networks. It provides a generic message passing infrastructure that supports various use cases, from simple token transfers to complex cross-chain application logic, all secured by a decentralized guardian network.

## Features

- **Generic Messaging**: Send arbitrary messages between supported chains.
- **Token Bridge**: Native and wrapped token transfers across chains.
- **NFT Bridge**: Transfer NFTs between different blockchains.
- **Guardian Network**: Decentralized network of validators securing cross-chain messages.
- **Automated Relayers**: Efficient message delivery system.
- **xChain Query System**: Query data across different chains.
- **Developer SDK**: Comprehensive tools for cross-chain development.

## Getting Started

To begin using Wormhole:

1. **Access Documentation**: Review the [Wormhole Documentation](https://docs.wormhole.com/).
2. **Choose Integration**: 
   - Token Bridge for asset transfers
   - Generic messaging for custom applications
   - NFT Bridge for digital collectibles
3. **Implement SDK**: 
   - Install Wormhole SDK
   - Configure for Avalanche
   - Test cross-chain functionality
4. **Monitor Transfers**: Track cross-chain messages and transfers.

## Documentation

For detailed technical documentation and integration guides, visit the [Wormhole Documentation](https://docs.wormhole.com/).

## Use Cases

Wormhole enables various cross-chain applications:

- **Asset Bridges**: Transfer tokens and NFTs between chains.
- **Cross-Chain dApps**: Build applications that operate across multiple networks.
- **Data Oracle**: Access data from other chains.
- **Governance**: Implement cross-chain governance mechanisms.
- **Liquidity Aggregation**: Pool liquidity from multiple chains.

## Conclusion

Wormhole provides a robust infrastructure for cross-chain communication on Avalanche's C-Chain. Its combination of secure message passing, token bridging capabilities, and comprehensive developer tools makes it an essential protocol for building cross-chain applications. Whether you're implementing simple token transfers or complex cross-chain logic, Wormhole offers the security and functionality needed for reliable cross-chain operations. 

# x402-rs (/integrations/x402-rs)

---
title: x402-rs
category: x402
available: ["C-Chain"]
description: A Rust-based implementation of the x402 protocol for accepting blockchain payments through HTTP on Avalanche.
logo: /images/x402-rs.png
developer: x402-rs
website: https://github.com/x402-rs/x402-rs
documentation: https://github.com/x402-rs/x402-rs
---

## Overview

x402-rs is a Rust-based implementation of the x402 protocol that enables blockchain payments directly through HTTP using the native `402 Payment Required` status code on Avalanche's C-Chain.

The x402 protocol allows servers to declare payment requirements for specific routes. Clients send cryptographically signed payment payloads, and facilitators verify and settle payments on-chain.

## What x402-rs Provides

- **x402-rs core**: Protocol types, facilitator traits, and logic for on-chain payment verification and settlement
- **Facilitator binary**: Production-grade HTTP server to verify and settle x402 payments
- **x402-axum**: Axum middleware for accepting x402 payments
- **x402-reqwest**: Wrapper for reqwest for transparent x402 payments

## Getting Started

### Run the Facilitator

The quickest way to get started is using Docker:

```bash
docker run --env-file .env -p 8080:8080 ukstv/x402-facilitator
```

Or build locally:

```bash
docker build -t x402-rs .
docker run --env-file .env -p 8080:8080 x402-rs
```

### Protect Axum Routes

Use `x402-axum` to gate your routes behind on-chain payments on Avalanche:

```rust
let x402 = X402Middleware::try_from("https://x402.org/facilitator/").unwrap();
let usdc = USDCDeployment::by_network(Network::AvalancheFuji);

let app = Router::new().route("/paid-content", get(handler).layer( 
        x402.with_price_tag(usdc.amount("0.025").pay_to("0xYourAddress").unwrap())
    ),
);
```

See the [x402-axum crate documentation](https://docs.rs/x402-axum) for more details.

### Send x402 Payments

Use `x402-reqwest` to send payments on Avalanche:

```rust
use x402_reqwest::X402ClientExt;

let signer: PrivateKeySigner = "0x...".parse()?; // never hardcode real keys!

let client = reqwest::Client::new()
    .with_payments(signer)
    .prefer(USDCDeployment::by_network(Network::Avalanche))
    .max(USDCDeployment::by_network(Network::Avalanche).amount("1.00")?)
    .build();

let res = client
    .get("https://example.com/protected")
    .send()
    .await?;
```

See the [x402-reqwest crate documentation](https://docs.rs/x402-reqwest) for more details.

## Facilitator

The x402-rs facilitator is a runnable binary that simplifies x402 adoption by handling:

- **Payment verification**: Confirming that client-submitted payment payloads match the declared requirements
- **Payment settlement**: Submitting validated payments to the blockchain and monitoring their confirmation

By using a facilitator, servers (sellers) do not need to:
- Connect directly to a blockchain
- Implement complex cryptographic or blockchain-specific payment logic

The facilitator never holds user funds. It acts solely as a stateless verification and execution layer for signed payment payloads.

### Configuration

Create a `.env` file or set environment variables directly:

```bash
HOST=0.0.0.0
PORT=8080
RPC_URL_AVALANCHE_FUJI=https://api.avax-test.network/ext/bc/C/rpc
RPC_URL_AVALANCHE=https://api.avax.network/ext/bc/C/rpc
SIGNER_TYPE=private-key
EVM_PRIVATE_KEY=0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef
RUST_LOG=info
```

**Important:** The supported networks are determined by which RPC URLs you provide:

- If you set only `RPC_URL_AVALANCHE_FUJI`, then only Avalanche Fuji testnet is supported
- If you set both `RPC_URL_AVALANCHE_FUJI` and `RPC_URL_AVALANCHE`, then both testnet and mainnet are supported
- If an RPC URL for a network is missing, that network will not be available for settlement or verification

### Environment Variables

Available configuration variables:

- `RUST_LOG`: Logging level (e.g., `info`, `debug`, `trace`)
- `HOST`: HTTP host to bind to (default: `0.0.0.0`)
- `PORT`: HTTP server port (default: `8080`)
- `SIGNER_TYPE` (required): Type of signer to use. Only `private-key` is supported now
- `EVM_PRIVATE_KEY` (required): Private key in hex for EVM networks
- `RPC_URL_AVALANCHE_FUJI`: Ethereum RPC endpoint for Avalanche Fuji testnet
- `RPC_URL_AVALANCHE`: Ethereum RPC endpoint for Avalanche C-Chain mainnet

### Docker Deployment

Prebuilt Docker images are available at:

- **GitHub Container Registry**: `ghcr.io/x402-rs/x402-facilitator`
- **Docker Hub**: `ukstv/x402-facilitator`

Run the container from Docker Hub:

```bash
docker run --env-file .env -p 8080:8080 ukstv/x402-facilitator
```

To run using GitHub Container Registry:

```bash
docker run --env-file .env -p 8080:8080 ghcr.io/x402-rs/x402-facilitator
```

Or build a Docker image locally:

```bash
docker build -t x402-rs .
docker run --env-file .env -p 8080:8080 x402-rs
```

The container:
- Exposes port `8080` (or a port you configure with `PORT` environment variable)
- Starts on `http://localhost:8080` by default
- Requires minimal runtime dependencies (based on `debian:bullseye-slim`)

### Point Your Application to Your Facilitator

If you are building an x402-powered application, update the Facilitator URL to point to your self-hosted instance.

**Using x402-hono:**

```typescript
import { Hono } from "hono";
import { serve } from "@hono/node-server";
import { paymentMiddleware } from "x402-hono";

const app = new Hono();

// Configure the payment middleware
app.use(paymentMiddleware(
  "0xYourAddress", // Your receiving wallet address
  {
    "/protected-route": {
      price: "$0.10",
      network: "avalanche-fuji",
      config: {
        description: "Access to premium content",
      }
    }
  },
  {
    url: "http://your-validator.url/", // 👈 Your self-hosted Facilitator
  }
));

// Implement your protected route
app.get("/protected-route", (c) => {
  return c.json({ message: "This content is behind a paywall" });
});

serve({
  fetch: app.fetch,
  port: 3000
});
```

**Using x402-axum:**

```rust
let x402 = X402Middleware::try_from("http://your-validator.url/").unwrap();  // 👈 Your self-hosted Facilitator
let usdc = USDCDeployment::by_network(Network::AvalancheFuji);

let app = Router::new().route("/paid-content", get(handler).layer( 
        x402.with_price_tag(usdc.amount("0.025").pay_to("0xYourAddress").unwrap())
    ),
);
```

## Observability

The facilitator emits OpenTelemetry-compatible traces and metrics, making it easy to integrate with tools like Honeycomb, Prometheus, Grafana, and others. Tracing spans are annotated with HTTP method, status code, URI, latency, and other request and process metadata.

To enable tracing and metrics export, set the appropriate `OTEL_` environment variables:

```bash
# For Honeycomb, for example:
# Endpoint URL for sending OpenTelemetry traces and metrics
OTEL_EXPORTER_OTLP_ENDPOINT=https://api.honeycomb.io:443
# Comma-separated list of key=value pairs to add as headers
OTEL_EXPORTER_OTLP_HEADERS=x-honeycomb-team=your_api_key,x-honeycomb-dataset=x402-rs
# Export protocol to use for telemetry. Supported values: `http/protobuf` (default), `grpc`
OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
```

The service automatically detects and initializes exporters if `OTEL_EXPORTER_OTLP_*` variables are provided.

## Avalanche C-Chain Support

The facilitator supports Avalanche C-Chain through these environment variables:

| Network                   | Environment Variable      | Notes                            |
| ------------------------- | ------------------------- | -------------------------------- |
| Avalanche Fuji Testnet    | RPC_URL_AVALANCHE_FUJI   | Recommended for testing          |
| Avalanche C-Chain Mainnet | RPC_URL_AVALANCHE        | Production mainnet               |

**Tip:** For initial development and testing, start with Avalanche Fuji testnet only.

## Development

### Prerequisites

- Rust 1.80+
- `cargo` and a working toolchain

### Build Locally

```bash
cargo build
```

### Run

```bash
cargo run
```

## Use Cases

### Payment-Gated APIs
Protect your API endpoints with automatic on-chain payment verification on Avalanche.

### Micropayment Services
Enable micropayments for content, data, or compute resources with Avalanche's low fees.

### AI Agent Monetization
Allow AI agents to charge for services on a pay-per-use basis using Avalanche's fast finality.

### Rust-Native dApps
Build Rust-based decentralized applications with built-in payment capabilities on Avalanche.

## Documentation

- [x402-rs GitHub Repository](https://github.com/x402-rs/x402-rs)
- [x402 Protocol Documentation](https://x402.gitbook.io/x402)
- [x402 Overview by Coinbase](https://www.coinbase.com/cloud/discover/protocol-guides/guide-to-x402)

## Conclusion

x402-rs provides a production-ready Rust implementation of the x402 protocol for Avalanche's C-Chain. With its facilitator service, Axum middleware, and client libraries, it makes it easy to build payment-gated services in Rust. Whether you're protecting API endpoints, enabling micropayments, or building AI agent monetization, x402-rs delivers the tools you need with Rust's performance and safety guarantees on Avalanche.



# Xangle (/integrations/xangle)

---
title: Xangle
category: Development Infrastructure
available: ["C-Chain"]
description: Xangle delivers robust blockchain infrastructure solutions—including node services, custom block explorers, and the all-in-one Xangle Hub—empowering projects to deploy, monitor, and scale on Avalanche and beyond. Analytics and market insights are also available as a complement to its infrastructure offerings.
logo: /images/xangle.jpg
developer: Xangle
website: https://infra.xangle.io/hub
documentation: https://business.xangle.io/
---

## Overview
Xangle is a leading blockchain infrastructure provider, offering high-performance node services, customizable block explorers, and the Xangle Hub—a unified platform for DeFi tools, portfolio management, and on-chain analytics. Xangle's infrastructure enables seamless deployment, monitoring, and scaling of blockchain applications, while supporting ecosystem transparency and accessibility.

## Features
- **Node Services**: Reliable, scalable node infrastructure for developers and enterprises, supporting secure access to blockchain networks.
- **Custom Block Explorers**: Deploy branded, feature-rich explorers for your network or application, with support for transactions, tokens, NFTs, analytics, and more. For example, MapleStory Universe uses a dedicated Xangle-powered explorer for its Henesys L1 testnet ([see example](https://msu-testnet-explorer.xangle.io/)).
- **Xangle Hub**: An all-in-one platform ([see Xangle Hub](https://infra.xangle.io/hub)) that brings together DeFi services (swap, bridge, faucet), portfolio management, NFT minting, dashboards, and real-time on-chain analytics.
- **Developer Tools**: APIs and dashboards for real-time monitoring, data access, and operational insights.
- **Security & Reliability**: Enterprise-grade uptime, monitoring, and support for mission-critical blockchain operations.
- **Analytics & Market Insights**: In addition to infrastructure, Xangle provides market analytics, research, and reporting tools for blockchain projects.

## Getting Started
1. **Explore Infrastructure Solutions**: Visit [Xangle](https://xangle.io/en) to learn about node services, explorer deployments, and developer tools.
2. **Try Xangle Hub**: Experience the unified DeFi and analytics platform at [Xangle Hub](https://infra.xangle.io/hub).
3. **Request Custom Explorer**: Contact Xangle to deploy a tailored explorer for your blockchain or dApp.
4. **Integrate Node Services**: Access secure, scalable nodes for your application or business.
5. **Review Documentation**: Access integration guides and API references at the [official documentation](https://business.xangle.io/).

## Documentation
For comprehensive integration guides, API references, and developer resources, visit the [Xangle Business Documentation](https://business.xangle.io/).

## Use Cases
Xangle supports a variety of development and business scenarios:
- **Network & dApp Infrastructure**: Deploy and manage nodes, explorers, and ecosystem tools for your blockchain or application.
- **Ecosystem Hubs**: Launch a unified platform for your community with DeFi tools, analytics, and portfolio management (see [Xangle Hub](https://infra.xangle.io/hub)).
- **Custom Block Explorers**: Provide users with transparent, branded access to on-chain data (see [MapleStory Universe Explorer](https://msu-testnet-explorer.xangle.io/)).
- **Operational Monitoring**: Use dashboards and APIs for real-time network and application insights.
- **Analytics & Reporting**: Leverage Xangle's analytics and research tools for market intelligence and compliance.

## Conclusion
Xangle delivers a robust suite of infrastructure and ecosystem tools for the blockchain space, empowering developers, projects, and communities to build, monitor, and scale with confidence. With its focus on infrastructure, reliability, and extensibility, Xangle is a valuable partner for any Web3 initiative—while also offering analytics and market insights as a powerful complement.


# Zeeve (/integrations/zeeve)

---
title: Zeeve
category: Blockchain as a Service
available: ["All EVM L1s"]
description: Build and Deploy Avalanche L1s with plug-and-play dev tools and Zeeve infrastructure platform.
logo: /images/zeeve.jpeg
developer: Zeeve
website: https://www.zeeve.io/appchains/avalanche-subnets/
documentation: https://docs.zeeve.io/
---

## Overview
Zeeve extends its enterprise-grade infrastructure management platform to Avalanche L1s, enabling builders to launch their own Blockchain. From seamless deployments to 24×7 monitoring, Zeeve handles it all for you, allowing you to focus on building your business.

## Features
- **Plug-and-play tools**: Simplify Avalanche L1 deployment with pre-built, easy-to-use dev tools.
- **Managed infrastructure**: Leverage Zeeve’s enterprise-grade platform for monitoring and maintenance.
- **Scalability**: Ensure smooth scaling of your blockchain network as your project grows.
- **Security**: Benefit from Zeeve's robust security features and architecture.
- **High availability**: Enjoy 24/7 uptime and monitoring services to minimize downtime and ensure operational continuity.

## Getting Started
1. Sign up for a Zeeve account [here](https://www.zeeve.io/appchains/avalanche-subnets/).
2. Explore the Avalanche L1s deployment guide provided in the Zeeve documentation.
3. Use Zeeve’s platform to set up, deploy, and monitor your Avalanche L1 blockchain with ease.

## Documentation
For detailed information and step-by-step guides, visit the official [Zeeve Documentation](https://docs.zeeve.io/).


# Zellic (/integrations/zellic)

---
title: Zellic
category: Security Audits
available: ["C-Chain", "All EVM L1s"]
description: "Zellic provides highly recommended security audits with deep expertise in VM audits and advanced cybersecurity techniques."
logo: /images/zellic.png
developer: Zellic
website: https://zellic.io/
---

## Overview

Zellic is a highly recommended security firm specializing in advanced blockchain security audits with particular expertise in Virtual Machine (VM) audits. Their team combines deep technical knowledge with practical cybersecurity experience to deliver comprehensive security assessments for projects building on Avalanche. Beyond static code audits, Zellic can perform dynamic analysis and in-depth security reviews of complex systems.

## Features

- **VM Audits**: Specialized expertise in auditing virtual machine implementations.
- **Smart Contract Security**: Comprehensive reviews of contract code and logic.
- **Deep Cybersecurity Background**: Team with advanced offensive security expertise.
- **Protocol Analysis**: Thorough assessment of protocol designs and implementations.
- **Advanced Vulnerability Research**: Identification of novel attack vectors and security issues.
- **Custom Security Solutions**: Tailored security assessments for specific project needs.

## Getting Started

To engage Zellic for security audits:

1. **Initial Contact**: Reach out to Zellic at [oliver@zellic.io](mailto:oliver@zellic.io) to discuss your project requirements.
2. **Security Assessment Planning**: Define the scope, objectives, and timeline for your audit.
3. **Audit Process**: 
   - In-depth code and architecture review
   - Specialized VM auditing when applicable
   - Dynamic analysis and penetration testing
   - Comprehensive vulnerability assessment
4. **Findings and Recommendations**: Detailed report outlining security issues and remediation steps.
5. **Remediation Support**: Guidance on addressing identified vulnerabilities.

## Use Cases

Zellic security audits are particularly valuable for:

- **Custom VM Implementations**: Specialized assessment of virtual machine code.
- **Novel Blockchain Implementations**: Security review of innovative blockchain designs.
- **Complex Smart Contract Systems**: Thorough analysis of intricate smart contract interactions.
- **Cross-Chain Applications**: Security assessment of applications spanning multiple blockchains.
- **High-Security Requirements**: Projects requiring advanced security validation beyond standard audits.

## Conclusion

Zellic provides highly specialized security audits with particular strength in VM auditing and deep cybersecurity expertise. Highly recommended by leading projects in the space, their team can perform not just static audits but also dynamic security analysis, making them well-suited for complex systems and custom implementations on Avalanche. Their technical depth and cybersecurity background enable them to identify sophisticated vulnerabilities that might be missed in conventional security reviews. 

# ZeroDev (/integrations/zerodev)

---
title: ZeroDev
category: Account Abstraction
available: ["C-Chain", "All EVM L1s"]
description: ZeroDev is an account abstraction toolkit that enables developers to build applications with smart accounts, gasless transactions, and session keys.
logo: /images/zerodev.png
developer: ZeroDev
website: https://zerodev.app/
documentation: https://docs.zerodev.app/
---

## Overview

ZeroDev is a comprehensive account abstraction toolkit built on ERC-4337 that empowers developers to create more user-friendly blockchain applications. It provides everything needed to integrate smart accounts into dApps, including gasless transactions, batch transactions, and session keys for simplified authentication flows.

## Features

- **Smart Accounts**: Implement fully ERC-4337 compliant smart contract accounts that enhance security and user experience.
- **Gasless Transactions**: Enable sponsorship of gas fees for users, eliminating the need for them to hold native tokens.
- **Bundled Transactions**: Combine multiple transactions into one for better UX and lower overall gas costs.
- **Session Keys**: Allow users to authorize specific actions for a limited time without needing to sign every transaction.
- **Social Login**: Integrate with email, social media, and passkey authentication for seamless user onboarding.
- **Multi-chain Support**: Deploy and manage smart accounts across multiple EVM-compatible blockchains.
- **Modular Architecture**: Customize account implementation based on specific application needs.

## Getting Started

To get started with ZeroDev, follow these steps:

1. **Install ZeroDev SDK**: Add the SDK to your project using npm or yarn:
   ```bash
   npm install @zerodev/sdk
   ```

2. **Initialize the SDK**: Set up the client in your application code:
   ```javascript
   import { createEcdsaKernelAccountClient } from "@zerodev/sdk"
   
   const client = await createEcdsaKernelAccountClient({
     projectId: "YOUR_PROJECT_ID",
     owner: yourWalletClient,
   })
   ```

3. **Register for API Keys**: Create an account on the [ZeroDev Dashboard](https://dashboard.zerodev.app/) to get your project ID.

4. **Implement Gas Sponsorship**: Follow the [paymaster documentation](https://docs.zerodev.app/sdk/core-api/sponsor-gas) to set up gas sponsorship for your users.

5. **Deploy and Test**: Test your implementation in a development environment before going live.

## Documentation

For detailed guides, API references, and examples, visit the [ZeroDev Documentation](https://docs.zerodev.app/).

## Use Cases

ZeroDev is versatile and can be used for a variety of applications:

**DeFi Applications**: Streamline the user experience by eliminating gas fees and simplifying complex transaction sequences through batching.

**Gaming and NFT Platforms**: Enable gasless minting and trading of NFTs, making blockchain gaming accessible to mainstream audiences.

**Web3 Social Applications**: Implement social login and session keys to create smooth, Web2-like user experiences while maintaining the benefits of blockchain.

**Enterprise Solutions**: Build corporate wallet solutions with customizable permissions, transaction limits, and multi-signature requirements.

**Mobile dApps**: Create mobile-friendly applications that don't require users to manually sign every transaction.

## Pricing

ZeroDev offers a tiered pricing model:

- **Free Tier**: Up to 100 monthly active users with basic features
- **Growth**: Starting at $99/month for up to 1,000 monthly active users
- **Scale**: Custom pricing for enterprises with higher volume needs

For the most current pricing information, visit the [ZeroDev pricing page](https://zerodev.app/pricing).

## Conclusion

ZeroDev provides a comprehensive toolkit for implementing account abstraction in blockchain applications. By handling the complex infrastructure required for ERC-4337 smart accounts, it allows developers to focus on building great user experiences. With features like gasless transactions, bundled operations, and session keys, ZeroDev makes blockchain applications more accessible to mainstream users while maintaining the security and decentralization benefits of Web3. 

# Zokyo (/integrations/zokyo)

---
title: Zokyo
category: Security Audits
available: ["C-Chain", "All EVM L1s"]
description: "Zokyo offers good-quality security audits with a balanced approach to thoroughness and accessibility."
logo: /images/zokyo.jpeg
developer: Zokyo
website: https://www.zokyo.io/
---

## Overview

Zokyo is a security audit provider offering good-quality assessments for blockchain projects building on Avalanche. Their balanced approach combines technical thoroughness with practical considerations, making their services accessible to a range of projects. Zokyo's team provides comprehensive security reviews while maintaining reasonable lead times and resource requirements.

## Features

- **Smart Contract Audits**: Thorough code reviews and vulnerability assessments.
- **Protocol Security**: Analysis of protocol design and implementation.
- **Balanced Approach**: Good combination of depth and efficiency in audit process.
- **Practical Recommendations**: Actionable guidance for security improvements.
- **Reasonable Timeframes**: Efficient audit processes with reasonable lead times.
- **Technical Expertise**: Team with solid knowledge of blockchain security.
- **Verification Services**: Validation of security improvements after remediation.

## Getting Started

To engage Zokyo for security audits:

1. **Initial Contact**: Reach out through their website to discuss your audit requirements.
2. **Audit Planning**: Define the scope, timeline, and security objectives.
3. **Audit Process**: 
   - Comprehensive code review
   - Vulnerability identification
   - Classification of security issues
   - Remediation recommendations
4. **Report Delivery**: Receive a detailed audit report with findings and guidance.
5. **Follow-up Support**: Optional verification of implemented security fixes.

## Use Cases

Zokyo security audits are well-suited for:

- **DeFi Projects**: Security assessment of financial smart contracts and protocols.
- **NFT Platforms**: Audit of NFT-related contracts and marketplaces.
- **GameFi Applications**: Security review of gaming and reward mechanisms.
- **Cross-Chain Solutions**: Validation of cross-chain implementations and bridges.
- **Startup Blockchain Projects**: Access to quality security reviews with reasonable requirements.

## Conclusion

Zokyo provides good-quality security audits that balance thoroughness with practical considerations. Their approach makes professional security services accessible to a range of projects building on Avalanche, with reasonable lead times and efficient processes. While maintaining good technical standards, Zokyo delivers actionable security insights that help projects improve their security posture without overwhelming resource requirements. 

# ACP-226 Dynamic Minimum Block Times for Sub-Second Blocks (/blog/226-min-block-times)

---
title: ACP-226 Dynamic Minimum Block Times for Sub-Second Blocks
description: ACP-226 replaces per-block gas cost with a dynamic minimum block delay to enable sub-second blocks, align with validator preferences, and prepare the network for higher gas targets.
date: 2025-09-04
authors: [meagfitzgerald]
topics: [ACP, Block Time, EVM Chains, Consensus, Performance]
comments: true
---

<YouTube id="v792NyX58sI" />

---

## What's Changing?

ACP-226 proposes swapping the old per-block gas cost for a simple, enforced minimum wait between blocks. New block header fields make 
sub-second blocks possible and keep spacing consistent. The delay naturally gravitates toward the stake-weighted median preference of
all validators (same control style as ACP-176), so cadence aligns with what validators actually want.

## Why Change the Current Mechanism?

The current gas check mechanism is overly complex and does not reliably prevent exceeding the target rate when priority fees already cover the
costs. No enforced minimum time between blocks can allow for bursts and risk periods of network instability.

ACP-226 introduces a minimum wait before the next block, enabling sub-second block production without network upgrades.

## How the Dynamic Delay Work?

The effective minimum delay uses a controller similar to ACP-176 with a dynamic Q parameter. Validators can set their
preferred minimum delay and the network will converge around the stake-weighted median. While the ACP-176 dynamic fee
mechanism still sets the target gas rate, ACP-226 reinforces network safety and prepares all the network's EVM chains for
higher gas targets and smoother UX.

## Looking Ahead

As gas targets climb, expect smaller, more frequent blocks and a snappier user experience. Streaming Asynchronous Execution (a.k.a. SAE, a.k.a. ACP-194) and ongoing
performance work make lower delays practical. We'll also share visuals that show how ACP-226 and ACP-176 fit together in practice.

## Want to Learn More?

Here are some resources to learn more about ACP-226, as well as future updates:
- [Read ACP-226](https://github.com/avalanche-foundation/ACPs/tree/main/ACPs/226-dynamic-minimum-block-times)
- [Join the discussion](https://github.com/avalanche-foundation/ACPs/discussions/228)
- [Follow AvaxDevelopers for updates, and sign up for future developer community calls](https://x.com/AvaxDevelopers/status/1958955055874548039)




# Scaling Web3 Distribution to 169M+ Telco Users with Avalanche (/blog/binary-holdings-avalanche-l1)

---
title: "Scaling Web3 Distribution to 169M+ Telco Users with Avalanche"
description: Learn how Binary Holdings deployed as an Avalanche L1, bringing more than 169 million users into the Avalanche ecosystem through telco partnerships.
date: 2025-09-29
authors: [thebinaryhldgs]
topics: [Avalanche L1, Blockchain, Powered By Avalanche]
---

## The Deployment That Changes Everything

The Binary Holdings (TBH) has deployed its native blockchain, The Binary Network, as an Avalanche L1, instantly bringing **169 million+ users** into the Avalanche ecosystem. This isn't some theoretical mass adoption. It's already happening now, all powered by Avalanche's L1 architecture.

## Why Build an Avalanche L1?

### Sovereign Blockchain Architecture

Avalanche L1s are independent, sovereign blockchains that operate with their own rules, virtual machines, and tokenomics while leveraging Avalanche's proven infrastructure.

For Binary Holdings, this means:
- **Custom EVM optimizations** for telco-scale operations
- **Native **$BNRY** tokenomics** without external dependencies
- **Direct validator participation** from partners
- **Built-in compliance** through pre-KYC'd users by telco partners

### Performance Metrics That Matter

- 169M+ accessible users (Indonesia & Philippines telcos)
- Currently in early stages with an airdrop campaign to drive more users
- 100+ redemptions already completed

## Technical Implementation

### Core Architecture

**OneWave PWA Integration**: OneWave is Binary Holdings' Progressive Web App (PWA) which functions as a Web3 dApp store embedded directly within telco applications. Users earn **$BNRY** tokens by engaging with dApps, which can be redeemed for phone bills, internet packages, or eCommerce goods.

The tokens flow directly to users' [Enkrypted Wallets](https://enkrypted.io/auth) - our proprietary crypto wallet solution.

The system embeds Web3 directly into existing telco apps through:
- iFrame-based dApp integration
- JWT token swaps for cross-chain interactions
- Chain-agnostic partnerships (we forge partnerships with dApps on any chain)
- Real-time **$BNRY** distribution controlled by our product team

### Security

Integration with FailSafe firewall provides security features, while partnership with Zeeve enabled the migration from our previous infrastructure to an Avalanche L1.

### Interchain Messaging (ICM)

ICM enables native cross-chain communication, allowing Binary Network to connect with 70+ other Avalanche L1s and maintain ecosystem-wide interoperability for future expansion.

## Check Out Our Numbers

### Current State

| Metric | Value |
|--------|-------|
| **Accessible Users** | 169M+ (Indonesia, Philippines telcos) |
| **Daily Transactions** | Millions (and growing) |
| **Redemptions** | 100+ completed |
| **dApp Partners** | Multiple chains |
| **Activity** | Airdropping **$BNRY** to drive traffic to OneWave |

### Vision & Growth

- **Our 2025 Target**: Onboard 1 billion telco users globally
- **Token Evolution**: Make **$BNRY** transferable for cross-border remittances, pooling loyalty points, and off-ramping fiat
- **Ecosystem Support**: 15,000 USD worth of [**$BNRY** credits](https://binaryavalanchegrants.notion.site/The-Binary-Holdings-x-Avalanche-Credit-Program-26b0b1ea9fae8025ae51ec2023f6addd) for qualifying dApps to advertise in OneWave

### Boosting the Avalanche Developer Ecosystem

Binary Holdings strengthens Avalanche through:

- **169M+ user distribution** network access for dApps via OneWave
- **15,000 USD worth of **$BNRY** credits** for qualifying projects. Can be used to advertise in prime spots within OneWave and boost traffic
- **dApp integration via iFrames**
- **Open partnership model** accepting any blockchain for integration. Engagement with dApps that live on other chains, is reflected on their native chain.

## Mass Adoption with Avalanche

Binary Holdings' L1 deployment proves that blockchain mass adoption requires Web3 to meet users where they are. 

With more than 169 million users accessible today through our partnerships with the largest telcos in Indonesia and Philippines, Binary Network is not theorizing about adoption. *We are executing it, one transaction at a time*.

**More Resources**:
- Binary Network Explorer: [explorer-binaryholdings.cogitus.io](https://explorer-binaryholdings.cogitus.io/)
- Grants Program: [binaryavalanchegrants.notion.site](https://binaryavalanchegrants.notion.site/)
- Website: [thebinaryholdings.com](https://www.thebinaryholdings.com/)


# Native Safe Multisig Support for Avalanche L1s in Builder Console (/blog/builder-console-safe-support)

---
title: Native Safe Multisig Support for Avalanche L1s in Builder Console
description: Learn how Builder Console now supports Safe, the leading account abstraction and smart wallet platform.
date: 2025-10-01
authors: [owenwahlgren]
topics: [Avalanche L1, Safe, Builder Console]
---

[Avalanche Builder Console](/console) now pre-deploys the [**Safe Singleton**](https://github.com/safe-global/safe-singleton-factory/tree/main) into your L1’s genesis at a canonical address. Normally, the Safe Singleton has to be deployed directly by the Safe team. By including it at genesis, Avalanche enables you to **self-service your Safe setup**—no need to wait for the Safe team to deploy it. To complete integration, you still need to deploy the additional Safe contracts and make a PR with your chain metadata to the Safe repositories. Alternatively, you can use the Safe deployments managed by the Ash team at [wallet.ash.center](https://wallet.ash.center/welcome).

---

## What You Get at Chain Launch

* **Pre-deployed Safe Singleton** in genesis
* **Address (canonical):** `0x914d7fec6aac8cd542e72bca78b30650d45643d7`
* **Availability:** Present from block 0; no post-launch deployment required for the singleton

Because the singleton is included in genesis, you don’t need to coordinate with the Safe team to deploy it. This makes it possible to move forward independently with setting up Safe on your chain.

![image](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/builder-console-safe-genesis)
---

## What Else You Need to Set Up

The genesis deployment includes **only the Safe Singleton**. To enable full Safe functionality and UI support, you must:

1. **Deploy the supporting contracts** from the [safe-deployments repository](https://github.com/safe-global/safe-deployments):

   * Safe ProxyFactory
   * MultiSend and MultiSendCallOnly
   * FallbackHandler or CompatibilityFallbackHandler (depending on your version)
2. **Verify contracts** on your block explorer so tools and SDKs can interact correctly.
3. **Ensure RPC endpoints and explorer APIs** are stable and publicly available for indexing.

---

## How to Get Your Chain in the Safe UI

To be recognized by the **official Safe Web App**, your chain must be added to the Safe **Transaction Service** (TS). This is done by opening a PR to the relevant Safe repositories with your chain’s metadata and contract addresses.

### Drafting the PR

Follow the contribution process in [safe-deployments](https://github.com/safe-global/safe-deployments). At a minimum, you’ll need to provide:

* **Chain metadata**: chainId, name, shortName, native token details
* **Public RPC endpoints** (HTTPS and optionally WebSocket)
* **Block explorer URL and API details**
* **Safe contract addresses** deployed on your chain:

  * Safe Singleton (pre-deployed by Builder Console)
  * ProxyFactory
  * MultiSend / MultiSendCallOnly
  * FallbackHandler
* **Gas/fee settings**: details on EIP-1559 support, native currency symbol/decimals

Once reviewed and merged, your chain can be supported natively in the Safe Web App via the official TS.

---

## Alternative: Use Ash Team’s Deployments

If you don’t want to manage the deployments or PR process yourself, you can leverage the Safe deployments and infrastructure managed by the **Ash team**. Their UI and service are available at:

➡️ [wallet.ash.center](https://wallet.ash.center/welcome)

This provides an out-of-the-box option for interacting with Safes on Avalanche L1s without running your own Transaction Service.

---

## Key Takeaways

* **Normally**: the Safe Singleton is deployed by the Safe team.
* **With Builder Console**: the Safe Singleton is included at genesis, so you can self-service your Safe setup.
* **Still required**: deploy additional Safe contracts (ProxyFactory, MultiSend, FallbackHandler) and submit a PR with your chain’s metadata and addresses to [safe-deployments](https://github.com/safe-global/safe-deployments).
* **Alternative option**: use the Ash team’s Safe deployments and UI at [wallet.ash.center](https://wallet.ash.center/welcome).

---

## Get Started

* Launch your L1: **[https://build.avax.network/console](https://build.avax.network/console)**
* Safe contracts and deployment repo: **[https://github.com/safe-global/safe-deployments](https://github.com/safe-global/safe-deployments)**
* Alternative Safe UI: **[https://wallet.ash.center/welcome](https://wallet.ash.center/welcome)**

Start your project with secure multisig primitives from genesis, then complete your setup by deploying the remaining contracts and registering your chain for UI support.


# Cortina: X-Chain Linearization (/blog/cortina-x-chain-linearization)

---
title: "Cortina: X-Chain Linearization"
description: Paving the way for broader X-Chain adoption, improving the UX of staking on the P-Chain, and allowing for more complex transactions on the C-Chain.
date: 2023-03-30
authors: [AvaxDevelopers]
topics: [Network Updates, Cortina Upgrade, X-Chain, P-Chain, C-Chain, Consensus]
comments: true
---

![Cortina: X-Chain Linearization](https://www.avax.network/_astro/65ce1a58b0011dc1f9a94e7c_1_CCP-46v8qu_epfQ4oH8fpQ_ZIq1nU.webp)

Paving the way for broader X-Chain adoption, improving the UX of staking on the P-Chain, and allowing for more complex transactions on the C-Chain.

---

On Monday, April 3rd, 2023, the pre-release code for the Avalanche Cortina Upgrade will be published. This upgrade will activate at 11 A.M. ET (3 P.M. UTC) on Thursday, April 6th, 2023. **Note, this pre-release code will ONLY work on Fuji.** If you run the code on Mainnet, it will exit on startup.

Pending a successful Cortina Upgrade on Fuji, the Avalanche Mainnet activation time will be announced and the official Cortina AvalancheGo release (v1.10.0) will be published.

The Cortina Upgrade includes protocol optimizations that are not compatible with AvalancheGo versions < v1.10.0. If you run a node on Fuji, you must upgrade your software to AvalancheGo >= v1.10.0 **before** the activation time on Fuji. **If you are a Mainnet node operator, there is no action required until the official AvalancheGo@v1.10.0 code is published.**

## X-Chain Linearization

The X-Chain runs [Avalanche Consensus](https://arxiv.org/pdf/1906.08936.pdf), a leaderless, DAG-based protocol that allows for the concurrent processing of non-conflicting UTXOs at high throughput without establishing a total ordering of activity. The C-Chain, P-Chain, and all Avalanche Subnets, on the other hand, run [Snowman++](https://github.com/ava-labs/avalanchego/blob/master/vms/proposervm/README.md), a chain-based, totally-ordered protocol that sequences conflict-free block production without time-based slots over thousands of participants.

The existing semantics of the X-Chain prevent or significantly complicate the integration of [Avalanche Warp Messaging](https://medium.com/avalancheavax/avalanche-warp-messaging-awm-launches-with-the-first-native-subnet-to-subnet-message-on-avalanche-c0ceec32144a) (AWM), the addition of complex X-Chain transactions, the enablement of state syncing, and broad exchange support. AWM integration requires Snowman++ to verify the [BLS Multi-Signature](https://crypto.stanford.edu/~dabo/pubs/papers/BLSmultisig.html) of incoming messages from other Avalanche Subnets. This limitation means the X-Chain, in its current form, cannot interact with Subnets and that the DAG-based consensus it runs cannot be broadly applied to Subnets, which overwhelmingly wish to communicate seamlessly with other Subnets. The partial-ordering on the X-Chain means there is no canonical state during vertex verification (a vertex is the container for batching transactions on the X-Chain, akin to a block in a blockchain) and that vertices are, by design, processed in a different order on different nodes. Without a canonical state, interacting with shared on-chain objects, such as exchanges, and state syncing to the tip of the network (to avoid re-processing all historical activity) becomes a non-trivial and error-prone problem that takes away from the time the community could spend further evolving Subnets. Finally, the non-deterministic ordering of on-chain activity greatly impedes the ability of many legacy exchanges to integrate with the X-Chain in its current form, as most legacy exchanges are designed for totally-ordered blockchains such as Bitcoin and Ethereum, and they have difficulty reconciling balances at different points in time on a partially-ordered blockchain.

Cortina migrates the X-Chain to run Snowman++ consensus and operate as a totally-ordered blockchain in a process called "linearization". When linearization begins, it will no longer be possible to add additional vertices to the X-Chain DAG. The terminal state of the DAG, now immutable, will then be used as the genesis state of the linearized X-Chain powered by Snowman++. The transaction format used on the X-Chain and the APIs to submit transactions, fetch transaction status, and fetch balance will not change during this process, so most wallets will not need to make any changes to support this linearization event. However, explorers that support the X-Chain will need to migrate to parsing X-Chain blocks instead of parsing X-Chain vertices, which look very similar to P-Chain blocks. Linearization is seamless and should not result in any downtime on the P-Chain, C-Chain, or any Subnets. The X-Chain will, however, be briefly inaccessible.

As alluded to above, this migration paves the way for Avalanche Warp Messaging integration, novel transaction types that modify shared X-Chain state, provides a straightforward path to enable state syncing, and enables exchanges to support the X-Chain, which will contain many of the tokens used on Elastic Subnets. While it is possible to introduce a total ordering over a DAG, doing so on the X-Chain would have required a rewrite of the existing Avalanche Consensus engine and would not have been useful for any Subnets. Migrating to a single consensus engine across the entire Avalanche Network, which reduces the size of the trusted computing base and increases the leverage of existing R&D efforts, will enable faster development and more broadly-applicable innovation.

We've prepared a migration guide for integrators [here](https://build.avax.network/docs/api-reference/x-chain/api) that highlights all changes to the AvalancheGo APIs required to support Cortina.

## Batched Delegator Rewards

Since the launch of the Avalanche Network, validators have had the opportunity to charge a service fee to anyone that delegates to their node. If a validator is online for 80% of a delegation period, they receive a % of the reward (the fee) earned by the delegator. The P-Chain distributes this fee as a separate UTXO per delegation period.

![Delegator Rewards Diagram](https://images.ctfassets.net/voq4a5ue459o/1f3582ac2c0c7e3dc5ba7b3175a67746/fbba1b9d2db4e6f5d28f4f1915627bfe/642610015bdc6509dbf97bbf_1_54JcPIBMZNU1_bkmOapOrQ.png?w=1600&q=80&fm=webp)

As the number of delegators on the network increased substantially over the last few months (up to ~80k as of 3/20/23), the number of UTXOs that a validator may receive as fees also increased substantially. This often means that a validator will end up with thousands of small UTXOs that must be aggregated to be used for anything. Tracking thousands of UTXOs in explorers and wallets also makes providing a great UX more challenging than it needs to be.

Cortina modifies how these delegation fees are distributed for all validators that begin staking after the Cortina Activation (previously staked validators will see no change). Instead of sending a fee UTXO for each successful delegation period, fees are now batched during a node's entire validation period and are distributed when it is unstaked.

## Increased C-Chain Gas Limit

Since Apricot Phase 1, the C-Chain block gas limit has been [set to 8M gas](https://github.com/ava-labs/coreth/blob/b1223203dbca7708142b8884f46a4deec678d80e/params/avalanche_params.go#L21). Blocks on the C-Chain are produced every ~2s, so this setting limits the max amount of gas that can be consumed every 10s to ~40M gas. The gas target for every rolling 10s window, however, is set to [15M gas](https://github.com/ava-labs/coreth/blob/b1223203dbca7708142b8884f46a4deec678d80e/params/avalanche_params.go#L32). This means that when more than 15M gas is used in a 10s window, the gas price will go up (and go down when less than 15M is used). You can read more about how dynamic fees work on the C-Chain [here](https://medium.com/avalancheavax/apricot-phase-three-c-chain-dynamic-fees-432d32d67b60).

Outside of limiting the amount of gas that can be consumed in some window at any gas price, the block gas limit also limits the complexity of transactions that can be issued in a single block. As different developers on Avalanche began to deploy more complex dApps, they've expressed that 8M gas per block isn't enough for their use case. Cortina increases the C-Chain block gas limit to 15M gas. To avoid increasing the amount of resources required to validate the Primary Network, the gas target will remain unchanged at 15M gas per 10s.

## FAQ

### How do I upgrade my node?

The process to upgrade to AvalancheGo v1.10.0 is the same as any other upgrade. If you build from source, run the build script as before. If you use the pre-compiled binaries, invoke them as before. If you use the [installer script](https://build.avax.network/docs/nodes/using-install-script/preparing-environment), use that as before.

Once you start AvalancheGo v1.10.0, you do not need to do anything else. More information on updating a node can be found [here](https://docs.avax.network/nodes/maintain/upgrade-your-avalanchego-node). As a reminder, it is best practice to [have a backup](https://docs.avax.network/nodes/maintain/node-backup-and-restore) of your staking key/certificate.

### Do I have to upgrade my node?

If you don't upgrade your validator to v1.10.0 before the Avalanche Mainnet activation date (which will be shared in coming days), your node will be marked as offline and other nodes will report your node as having lower uptime, which may jeopardize your staking rewards.

### Is there any change in hardware requirements?

No.

### Will updating decrease my validator's uptime?

No. As a reminder, you can check your validator's estimated uptime using the [info.uptime API call](https://build.avax.network/docs/api-reference/info-api).

![API Call Screenshot](https://images.ctfassets.net/voq4a5ue459o/3d4db985173559c8152c66d947eaa8c6/a55abcafa1a6a4fc0d82719ce5185ea9/6426100118a8ff0a95f40712_1_2zL1ZrQY8vKffH9fVcy4Ig.png?w=1600&q=80&fm=webp)

### I think something is wrong. What should I do?

First, **make sure that you've read the** [documentation](https://docs.avax.network/) **thoroughly and checked the** [FAQs](https://support.avax.network/en/)**. If you don't see an answer to your question, go to our** [Discord](https://chat.avalabs.org/) **server and search for your question. If it has not already been asked, please post it in the appropriate channel.**


# Deploy a DApp on the C-Chain with Foundry (/blog/deploy-a-dapp-on-c-chain-with-foundry)

---
title: Deploy a DApp on the C-Chain with Foundry
description: This guide shows how to deploy and interact with smart contracts using foundry on a local Avalanche Network and the Fuji C-Chain.
date: 2024-05-26
authors: [ashngmi, martin_eckardt]
topics: [solidity, foundry, Avalanche Starter Kit]
---

Foundry toolchain is a smart contract development toolchain written in Rust. It manages your dependencies, compiles your project, runs tests, deploys, and lets you interact with the chain from the command-line.

# Recommended Knowledge

- Basic understanding of Solidity and Avalanche.
- You are familiar with Avalanche Smart Contract Quickstart.
- Basic understanding of the Avalanche's architecture

# Run Avalanche Starter Kit

import SetUp from "@/content/common/avalanche-starter-kit/set-up.mdx";

import defaultMdxComponents from "fumadocs-ui/mdx";

<SetUp components={defaultMdxComponents}/>

# Create a Smart Contract

Create a new Solidity file in the `src` directory of your project. For example, `src/MyContract.sol`.

```solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

contract MyContract {
    uint256 public myNumber;

    function setNumber(uint256 _num) public {
        myNumber = _num;
    }
}
```

# Create Deployment Address

You can create a new wallet with the case command:

```bash
cast wallet new
```

# Fund Your Account

**Option 1 (Recommended):** Create a [Builder Hub account](https://build.avax.network/login) and connect your wallet to receive testnet AVAX automatically.

**Option 2:** Use the [Avalanche Testnet Faucet](https://core.app/tools/testnet-faucet/?subnet=c&token=c) with code `avalanche-academy25`

# Deploy the Smart Contract

With foundry's `forge` command, you can deploy your smart contract to the Fuji C-Chain.

```shell
forge create --rpc-url fuji-c --private-key <private-key> src/MyContract.sol:MyContract
```



# Durango: Avalanche Warp Messaging Comes to the EVM (/blog/durango-avalanche-warp-messaging)

---
title: "Durango: Avalanche Warp Messaging Comes to the EVM"
description: Native cross-chain communication comes to every EVM Chain in the Avalanche Ecosystem.
date: 2024-02-01
authors: [AvaxDevelopers]
topics: [Network Updates, Durango Upgrade, Avalanche Warp Messaging, EVM, Interoperability, P-Chain]
comments: true
---

![Durango: Avalanche Warp Messaging Comes to the EVM](https://www.avax.network/_astro/65bc11f33d8a959ccaee46f2_durango_20test4_GXxOE.webp)

The publishing of the pre-release code for a proposed upgrade to the Avalanche Network, codenamed Durango

---

**Update (2/21/24):** The production code [AvalancheGo@v1.11.0](https://github.com/ava-labs/avalanchego/releases/tag/v1.11.0) for the proposed Durango Upgrade was published. If sufficient stake supports Durango, it will activate on the Avalanche Mainnet at **11 AM ET on Wednesday, March 6th, 2024**. Durango contains ACPs that are not compatible with < v1.11.0 (Cortina). If Durango activates and you do not upgrade your node **before** the activation time, your node will be unable to process new blocks and will be marked as offline by other nodes (impacting your node's uptime and potentially jeopardizing your staking rewards). You can track support for ACP-23, ACP-24, ACP-25, ACP-30, ACP-31, ACP-41, and ACP-62 (included in Durango) on snowpeer: [https://snowpeer.io/acps](https://snowpeer.io/acps)

**Update (2/13/24):** Durango activated successfully on the Fuji Testnet this morning at 11 AM ET!

---

The [pre-release code](https://github.com/ava-labs/avalanchego/releases/tag/v1.11.0-fuji) for a proposed upgrade to the Avalanche Network was published for activation on the Fuji Testnet at 11 A.M. ET (4 P.M. UTC) on Tuesday, February 13th, 2024. This proposed upgrade, codenamed Durango, consists of Avalanche Community Proposals (ACPs) [\[ACP-23\] P-Chain Native Transfers](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/23-p-chain-native-transfers/README.md), [\[ACP-24\] Activate Shanghai EIPs on C-Chain](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/24-shanghai-eips/README.md), [\[ACP-25\] Virtual Machine Application Errors](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/25-vm-application-errors/README.md), [\[ACP-30\] Integrate Avalanche Warp Messaging into the EVM](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/30-avalanche-warp-x-evm/README.md), [\[ACP-31\] Enable Subnet Ownership Transfer](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/31-enable-subnet-ownership-transfer/README.md), [\[ACP-41\] Remove Pending Stakers](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/41-remove-pending-stakers/README.md), and [\[ACP-62\] Disable AddValidatorTx and AddDelegatorTx](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/62-disable-addvalidatortx-and-adddelegatortx/README.md).

**Note, this pre-release code will ONLY work on Fuji. If you run the code on Mainnet, it will exit on startup.** The Durango Upgrade includes protocol optimizations that are not compatible with AvalancheGo versions < v1.11.0. If you run a node on Fuji, you must upgrade your software to AvalancheGo >= v1.11.0 **before** the activation time on Fuji. **If you are a Mainnet node operator, no action is required.**

Pending a successful activation on the Fuji Testnet of all [implementable](https://github.com/avalanche-foundation/ACPs?tab=readme-ov-file#acp-statuses) ACPs, Avalanche Validators can choose to update their nodes to a production release of Durango (yet to be published) that supports the ACPs on Avalanche Mainnet. **Reminder: Avalanche Validators can** [signal](https://x.com/_patrickogrady/status/1748074273275822364?s=20) **their support for ACPs.**

## Cross-Subnet Interoperability

The first native Cross-Subnet message was sent on Avalanche Mainnet using Avalanche Warp Messaging (AWM) [on December 22nd, 2022](https://x.com/_patrickogrady/status/1605989086451597313?s=20). Following this milestone, [ACP-30](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/30-avalanche-warp-x-evm/README.md) proposed activating AWM on the C-Chain and Subnet-EVM. Activating this ACP brings native cross-chain communication to every EVM Chain in the Avalanche Ecosystem and establishes a standard for future VMs to communicate using AWM.

With AWM, there are no third party intermediaries or trust assumptions outside of the validator set of the Primary Network and the communicating Subnets. With only the validators of a Subnet, every Avalanche Subnet can send messages to one another. AWM leverages the Avalanche P-Chain as a registry of all Subnets' validator sets including a BLS Public Key for each validator.

To send a message, an [untrusted relayer](https://github.com/ava-labs/awm-relayer) or [user](https://github.com/ava-labs/hypersdk/blob/4bd6d720a5bc8ab9c6361e05f3c00d9c4780720d/examples/tokenvm/tests/e2e/e2e_test.go#L710-L748) aggregates signatures from a threshold of the Subnets' participating stake. Once it has received signatures from a threshold of stake, it constructs a [BLS Multi-Signature](https://crypto.stanford.edu/~dabo/pubs/papers/BLSmultisig.html) and a bit set to specify which validators have included a signature. For a receiving Subnet to verify the message, it looks up the validator set of the source Subnet at the current P-Chain height from its local database, checks that the total weight of included validators meets the required threshold, aggregates the specified BLS public keys, and then verifies the signature against the resulting aggregate public key. Any relayers broadcasting invalid BLS Multi-Signatures will be ignored.

**Note, no transactions/messages are included in the P-Chain to send an Avalanche Warp Message. Messages are passed directly between communicating Subnets or between a Subnet and the C-Chain.**

![AWM Architecture Diagram](https://images.ctfassets.net/voq4a5ue459o/4f048dc2a414c1a60bb67c7b299581b3/fe273d73529d1bbff8a3390e37f4eb7c/65bc12b118fad82932fc4693_KLrCXnfqjgHu9ltWr39vbTzOEfiYVFWu4O6GUGiVXll3XMCnAFVROeKf2q625pV0h0YSo7G2UywgsS9cocU3V6gRsoIOrdxoIC3.png?w=1600&q=80&fm=webp)

This lightweight protocol replaces the management of point-to-point connections with the simplicity of one unified registry: the Avalanche P-Chain. For the full details on how this is integrated into the EVM, see [ACP-30](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/30-avalanche-warp-x-evm/README.md).

In order to use AWM, a threshold stake of the Subnet's validators need to register BLS keys via 'AddPermissionlessValidatorTx'. [ACP-62](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/62-disable-addvalidatortx-and-adddelegatortx/README.md) proposes disabling 'AddValidatorTx' and 'AddDelegatorTx' to push all new stakers to use 'AddPermissionlessValidatorTx' and 'AddPermissionlessDelegatorTx'. Wide adoption of registered BLS keys not only enables Subnets to utilize AWM, but also accelerates the timeline for potential future P-Chain upgrades.

## Improving the Developer Experience

This upgrade also addresses some common requests from developers to improve the developer experience. These include adding P-Chain native transfers, enabling subnet ownership transfers, maintaining smart contract compatibility with Ethereum by supporting the Ethereum Shanghai Upgrade, and adding VM application errors.

Currently, users who want to transfer assets between P-Chain addresses either need to leave the P-Chain or use a transaction type not meant for native transfers. [ACP-23](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/23-p-chain-native-transfers/README.md) proposes supporting native transfers on the P-Chain with 'BaseTx'. By supporting native transfers on the P-Chain, users can manage their assets more efficiently and securely.

Another challenge for developers has been changing the owner of a Subnet, as currently the owner is immutable when new Subnets are created on the P-chain. Subnet operators may want to transition ownership of the Subnet to a new owner for a number of reasons, i.e. to perform a periodic rotation of the Subnet's control key(s). [ACP-31](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/31-enable-subnet-ownership-transfer/README.md) proposes allowing the current owner of a Subnet to transfer ownership to a new owner via 'TransferSubnetOwnershipTx'.

Durango also activates [ACP-24](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/24-shanghai-eips/README.md), which incorporates the changes from the Ethereum Shanghai Upgrade to ensure the C-Chain maintains smart contract compatibility with Ethereum. Specifically, EIP-3855 adds the PUSH0 opcode to the C-Chain, maintaining compatibility with Solidity versions >= v0.8.20. See the [ACP](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/24-shanghai-eips/README.md) for full details on the changes.

At the VM level, a peer cannot signal VM application errors, resulting in a network timeout and failed request. [ACP-25](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/25-vm-application-errors/README.md) proposes adding an 'AppError' message to indicate that an error has occurred. This allows a peer to signal failure early rather than wait for a timeout to fire, reducing the latency of a failed request from the network timeout (~2s) to a single network round trip time (~500ms).

## Starting the Path to 100k Subnets

To help further increase the scalability of the P-Chain, [ACP-41](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/41-remove-pending-stakers/README.md) proposes removing a user-specified 'StartTime' for stakers. This modifies the P-Chain to start a staker's staking period when the transaction is accepted. This greatly reduces the computation load on the P-Chain, increasing the efficiency of all Avalanche Network Validators and sets the stage for future P-Chain upgrades, including continuous staking (stake once and forget about it).

In addition to scaling the P-chain, key features will be needed in order to walk the "[Path to 100k Subnets](https://hackmd.io/@patrickogrady/100k-subnets)". Many of these will rely on BLS keys, whose wide adoption not only enables Subnets to fully utilize Avalanche Warp Messaging and to send cross-Subnet messages, but also accelerates the timeline for future P-Chain upgrades. These include, but are not limited to:

**Arbitrary Subnet Rewards:** The P-Chain currently restricts Elastic Subnets to follow the reward curve defined in a 'TransformSubnetTx'. With sufficient BLS key adoption, Elastic Subnets can define their own reward curve and reward conditions. The P-Chain can be modified to take in a message indicating if a Subnet validator should be rewarded with how many tokens signed with a BLS Multi-Signature.

**Subnet Attestations:** The Primary Network or a Subnet can attest to the state of their Subnet with a BLS Multi-Signature. This can enable clients to fetch the current state of the Subnet without syncing the entire Subnet. StateSync enables clients to download chain state from peers up to a recent block near tip. However, it is up to the client to query these peers and resolve any potential conflicts in the responses. With Subnet Attestations, clients can query an API node to prove information about a Subnet without querying the Subnet's validators. This can especially be useful for Subnet-Only Validators to prove information about the C-Chain.

As mentioned earlier, [ACP-62](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/62-disable-addvalidatortx-and-adddelegatortx/README.md) proposes the shift to the new BLS key tx type, 'AddPermissionlessValidatorTx', accelerating towards the future of BLS-powered advancements in the Avalanche Network.


# What to Expect After the Etna Upgrade (/blog/etna-changes)

---
title: What to Expect After the Etna Upgrade
description: This guide outlines the operational impact on existing network participants expected from the activation of the AvalancheGo "Etna" upgrade.
date: 2024-08-23
authors: [meagfitzgerald]
topics: [Avalanche Network Upgrade, Etna Upgrade, Validators, Layer 1, L1]
comments: true
---

This guide outlines the operational impact on existing network participants expected from the activation of the AvalancheGo "Etna" upgrade.

## Vocabulary, New and Old

- **L1**: An Avalanche Layer 1 Network. An L1 is a sovereign network that has its own dynamic set of validators, rules for network participation, and defines its own validator rewards incentives.
- **L1-validator**: A validator that only validates an Avalanche layer 1 blockchain. These validators are not required to stake 2000 AVAX, or validate the Avalanche Primary Network. They instead pay a continuous fee in order to participate in L1 validation.
- **ACP-77**: The Avalanche Community Proposal that outlines a new framework for creating low-cost, independent blockchains that can _easily_ interoperate with each other. You can read the full proposal [here](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/77-reinventing-subnets/README.md).
- **The Primary Network**: The Avalanche X,P, and C-Chains, a.k.a. the 3 primary blockchains that most validators currently sync on Avalanche Mainnet.

## What is Changing?

### Subnets Are Now Called L1s

Avalanche Subnets are being rebranded as Avalanche L1s. Unlike layer 2 blockchains, layer 1 blockchains operate independently without relying on other systems for their core functions.
They manage their own consensus mechanisms, transaction processing, and security protocols directly within their own networks.

Subnets have always operated this way, scaling Avalanche's network _horizontally_ instead of compounding dependencies by requiring chains to roll down to other networks.

### For Validators

L1 validators will no longer be required to sync the Primary Network’s X or C-Chain, drastically reducing the cost of operating a validator.

L1 validators will no longer be required to stake 2000 AVAX. Instead they will pay a substantially cheaper continuous fee calculated based on the number of L1 validators. The AVAX-denominated fee is a nominal amount per second and provides significant cost-savings for L1 validators.

### For New L1s

The ownership of validator set management will be moved from the P-Chain to individual L1 _ValidatorManager_ smart contracts.

- Essentially, validators will be managed by the L1s themselves instead of the P-Chain.

Sovereign L1s can easily be launched on Avalanche with a dynamic set of validators whose staking logic is defined and enforced by a _ValidatorManager_ smart contract deployed by the L1 creator. The smart contract deployed can enforce any network rules the creator desires, including but not limited to:

- A permissionless proof-of-stake blockchain where network participation is not controlled by any centralized authority
- A permissioned proof-of-authority blockchain where the validator set is controlled by a consortium or centralized authority

If the L1 is permissionless, the validator earns staking rewards by staking the asset specified by the L1; If the L1 is permissioned, the validator is controlled by a party specified by the L1 Owner and does not earn any rewards.

### For Existing L1s

Existing Avalanche Subnets _that wish_ to remove the 2000 AVAX per validator requirement will need to convert their Subnet’s control from a _P-Chain Owner Key_ to a _ValidatorManager_ smart contract via the workflow outlined in ACP-77.

- A detailed guide on how to convert existing L1s will be released prior to Testnet activation.

Existing L1s do not need to be converted if their validators continue to stake 2000 AVAX and validate the Primary Network.

## What is Staying the Same?

### For Validators

If you want to earn staking rewards for validating the Avalanche Primary Network, you will still need to stake 2000 AVAX per validator.

Existing validators can continue operating as they have before, and do not require any action. Updating to the latest release of AvalancheGo will not affect their operation.

### For L1s

Existing Avalanche L1s are not required to convert their pre-Etna validators to L1-only-validators; they will continue to operate as before.

All L1s will still be able to interoperate using Avalanche Warp Messaging (Avalanche ICM) and Teleporter (Avalanche ICM Contracts), regardless of how or when they were created.

## What Technical Changes Will be Included?

While driven by ACP-77, this upgrade will include many other feature additions outlined thoroughly in the following Avalanche Community Protocols:

**[ACP-77](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/77-reinventing-subnets/README.md)**: Outlines a new validator management framework for Avalanche L1s, creating low-cost, natively-interoperable blockchains.

**[ACP-103](https://github.com/avalanche-foundation/ACPs/pull/103)**: Introduces a dynamic fee mechanism to the X-Chain and the P-Chain, previewing a future transition to a multidimensional fee mechanism.

**[ACP-118](https://github.com/avalanche-foundation/ACPs/tree/main/ACPs/118-warp-signature-request)**: Proposes a standard `AppRequest` payload format type, simplifying potential AWM signature aggregation implementations.

**[ACP-125](https://github.com/avalanche-foundation/ACPs/tree/main/ACPs/125-basefee-reduction)**: Reduces the minimum base fee on the Avalanche C-Chain from 25 nAVAX to 1 nAVAX.

**[ACP-131](https://github.com/avalanche-foundation/ACPs/pull/131)**: Brings the EVM opcodes introduced by the Cancun Upgrade to the Avalanche C-Chain and Subnet-EVM.


# Etna: Enhancing the Sovereignty of Avalanche L1 Networks (/blog/etna-enhancing-sovereignty-avalanche-l1s)

---
title: "Etna: Enhancing the Sovereignty of Avalanche L1 Networks"
description: The Etna upgrade introduces sovereign L1 networks with 99.9% reduced costs, dynamic P-Chain fees, reduced C-Chain base fees, and standardized Interchain Messaging. Activated December 16, 2024.
date: 2024-12-02
authors: [AvaxDevelopers]
topics: [Network Updates, Etna Upgrade, Avalanche L1, ACP-77, Dynamic Fees, ICM, Sovereignty]
comments: true
---

![Etna: Enhancing the Sovereignty of Avalanche L1 Networks](https://www.avax.network/_astro/674e25e0ec7450feaab90afb_Etna_Announce_ZomV8V.webp)

The publishing of the release code for an upcoming network upgrade to the Avalanche Network, codenamed Etna.

---

## Intro

A release for the latest upgrade to the Avalanche Network, dubbed the "Etna" upgrade, was published for activation on Avalanche Mainnet scheduled for 12 PM ET (5 PM UTC), December 16, 2024. This proposed upgrade consists of Avalanche Community Proposals (ACPs) [\[ACP-77\]](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/77-reinventing-subnets/README.md) Reinventing Subnets, [\[ACP-103\]](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/103-dynamic-fees/README.md) Add Dynamic Fees to the P-Chain, [\[ACP-118\]](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/118-warp-signature-request/README.md) Warp Signature Interface Standard, [\[ACP-125\]](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/125-basefee-reduction/README.md) Reduce C-Chain minimum base fee from 25 nAVAX to 1 nAVAX, [\[ACP-131\]](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/131-cancun-eips/README.md) Activate Cancun EIPs on C-Chain and Subnet-EVM chains, and [\[ACP-151\]](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/151-use-current-block-pchain-height-as-context/README.md) Use current block P-Chain height as context for state verification. The prereleased code version was successfully activated on the Fuji Test Network at 11 AM ET (4 PM UTC), November 25, 2024.

The Etna Upgrade release includes protocol optimizations that are **not** compatible with AvalancheGo versions \<[v1.12.0](https://github.com/ava-labs/avalanchego/releases/tag/v1.12.0). If you run a node on Mainnet, you must upgrade your software to AvalancheGo >=v1.12.0 before the scheduled activation time. **If you are a Mainnet node operator, upgrading to v1.12.0 is mandatory.** The plugin version is unchanged at 38, and is compatible with [v1.11.13](https://github.com/ava-labs/avalanchego/releases/tag/v1.11.13).

## C-Chain Fees Reduced

This upgrade activates [ACP-125](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/125-basefee-reduction/README.md), which reduces the C-Chain transaction minBaseFee from 25 nAVAX to 1 nAVAX, a reduction of nearly 96%. This change has big implications for users, as it affects the lower bound of transaction fees under the EIP-1559 fee mechanism. This update simply lowers the floor for transaction fee pricing, making Avalanche transactions significantly cheaper during periods of low activity.

For context, the minBaseFee sets the minimum possible value for the base fee of all transactions on the C-Chain, as defined by EIP-1559. The base fee is a dynamic component of transaction fees that is adjusted based on the demand for block space. When the network is less congested, the base fee will decrease, approaching the minBaseFee, making transactions less expensive. At high demand, fees will increase proportionally with the load on the network, so the fees may be higher.

## Dynamic Fees Introduced On The P-Chain

A similar dynamic fee mechanism has also been introduced to the P-Chain in this upgrade, implemented according to the specification proposed by [ACP-103](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/103-dynamic-fees/README.md). With the previous fixed fee mechanism, P-Chain users were provided with simplicity and predictability, but network congestion and resource constraints weren't properly accounted for. Adding this dynamic fee mechanism has made it possible to significantly lower the transaction fees on the P-Chain, as it no longer relies on hard-coded, artificially high fees as the main DoS prevention mechanism. Furthermore, adding a fee mechanism that can more robustly handle spikes in load was necessary to prepare for the possibility of increased P-Chain usage following the new functionality added in [ACP-77](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/77-reinventing-subnets/README.md), which introduces five new P-Chain transaction types that perform Layer 1 (L1) validator management.

## A Network Of Sovereign Networks

[ACP-77](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/77-reinventing-subnets/README.md) introduces a mechanism for creating and operating a sovereign Layer 1 blockchain, aimed at addressing the biggest concerns around the existing Subnet architecture.

Etna introduces the ability to create sovereign Avalanche L1s, with lightweight, cost-efficient validation. Instead of staking 2000 AVAX, L1 validators will pay a dynamic continuous fee for L1 validation as defined by the ACP-77 specification, which should initially be approximately 1.3 AVAX per month. Unlike Subnet validation, L1 validators are not required to sync and validate the Primary Network. For an explanation on the distinction between Subnet and L1 validators, see [ACP-77](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/77-reinventing-subnets/README.md) for a note on the nomenclature.

This upgrade also enables L1s to enforce custom validator management logic with smart contracts. Projects can choose from conventional proof-of-authority and proof-of-stake [validator management contracts](https://github.com/ava-labs/icm-contracts/tree/main/contracts/validator-manager) made available by the Avalanche Platform engineers for the community to review or use as they see fit, or define their own staking logic with a custom smart contract, such as the contract proposed by community member Gauthier Leonard in [ACP-99](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/99-validatorsetmanager-contract/README.md). This unlocks a new level of network design for creators, enabling unlimited custom staking logic to be easily defined and enforced on L1 networks.

This new functionality significantly reduces the economic barrier to create and operate a blockchain (over 99.9% reduction in upfront costs), drastically reducing the required validator resources and defining a new industry standard for L1 network creation.

## Messages Ensured By An Entire Network

This upgrade includes [\[ACP-118\]](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/118-warp-signature-request/README.md) which proposes a VM-agnostic standard payload format for requesting signatures for Avalanche Interchain Messages. A valid ICM signature is produced by querying a blockchain's validator set, requesting a threshold majority sign a message confirming an event has or has not occurred on that chain, and then aggregating those signatures into a single BLS signature. Most of the new validator management transaction types introduced by ACP-77 require valid ICM signatures signed by either the source chain or the P-Chain to secure validator addition and removal.

ACP-118 standardizes the request and retrieval of Warp signatures, defining it as part of the AvalancheGo client such that VMs do not need to independently implement this logic. This will simplify signature aggregator implementations by allowing them to depend only on AvalancheGo for message construction, rather than individual VM codecs.


# Motivation behind Avalanche9000 (/blog/etna-upgrade-motivation)

---
title: Motivation behind Avalanche9000 
description: Learn about the largest network upgrade of Avalanche, that will lower the barrier to launch a blockchain and enable permissionless validation of L1s.
date: 2024-08-15
authors: [martin_eckardt, owenwahlgren]
topics: [Avalanche]
---

import EtnaUpgradeMotivation from '@/content/common/multi-chain-architecture/etna-upgrade-motivation.mdx';

<EtnaUpgradeMotivation />


# Avalanche C-Chain Throughput Increases as Validators Signal Higher Gas Targets (/blog/gas-target-increase)

---
title: Avalanche C-Chain Throughput Increases as Validators Signal Higher Gas Targets
description: Avalanche validators increase the C-Chain's target gas consumption by 30% thanks to the Octane upgrade, paving the way for higher throughput and future scaling optimizations.
date: 2025-08-21
authors: [AvaxDevelopers]
topics: [Validators, Gas Target, Octane Upgrade, SAE, Firewood]
comments: true
---

_Originally published by [@AvaxDevelopers](https://x.com/AvaxDevelopers/status/1958202141409247333)_

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/header.jpeg)
---

## Quick Take

- Positions Avalanche well to become one of the lowest latency, highest throughput EVM L1 experiences in the ecosystem.  
- Avalanche validators increased the C-Chain's target gas consumption by 30 % from 1.6 M to 2.1 M gas/sec.  
- The dynamic adjustments were enabled by the Octane upgrade, activated on April 6, 2025.  
- The Avalanche Foundation plans to continue signaling incremental increases as network metrics allow.  
- Future improvements like Streaming Asynchronous Execution (SAE) and Firewood Database integration aim to enable even larger increases.

Avalanche's C-Chain has seen its throughput capacity increase by over 30% following validator action to raise the target gas
consumption from 1.6 million to 2.1 million gas per second. The increase was made possible by the Octane upgrade that went live
on April 6th, 2025.

The gas target determines how much computational work the network can process per second, directly affecting how many transactions
and smart contract operations can be executed. For users of the chain, higher gas targets mean higher potential transactions per second,
and also lower transaction fees. For validators and node operations, higher gas targets can mean increased demands on hardware and network
infrastructure, which is closely monitored to ensure stability and reliability.
The dynamic adjustments were enabled by the Octane upgrade, activated on April 6, 2025.
Future improvements like Streaming Asynchronous Execution (SAE) and Firewood Database integration aim to enable even larger increases.

---

## Dynamic Gas Target Adjustment

[The Octane upgrade](https://www.avax.network/about/blog/octane-optimizing-c-chain-gas-fees) introduced the ability for Avalanche Primary Network validators to dynamically update the network's target utilization through
signaling their preferences. This mechanism allows the network to adjust capacity parameters without requiring hard forks or governance votes.

### How Validator Signaling Works

Under the new mechanism, validators can explicitly set their preferred gas target values. Validators that do not set a preference effectively abstain
from influencing the network's gas target by defaulting to whatever the current value is. The network calculates the effective gas target based on the
preferences of participating validators.

Since the upgrade's activation, validators run by the Avalanche Foundation have iteratively increased their gas target preferences, resulting in the
30% throughput increase observed across the network.

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/1.jpeg)

The Avalanche Foundation plans to continue gradually increasing their validator preferences while monitoring network performance metrics.
This approach aims to maximize C-Chain utilization within current infrastructure constraints. Upcoming optimizations like Streaming Asynchronous
Execution and the Firewood Database integration are expected to enable further increases.

Other validator operators can set their gas target preferences to participate in determining the network's effective throughput capacity.
This allows scaling decisions to reflect the technical assessment of the broader validator community.

---

### Network Health Monitoring

Several key performance indicators are closely monitored consistently through changes to the target gas consumption to ensure network stability:

- Block verification times - to ensure consensus remains stable

As the gas target increases, so does the maximum amount of gas able to be consumed in a given block. The more gas in a block, the longer time that
block will potentially take to execute. It's important that block execution times remain within an acceptable range to ensure that consensus is able
to proceed successfully.

Because blocks can have significantly different sizes depending on the time they are produced and gas capacity available at that instant, a holistic
way of viewing the amount of time spent in block execution is by looking at the percentage of time that a node uses to execute blocks during consensus.
We had earmarked less than or equal to 5% of time spent in block execution as a key performance indicator of consensus, and though a small initial
increase was observed, validator nodes were able to stay below that threshold.

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/2.jpeg)

- Disk usage and state growth rates - to monitor storage requirements

The higher the gas usage, the higher potential for state growth, and because all validators currently must maintain the full state of the chain on disk,
the more storage validators may need to have available to use.

Of course the larger the chain grows, the more disk space it will require to store it, but in increasing the gas target we wanted to ensure that the
rate of disk growth didn't become unsustainable, and in fact observed that disk usage continued to grow at a relatively constant rate of around 3 to 4
GB per day.

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/3.jpeg)

- Peer-to-peer network health - to monitor connectivity between all validator nodes

A key indicator of the health of the network as a whole is the percentage of successful queries made to peers. If any significant number of validator
nodes were to not be able to process the increased utilization level of the chain, they would not be able to respond to their peer's queries about block
proposals. Throughout the iterative increases to the gas target in June and July, we did not observe any noticeable decrease in the observed percentage
of successful queries, indicating that on the whole, the vast majority of nodes are still stable and able to keep up with the increased processing
demands created by the higher gas targets.

![](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/4.jpeg)

These metrics remained within acceptable parameters throughout the increase, indicating the network can handle the higher throughput without stability issues.

---

## Scaling Optimization Ahead

The 30% increase represents just the beginning of Avalanche's throughput expansion plans. Two major technical upgrades are in development that could
enable even more significant capacity improvements:

### Streaming Asynchronous Execution (SAE)  

As outlined in Avalanche Community Proposal ACP-194, SAE introduces a fundamental architectural change by separating block execution from the consensus
process. This allows for a continuous execution thread that operates independently of consensus, enabling gas targets to align with average-case execution
times rather than being constrained by worst-case scenarios.

The separation means the network can maintain higher throughput targets without risking consensus delays during computationally intensive blocks.

### Firewood Database Integration 

The upcoming Firewood database integration is designed to significantly improve performance of blockchain database operations, and also reduce validator
node storage requirements through optimized data layout and state pruning. By maintaining only recent state data and improving storage efficiency, Firewood
will reduce the operational burden on validators, potentially enabling support for higher gas targets.

---

## Looking Ahead

A combination of upcoming performance improvement efforts as well as continued iteration to dynamically determine the maximum chain capacity possible
at any given point in time positions Avalanche well to become one of the lowest latency, highest throughput EVM L1 experiences in the ecosystem.

Head to the Builders Hub to access everything you need to know about building on Avalanche: https://build.avax.network/

Follow us on X to keep up with all of the latest news, research and tooling for building on Avalanche: https://x.com/avaxdevelopers/


# How to Upgrade AvalancheGo to Granite (/blog/granite-installer)

---
title: How to Upgrade AvalancheGo to Granite
description: This guide shows how to upgrade AvalancheGo to Granite v1.14.0, the latest network upgrade with major improvements.
date: 2025-10-21
authors: [owenwg]
topics: [Granite Upgrade, AvalancheGo, Upgrade]
comments: true
---

import { Step, Steps } from 'fumadocs-ui/components/steps';

## Introduction

Avalanche Granite is the latest upgrade to the Avalanche network. It includes major improvements including P-Chain epoched views for ICM, secp256r1 support for biometric authentication, and dynamic minimum block times for faster transactions.

## Prerequisites

- An existing AvalancheGo node running any version prior to v1.14.0
- Basic command line knowledge
- Access to your node's terminal or SSH

## Backup Your Node First

Before upgrading your node, it's crucial to backup your staker files which identify your node on the network. These files are essential for recovering your node if anything goes wrong.

Run the following commands to backup your staker files:

```bash
cd
cp ~/.avalanchego/staking/staker.crt .
cp ~/.avalanchego/staking/staker.key .
```

Download these `staker.crt` and `staker.key` files and store them in a secure, private location. These files can be used to fully recreate your node if needed.

<Callout type="warning">
If you use your node for development purposes and have keystore users on your node, make sure to back those up as well.
</Callout>

## Primary Network Nodes

Choose one of the following methods to upgrade your Primary Network node to Granite:

### Method 1: Using the Installer Script (Recommended)

The easiest way to upgrade is using the AvalancheGo installer script.

<Steps>
<Step>

#### Get the Installer Script

If you don't already have the installer script, download it:

```bash
wget -nd -m https://raw.githubusercontent.com/ava-labs/avalanche-docs/master/scripts/avalanchego-installer.sh
chmod 755 avalanchego-installer.sh
```

</Step>
<Step>

#### Run the Installer

Execute the installer script:

```bash
./avalanchego-installer.sh
```

The script will automatically detect your existing installation and switch to upgrade mode:

```bash
AvalancheGo installer
---------------------
Preparing environment...
Found amd64 architecture...
Looking for amd64 version latest...
Node version found.
Attempting to download: 
   https://github.com/ava-labs/avalanchego/releases/download/v1.14.0/avalanchego-linux-amd64-v1.14.0.tar.gz
```

</Step>
<Step>

#### Automatic Upgrade

The script will:
1. Stop your current node
2. Download and install AvalancheGo v1.14.0 (Granite)
3. Restart your node with the new version

You'll see output similar to:

```bash
Node upgraded, starting service...
New node version:
avalanche/1.14.0 [network=mainnet, database=v1.4.0, commit=...]
Done!
```

</Step>
</Steps>

### Method 2: Docker

For Docker users, pull the new Granite image:

- **Docker Image**: [`avaplatform/avalanchego:v1.14.0`](https://hub.docker.com/r/avaplatform/avalanchego/tags?name=v1.14.0)

```bash
docker pull avaplatform/avalanchego:v1.14.0
```

### Method 3: Pre-Built Binary

1. Go to the [AvalancheGo releases page](https://github.com/ava-labs/avalanchego/releases)
2. Find version v1.14.0 (Granite release)
3. Download the appropriate file for your system:
   - **Linux (AMD64)**: `avalanchego-linux-amd64-v1.14.0.tar.gz`
   - **Linux (ARM64)**: `avalanchego-linux-arm64-v1.14.0.tar.gz`

4. Extract and run:

```bash
tar -xvf avalanchego-linux-amd64-v1.14.0.tar.gz
./avalanchego-v1.14.0-linux/avalanchego
```

### Method 4: Build from Source

For developers who want to build from source:

```bash
# Clone the repository (skip if already cloned)
git clone https://github.com/ava-labs/avalanchego.git
cd avalanchego

# Fetch and checkout Granite release
git fetch --all --tags
git checkout --force tags/v1.14.0

# Build the binary
./scripts/build.sh

# Verify the version
./build/avalanchego --version

# Run the node
./build/avalanchego
```

## L1s/Subnets Nodes

For nodes running L1s (formerly Subnets), you need to upgrade both AvalancheGo and the Subnet-EVM plugin:

### Method 1: Docker (Easiest)

Use the Docker image that includes both AvalancheGo v1.14.0 and Subnet-EVM v0.8.0:

- **Docker Image**: [`avaplatform/subnet-evm_avalanchego:v0.8.0_v1.14.0`](https://hub.docker.com/r/avaplatform/subnet-evm_avalanchego/tags?name=v0.8.0_v1.14.0)

```bash
docker pull avaplatform/subnet-evm_avalanchego:v0.8.0_v1.14.0
```

<Callout type="info">
This Docker image includes the Subnet-EVM v0.8.0 binary pre-installed, so no additional plugin installation is needed.
</Callout>

### Method 2: Manual Binary Update

If running AvalancheGo manually, you need to:

1. **Upgrade AvalancheGo** using any method from the Primary Network section above
2. **Update the Subnet-EVM plugin**:

```bash
# Stop your node first
sudo systemctl stop avalanchego

# Download the plugin (example for Linux AMD64)
wget https://github.com/ava-labs/subnet-evm/releases/download/v0.8.0/subnet-evm_0.8.0_linux_amd64.tar.gz
tar -xvf subnet-evm_0.8.0_linux_amd64.tar.gz

# Copy to plugins folder and rename to your VM ID
cp subnet-evm ~/.avalanchego/plugins/<YOUR_VM_ID>

# Restart your node
sudo systemctl start avalanchego
```

<Callout type="warning">
Ensure the plugin binary has the correct permissions and is renamed to match your L1's VM ID in the plugins directory.
</Callout>

## Verifying the Upgrade

After upgrading, verify you're running Granite by checking the node version.

### API Health Check

Run this curl command on your node machine to get detailed version information. You can also use the [API Health Check](/docs/api-reference/health-api#healthhealth) to check the node version.

```bash
curl -X POST --data '{
    "jsonrpc":"2.0",
    "id"     :1,
    "method" :"info.getNodeVersion"
}' -H 'content-type:application/json;' 127.0.0.1:9650/ext/info
```

You should see a response similar to:

```json
{"jsonrpc":"2.0","result":{"version":"avalanchego/1.14.0","databaseVersion":"v1.4.5","rpcProtocolVersion":"44","gitCommit":"dce38e90b1542fafa3c2b8efa8ef864d7a370eb6","vmVersions":{"avm":"v1.14.0","evm":"v0.15.4","platform":"v1.14.0"}},"id":1}
```

The `version` field should show `avalanche/1.14.0` confirming your node is running Granite.

## Stay Updated

To receive notifications about future upgrades:

1. **Avalanche Notify**: If you have a node, subscribe to the [Avalanche Notify service](/docs/nodes/maintain/enroll-in-avalanche-notify) with your node ID
2. **GitHub Notifications**: Watch the [AvalancheGo repository](https://github.com/ava-labs/avalanchego) and select "Releases" under custom notifications
3. **For L1s/Subnets**: Also watch the [Subnet-EVM repository](https://github.com/ava-labs/subnet-evm) for plugin updates

## Troubleshooting

If you encounter issues during the upgrade:

- Ensure you've properly backed up your staker files
- Check that your previous node version is completely stopped before upgrading
- For service-based installations, verify the service name (could be `avalanchego.service` or `avalanche.service`)
- For L1s/Subnets, ensure the Subnet-EVM plugin is updated to v0.8.0 and renamed to match your VM ID
- Join the [Avalanche Discord](https://discord.gg/avax) for community support


# Avalanche Granite Upgrade - Enhancing ICM, Unlocking Biometric Use Cases, and Enabling Dynamic Block Times (/blog/granite-upgrade)

---
title: Avalanche Granite Upgrade - Enhancing ICM, Unlocking Biometric Use Cases, and Enabling Dynamic Block Times
description: The Avalanche Granite upgrade activates on Fuji Testnet on October 29th, 2025, bringing major improvements including P-Chain epoched views for ICM, secp256r1 support for biometric authentication, and dynamic minimum block times for faster transactions.
date: 2025-11-05
authors: [AvaxDevelopers]
topics: [Granite Upgrade, ICM, Biometric, Block Time, ACP, Performance]
comments: true
---

## Introducing Avalanche Granite

The Mainnet [release](https://github.com/ava-labs/avalanchego/releases/tag/v1.14.0) for the latest upgrade to the Avalanche Network, dubbed "Avalanche Granite", has been published. The Mainnet activation is scheduled for **November 19th, 2025 at 11 AM ET (4 PM UTC)**.

**_Action Required_: All Mainnet node operators must upgrade their nodes to v1.14 before the scheduled activation time or risk operational failure.** For instructions on upgrading your node, see [this guide](https://build.avax.network/blog/granite-installer).

The [pre-release](https://github.com/ava-labs/avalanchego/releases/tag/v1.14.0-fuji) was published on October 21st, 2025 and successfully activated on the Fuji Testnet at 11 AM ET (3 PM UTC) on Wednesday, October 29th, 2025.

The Granite upgrade is driven by three Avalanche Community Proposals that significantly enhance the network's capabilities:

- [ACP-181: P-Chain Epoched Views](https://github.com/avalanche-foundation/ACPs/tree/main/ACPs/181-p-chain-epoched-views)
- [ACP-204: Precompile for secp256r1 Curve Support](https://github.com/avalanche-foundation/ACPs/tree/main/ACPs/204-precompile-secp256r1)
- [ACP-226: Dynamic Minimum Block Times](https://github.com/avalanche-foundation/ACPs/tree/main/ACPs/226-dynamic-minimum-block-times)

---

## Node Operator Requirements

### Mainnet Node Operators

**Action Required**: All Mainnet node operators must upgrade their nodes to **v1.14** before **11 AM ET (4 PM UTC) on November 19th, 2025**.

The Avalanche Granite Upgrade includes protocol optimizations that are not compatible with AvalancheGo versions < v1.14. If you run a node on Mainnet, you must upgrade your software to AvalancheGo >= v1.14 before the activation time. The plugin version is updated to 44. All plugins must update to be compatible. Ensure your node is running with the correct plugin version as specified in the [release notes](https://github.com/ava-labs/avalanchego/releases).


**Critical Warning**: All Mainnet nodes must upgrade before **11 AM ET, November 19, 2025**, or risk going offline once Granite activates. This warning applies to L1 validators who risk finalizing invalid blocks past the Granite activation time without epoch information if they fail to upgrade in time.

L1 validators **must** upgrade to the latest version of Subnet-EVM to be compatible with the Granite upgrade. [Learn more about upgrading your L1 to Granite](https://build.avax.network/blog/granite-installer#l1ssubnets-nodes).

### Fuji Testnet Node Operators

The Granite upgrade successfully activated on the Fuji Testnet at **11 AM ET (3 PM UTC) on Wednesday, October 29th, 2025**. Fuji node operators have upgraded their nodes to **[v1.14-fuji](https://github.com/ava-labs/avalanchego/releases/tag/v1.14.0-fuji)**, which includes protocol optimizations that are not compatible with AvalancheGo versions < v1.14-fuji. The plugin version is updated to 44.

**Please note**: This Fuji pre-release is unable to run on mainnet and will display "mainnet is not supported" if attempted with a mainnet configuration.

---

## Enhancing ICM Verification with P-Chain Epoched Views

This upgrade activates **ACP-181**, which significantly improves the robustness and cost-effectiveness of Interchain Messaging (ICM) verification on Avalanche's L1 chains.

### The Challenge

Previously, the P-Chain pointers were updated with every block, leading to validation uncertainty and potential invalidation of ICM messages due to continuous changes in the validator set. This created inefficiencies and increased costs for cross-chain message verification.

### The Solution

With ACP-181, the P-Chain height is fixed for an entire epoch period (approximately 5-10 minutes), providing a stable validator set view. This ensures ICM messages are verified against a consistent P-Chain height, reducing invalidation risk and lowering costs.

### Benefits for Developers

By allowing L1 chains to maintain a consistent view of the P-Chain, ACP-181 enhances the efficiency and reliability of ICM message handling across the network. Developers building cross-chain applications can now rely on:

- **Cheaper message verification** - Reduced computational overhead
- **More reliable cross-chain messaging** - Lower invalidation risk
- **Predictable validator set views** - Stable reference points for verification

[Watch the ACP-181 community call](https://youtu.be/1c6Qa1sobQg?si=eeTSG3pdPPNcAW_o) to learn more about the technical details.

---

## Unlocking New Biometric Use Cases with secp256r1

This upgrade introduces support for signature verifications using the **secp256r1 elliptic curve** via **ACP-204**, enabling innovative biometric data signing on the Avalanche network.

### New Capabilities

With secp256r1 curve support, developers can now implement biometric data signing, unlocking a range of new use cases:

- **Secure identity verification** through fingerprint or facial recognition
- **Enhanced user authentication** processes without traditional passwords
- **FaceID/TouchID-style logins** integrated directly into dApps
- **Seamless, secure transactions** with biometric confirmation

### Enterprise Applications

The integration of biometric data signing facilitates the development of decentralized applications that require high-security standards, such as:

- Digital identity platforms
- Secure access control systems
- Healthcare applications with HIPAA compliance
- Financial services with enhanced KYC/AML processes

ACP-204 expands the possibilities for biometric implementations, positioning Avalanche at the forefront of blockchain innovation. Developers can now deliver stronger security and a smoother user experience by integrating modern biometric authentication methods into their applications.

---

## Enabling Faster Transactions with Dynamic Minimum Block Times

This upgrade activates **ACP-226**, introducing a dynamic adjustment mechanism for block times on the Avalanche network, which enhances user experience by reducing latency.

### How It Works

ACP-226 allows validators to dynamically adjust block times in response to network improvements, such as the upcoming Streaming Asynchronous Execution (SAE) and Firewood features. This flexibility enables:

- **Sub-second block times** - Significantly faster than the previous fixed intervals
- **Continuous optimization** - Validators can adjust block times without network upgrades
- **Stake-weighted preferences** - Network converges around validator consensus

### The Impact

Previously, block rates could only be changed during network upgrades, creating rigid constraints on performance improvements. With ACP-226, validators can continuously optimize block times to match the network's evolving capabilities.

This upgrade ensures that users benefit from:

- **Quicker transaction finality** - Reduced time to confirmation
- **Lower end-user latency** - More responsive applications
- **Improved network efficiency** - Better resource utilization
- **Future-proof scalability** - Ready for upcoming performance enhancements

[Watch the ACP-226 community call](https://youtu.be/v792NyX58sI?si=2TfJpRg1Ju0AePs6) to learn more about the technical implementation.

---

## Looking Ahead

The Granite upgrade represents another significant step forward in Avalanche's evolution as a high-performance blockchain platform. By improving ICM reliability, enabling biometric authentication, and allowing dynamic block time adjustments, Avalanche continues to deliver the speed, flexibility, and scalability that developers need.

As the network continues to evolve with upcoming features like Streaming Asynchronous Execution (SAE) and Firewood Database integration, these Granite improvements lay the foundation for even greater performance enhancements.

---

## Summary of Changes

This section provides a technical overview of the changes introduced in the Granite upgrade for developers and node operators.

### New Block Headers (ACP-226)

Two new headers have been introduced as part of ACP-226 for dynamic block time management:

1. **`timestampMilliseconds`** (uint64) - Timestamp in milliseconds for more precise block timing
2. **`minDelayExcess`** (uint64) - Tracks the excess delay for dynamic block time adjustments

See the [full changelog](https://github.com/ava-labs/coreth/blob/master/RELEASES.md#pending-release) for implementation details.

### New Data Structures (ACP-181)

A new struct has been added as part of ACP-181 to support epoched P-Chain views:

- **`Epoch`** struct - Provides stable P-Chain height references for ICM message verification
  - [View implementation](https://github.com/ava-labs/avalanchego/blob/master/vms/proposervm/block/block.go#L58)

### New API Methods

Three new API methods have been added to support the Granite upgrade features:

1. **`proposervm.GetProposedHeight`** - Returns this node's current proposer VM height.
   - [Documentation](https://build.avax.network/docs/api-reference/proposervm-api#proposervmgetproposedheight)

2. **`proposervm.GetCurrentEpoch`** - Returns the current epoch information.
   - [Documentation](https://build.avax.network/docs/api-reference/proposervm-api#proposervmgetcurrentepoch)

3. **`platform.GetAllValidatorsAt`** - Get the validators and their weights of all L1s and the Primary Network at a given P-Chain height.
   - [Documentation](https://build.avax.network/docs/api-reference/p-chain/api#platformgetallvalidatorsat)

**Note**: While `platform.getProposedHeight` will not be immediately deprecated, you should switch to using `proposervm.getProposedHeight` for future compatibility.

### Node Configuration Changes

#### For L1 Operators

Add the `--min-delay-target` parameter to your [subnet-evm chain config](https://build.avax.network/docs/nodes/chain-configs/subnet-evm) to enable sub-second minimum block times:

```json
{
  "min-delay-target": <uint64_value>
}
```

#### For Primary Network Node Operators

Add the `--min-delay-target` parameter to your [C-Chain config](https://build.avax.network/docs/nodes/chain-configs/c-chain) to vote on the target minimum block time enforced by the proposerVM on the C-Chain:

```json
{
  "min-delay-target": <uint64_value>
}
```

---

## Resources

- [ACP-181: P-Chain Epoched Views](https://github.com/avalanche-foundation/ACPs/tree/main/ACPs/181-p-chain-epoched-views)
- [ACP-204: secp256r1 Curve Support](https://github.com/avalanche-foundation/ACPs/tree/main/ACPs/204-precompile-secp256r1)
- [ACP-226: Dynamic Minimum Block Times](https://github.com/avalanche-foundation/ACPs/tree/main/ACPs/226-dynamic-minimum-block-times)
- [AvalancheGo Releases](https://github.com/ava-labs/avalanchego/releases)
- [Join the discussion on GitHub](https://github.com/avalanche-foundation/ACPs/discussions)

---

## About Avalanche

Avalanche is a high-performance blockchain platform designed for builders who need to scale. Engineered with a revolutionary three-part Layer 1 (L1) architecture, Avalanche is anchored by its Avalanche Consensus Mechanism, ensuring near-instant finality for transactions. The platform also features an open-source Layer 0 (L0) framework, enabling the seamless creation of interoperable Layer 1 blockchains with high throughput on both public and private networks.

Supported by a global community of developers and validators, Avalanche offers a fast, low-cost environment for building the next generation of decentralized applications (dApps). With its unique blend of speed, flexibility, and scalability, Avalanche is the preferred choice for innovators pushing the boundaries of blockchain technology.

---

**Follow [@AvaxDevelopers](https://x.com/AvaxDevelopers) for updates and join our developer community to stay informed about future upgrades and tooling improvements.**


# Install Avalanche CLI (/blog/install-avalanche-cli)

---
title: Install Avalanche CLI
description: Avalanche CLI is a command line tool for accessing Avalanche, specializing in developing and testing subnets.
date: 2024-05-26
authors: [martin_eckardt]
topics: [Avalanche CLI]
---

Avalanche CLI is a command line tool that gives developers access to everything Avalanche. This release specializes in helping developers develop and test subnets. This guide shows you how to install Avalanche CLI on your machine.

## Compatibility

Avalanche-CLI runs on Linux and Mac. Windows is currently not supported.

## Instructions

To download a binary for the latest release, run:

```shell
curl -sSfL https://raw.githubusercontent.com/ava-labs/avalanche-cli/main/scripts/install.sh | sh -s
```

The script installs the binary inside the `~/bin` directory. If the directory doesn't exist,
it will be created.

## Adding Avalanche-CLI to Your PATH

To call the `avalanche` binary from anywhere, you'll need to add it to your system path. If you installed
the binary into the default location, you can run the following snippet to add it to your path.

```shell
export PATH=~/bin:$PATH
```

To add it to your path permanently, add an export command to your shell initialization script. If
you run `bash`, use `.bashrc`. If you run `zsh`, use `.zshrc`.

For example:

```shell
export PATH=~/bin:$PATH >> .bashrc
```

## Checking Your Installation

You can test your installation by running `avalanche --version`. The tool should print the running version.

## Updating

To update your installation, you need to delete your current binary and download the latest version
using the preceding steps.

## Building from Source

The source code is available in this [GitHub repository](https://github.com/ava-labs/avalanche-cli).

After you've cloned the repository, checkout the tag you'd like to run. You can compile the code by
running `./scripts/build.sh` from the top level directory.

The build script names the binary `./bin/avalanche`.

# Economics of L1 Blockchains: Deploying on Public Permissionless Chains vs. Your Custom L1 Blockchain (/blog/l1-economics)

---
title: "Economics of L1 Blockchains: Deploying on Public Permissionless Chains vs. Your Custom L1 Blockchain"
description: Discover the economic factors that influence the decision to deploy blockchain applications on public permissionless blockchains like Ethereum versus creating your own custom Layer 1 (L1) blockchain on Avalanche. This article explores the impact of transaction fees, validator incentives, and decentralization models, offering insights for developers to determine when launching a dedicated L1 makes sense. Ideal for developers and blockchain enthusiasts looking to optimize cost efficiency and user experience in decentralized applications.
date: 2024-08-30
authors: [martin_eckardt]
topics: [L1, Tokenomics]
comments: true
---

When considering the deployment of a blockchain application, developers often face a critical decision: Should the application be launched on an existing public permissionless blockchain like Ethereum, or should it operate on a specialized Layer 1 (L1) blockchain? The answer to this question depends on various factors, with transaction fees being among the most significant. Understanding the economic implications of each option is essential for making an informed choice that aligns with your project's goals and long-term success.

## Understanding Transaction Fees on Public Permissionless Blockchains

Public permissionless blockchains like Ethereum or Avalanche's C-Chain have an inherent structure where users pay transaction fees — commonly known as gas fees — in a token that holds real value (e.g., ETH or AVAX). These fees compensate the network validators for securing and processing transactions on the blockchain. The fee is determined by supply and demand dynamics, with users bidding on the limited block space available to include their transactions.

The challenge with this model is that gas fees can fluctuate wildly based on network activity. During periods of high demand—such as NFT drops, DeFi protocol launches, or bull markets—transaction fees can spike to levels that deter users from interacting with your application. For applications with many low-value transactions, these high fees can become prohibitive, leading to decreased user adoption and engagement. This is particularly problematic if your users are not even aware that they are interacting with a blockchain, as is often the case with mainstream applications.

To mitigate this, developers might implement gas sponsoring and account abstraction, where the application absorbs the cost of the transaction fees. However, this introduces a continuous cost for every interaction, which can become unsustainable, especially if the underlying asset's value (e.g., AVAX) increases significantly. For instance, if AVAX appreciates from $20 to $60, your gas sponsoring costs could triple, drastically altering your application’s economics.

## The Case for Launching a Custom L1 Blockchain

When considering the deployment of a blockchain application, the option to spin up your own L1 blockchain on Avalanche offers a compelling alternative. With your own L1, you have complete control over the transaction fee structure. This flexibility is invaluable, especially for applications with a high volume of low-value transactions. By setting transaction fees according to your specific economic model, you can ensure that fees remain low, predictable, and aligned with your users' needs.

For example, in a gaming application where users frequently make micro-transactions, high transaction fees on a public blockchain could be a significant barrier to user retention. By deploying your own L1, you can minimize or even eliminate these fees, thereby enhancing the user experience and driving higher engagement. This is particularly relevant for applications that target mainstream audiences, where a seamless and cost-effective user experience is paramount.

## Decentralization Considerations

When launching your own L1, it's crucial to consider how you will secure and govern the network. Some use cases might opt for a Proof of Authority (PoA) model with a permissioned validator set, where validators are pre-approved and known entities. This approach offers a higher degree of control but at the expense of decentralization.

On the other hand, if you choose a permissionless validator set using Proof of Stake (PoS), you need to ensure that your transaction fee structure sufficiently compensates the independent validators for their running costs and provides additional incentives. This is essential for maintaining a healthy and secure network, as validators need to be motivated to participate and uphold the integrity of the blockchain. Striking the right balance between validator incentives and user costs is key to the long-term success of your custom L1.

## When Does a Custom L1 Make Sense?

Deciding whether to deploy on a public blockchain or create your own L1 is ultimately about determining your breakeven point. Here are some key considerations:

#### Transaction Volume and Value
If your application processes a high volume of low-value transactions, a custom L1 may be more cost-effective in the long run. Conversely, if your application handles only a few high-value transactions, the cost savings may not justify the complexity of running a separate L1.
  
#### Fee Stability
On a public blockchain, you are at the mercy of network-wide fee fluctuations. With a custom L1, you can ensure fee stability, which is crucial for budgeting and long-term planning.

#### Infrastructure Costs
The primary cost of running an L1 is the infrastructure required to support the validator set. Once you establish an appropriate number of validators based on your security requirements, the operational costs become mostly fixed. These costs are independent of the number and complexity of the transactions processed on your chain, providing predictable financial outlays as your application scales.

## Conclusion

Launching a blockchain application on a public permissionless blockchain or spinning up your own L1 on Avalanche is a decision that depends heavily on your application's transaction profile and economic model. If you anticipate high transaction volumes with low individual values, a custom L1 could offer significant economical advantages in terms of fee management and user adoption. However, for applications with fewer, high-value transactions, the convenience and existing infrastructure of a public blockchain might be more appropriate.

Ultimately, the decision should be driven by a careful analysis of your transaction patterns, user experience goals, and the potential for fee volatility in public networks. By weighing these factors, you can make an informed decision that aligns with your application's long-term success.

# How Do L1 Validator Fees Work? (/blog/l1-validator-fee)

---
title: How Do L1 Validator Fees Work?
description: This guide provides an overview of how L1 validators are charged AVAX to participate in sovereign L1s, how the fee is determined, and how this information can be retrieved from the Avalanche P-Chain.
date: 2025-01-30
authors: [meagfitzgerald]
topics: [ Avalanche Network Upgrade, Etna Upgrade, Validators, Layer 1, L1, L1 Validators, Continuous L1 Validation Fee]
comments: true
---

## What are L1 Validators?

Introduced with ACP-77, [Avalanche L1 Validators](https://build.avax.network/guides/subnet-vs-l1-validators) enable the creation of sovereign L1
networks with minimal dependency on the Avalanche Primary Network. Unlike Subnet validators, L1 validators do not stake AVAX, but instead pay a
continuous dynamic fee called the L1 Validator Fee.

## L1 Validator Balance

This new fee mechanism takes advantage of the fact that each L1 validator uses the same amount of computation and charges every validator the same fee.

To charge L1 validators, a "Balance" system is used. This balance is charged continuously while a validator is active to cover costs of storing their
information (such as BLS key, weight, nonce) in active state and tracking their IP addresses. Each L1 Validator carries a balance, starting from when
the validator is added with the `RegisterL1ValidatorTx` transaction. It can be increased anytime using the `IncreaseL1ValidatorBalanceTx`. If the
balance reaches zero, the validator becomes "inactive" and stops validating. Once inactive, their properties are removed from memory and stored on
disk, and any messages from them will be invalid until they are revived. Inactive validators can be revived by re-upping their balance using
`IncreaseL1ValidatorBalanceTx`.

## How Fees are Charged

AvalancheGo calculates the accrued fees for a block based on the formula: fee rate (in nAVAX/sec) \* duration since the prior block (in seconds) for
every block. For each L1 validator, AvalancheGo tracks a value called the
[`endAccumulatedFee`](https://github.com/ava-labs/avalanchego/blob/ab4619873028fd975dfa6e89e53e555dd53e0cdb/vms/platformvm/state/l1_validator.go#L116-L124), which represents the total fees that will accumulate
in the future at the current rate. Once this value is reached, the validator will be marked as “inactive” due to the fact that its balance will not
cover the fees accrued until this final block.

When a validator registers with `RegisterL1ValidatorTx`, the balance of AVAX is allocated to that validator, and is continuously charged by the
P-Chain until it runs out. To prevent the balance from running out, and validation pausing, any validator can increase its balance with
`IncreaseL1ValidatorBalanceTx`. If a validator decides to end its validation with `DisableL1ValidatorTx`, any remaining balance that has not
been used to pay the continuous fee will be returned.

For example, imagine a world where in order to take a taxi, you must first deposit a lump sum upfront. As the taxi travels to your destination,
the fare for the distance travelled is continuously debited from your account. If during the drive you want to increase your balance so you can
travel farther, you can add funds to your balance. Once you end the ride, the driver would return any of the remaining balance to you.

## Who Pays and Who Gets the Change?

`IncreaseBalanceTx` must be used whenever an L1 validator wishes to increase their balance. This transaction can be executed by anyone, meaning that
anyone can increase the balance on behalf of another validator.

However, only the P-Chain address set as the `remainingBalanceOwner` when the validator originally registered with `RegisterL1ValidatorTx` can receive
the funds left over if the validator decides to terminate with `DisableL1ValidatorTx`. Your friend can throw you some cash to pay for your cab fare,
but only you can keep the change at the end of the ride.

## Retrieving Validator Fee Information

The current validator fee rate can be retrieved with the P-Chain API endpoint
[`platform.getValidatorFeeState`](https://build.avax.network/docs/api-reference/p-chain/api#platformgetvalidatorfeestate).

An L1 validator's available remaining balance can be retrieved using the P-Chain API endpoint
[`platform.getL1Validator`](https://build.avax.network/docs/api-reference/p-chain/api#platformgetl1validator).

The validator fee configuration, with the current parameters set to calculate the L1 validator fee rate according to the formula in [ACP-77](https://github.com/avalanche-foundation/ACPs/tree/main/ACPs/77-reinventing-subnets#parameters), can be
retrieved with the P-Chain API endpoint
[`platform.getValidatorFeeConfig`](https://build.avax.network/docs/api-reference/p-chain/api#platformgetvalidatorfeeconfig).

## How the Fee Changes

The L1 Validator Fee is calculated each time the P-Chain adds a new block, according to the algorithm outlined in
[ACP-77](https://github.com/avalanche-foundation/ACPs/tree/main/ACPs/77-reinventing-subnets#fee-algorithm):

$$ M \cdot \exp\left(\frac{x}{K}\right) $$

where M is the minimum price for validators, and exp(x) is an approximation of the exponential function based on the EIP-4844 specification. The
value K simply controls how quickly the price changes, and x is updated every second based on the difference between the number of active validators
V and the target T:

$$ x = \max(x + V - T, 0) $$

The max function above basically chooses either $(x + V - T)$, or 0, whichever is greater.

If the fees become too high, some validators may exit the set, which will lower x and subsequently reduce the price, helping to maintain an average of
T active validators on the P-Chain.

## The Fee Rate Settings

The parameters of the above functions at the time Etna activated were:

- T: target number of validators: 10,000
- C: capacity number of validators: 20,000
- M: minimum fee rate: 512 nAVAX/s
- K: constant to control the rate of fee changes: 1,246,488,515

As long as the number of validators stays below the target of 10,000, it will cost ~1.33 AVAX/month to run an L1 validator.

K was chosen to set the maximum fee doubling rate to ~24 hours. This is in the extreme case that the network has 20,000 active L1 validators for
prolonged periods of time. Alternatively, if the network has 10,001 L1 validators for a prolonged period of time, the fee rate would double every
~27 years.

In a nutshell, when the total number of L1 validators is greater than or equal to 10,000, the fee rate, a.k.a. the L1 validation fee per second, will
increase in the next block according to the formula. These parameters can be changed with community input and the implementation of any future ACP.

The validator fee configuration, with the current parameters set to calculate the L1 validator fee rate according to the formula in
[ACP-77](https://github.com/avalanche-foundation/ACPs/tree/main/ACPs/77-reinventing-subnets#parameters), can be retrieved with the P-Chain API
endpoint [`platform.getValidatorFeeConfig`](https://build.avax.network/docs/api-reference/p-chain/api#platformgetvalidatorfeeconfig).


# Avalanche Octane: Optimizing C-Chain Fees and Gas Target (/blog/octane-optimizing-c-chain-gas-fees)

---
title: "Avalanche Octane: Optimizing C-Chain Fees and Gas Target"
description: The Avalanche Octane upgrade activates ACP-176, enabling validators to dynamically adjust gas targets and implementing improved dynamic fee mechanisms for cheaper gas fees and better network scalability. Activated March 2025.
date: 2025-03-11
authors: [AvaxDevelopers]
topics: [Network Updates, Octane Upgrade, C-Chain, Gas Fees, ACP-176, Dynamic Fees, Validators]
comments: true
---

![Avalanche Octane: Optimizing C-Chain Fees and Gas Target](https://www.avax.network/_astro/67d1a457d18ffe0b373442ab_Screenshot_202025-03-12_20at_208.12.08_E2_80_AFAM_ZQpDwI.webp)

This upgrade activates ACP-176, which positions the Avalanche C-Chain to have cheaper gas fees and better handle future increases in network demand.

---

A [pre-release](https://github.com/ava-labs/avalanchego/releases/tag/v1.13.0-fuji) for the latest upgrade to the Avalanche Network, dubbed the "Octane" upgrade, has been published. The Avalanche Octane upgrade is scheduled to activate on the Fuji Testnet at 11 AM ET (3 PM UTC) on Thursday, March 13, 2025. The upgrade is driven by Avalanche Community Proposal 176 [\[ACP-176\]](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/176-dynamic-evm-gas-limit-and-price-discovery-updates/README.md), titled: Dynamic EVM Gas Limits and Price Discovery Updates. Following successful activation and testing on the Avalanche Fuji Testnet, an Avalanche Mainnet release will be published, with a set future activation time.

**Fuji node operators must upgrade their nodes to** [v1.13.0-fuji](https://github.com/ava-labs/avalanchego/releases/tag/v1.13.0-fuji) **prior to 11 AM ET (3 PM UTC) Thursday, March 13, 2025.** The pre-release includes protocol optimizations that are **not** compatible with AvalancheGo versions \<v1.13.0-fuji. The plugin version is unchanged at 39 and is compatible with version v1.12.2. Please note that this release is unable to run mainnet, and will display "mainnet is not supported" if attempted to run with a mainnet configuration.

**If you are a Mainnet node operator, upgrading to v1.13.0 before the set activation time is mandatory, ensuring the client is running with the correct plugin version.** The Octane Upgrade release includes protocol optimizations that are **not** compatible with AvalancheGo versions \<v1.13.0. If you run a node on Mainnet, you must upgrade your software to AvalancheGo >=v1.13.0 before the scheduled activation time. Activation time and plugin version for mainnet nodes will be specified in the release notes when the mainnet release is published.

## Improving the Dynamic Fee Mechanism on the C-Chain

The Avalanche Octane upgrade activates [ACP-176](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/176-dynamic-evm-gas-limit-and-price-discovery-updates/README.md), which positions the Avalanche C-Chain to have cheaper gas fees and better handle future increases in network demand.

Currently, the C-Chain operates with a static gas target of 15,000,000 gas per 10-second rolling window, using a modified version of the EIP-1559 dynamic fee mechanism. This mechanism has a notable drawback: it can lead to large spikes in gas prices following large blocks that consume their full gas limit. Even smaller subsequent blocks within the same window can trigger further price increases, creating inefficiencies in fee predictability.

The fee mechanism introduced to the C-Chain improves the handling of blocks that consume large amounts of gas by implementing the same mechanism introduced in [ACP-103](https://github.com/avalanche-foundation/ACPs/blob/main/ACPs/103-dynamic-fees/README.md) to determine the base fee of a block. Adding this dynamic fee mechanism has made it possible to significantly lower the transaction fees on the C-Chain. Gas fee simulations were performed and discussed publicly in an [Avalanche Developer Community Call](https://www.youtube.com/watch?v=NcjgpG-bU-k). Results have been published and shared [publicly](https://docs.google.com/document/d/1vSNbeaQSi96Pl5EhOMA6WM2uuzGASDVqMtHLkaegP4M/edit?tab=t.0#heading=h.9kukhbsvclk6).

## Validator Voting on Target Gas Consumption

The Avalanche Octane upgrade also includes modifications to allow block proposers (i.e. validators) to dynamically adjust the target gas consumption rate.

Prior to the Octane upgrade, changing the C-Chain's static target gas consumption rate required a network upgrade, making it difficult to adapt to performance optimizations or hardware advancements in a timely manner. ACP-176 proposes a more flexible and efficient solution by introducing dynamic gas target adjustments based on the preference of Primary Network Validators. While validators can set default configuration values for the desired target gas consumption rate, each validator can alternatively choose to set this value independently based on their own considerations.

This upgrade empowers validators to dynamically adjust the target rate of gas consumption, ensuring the network can scale more effectively in response to varying loads and future growth. A validator that values high transactions per second (TPS) and lower gas fees may vote to increase the gas consumption over time by setting their preference higher than the historical target. The higher the target gas consumption, the more resources that are able to be used by the network. Validators should consider whether their machine will be able to reliably support the resources that are required to properly support that level of gas consumption when choosing their preferred gas target.

This change builds on Avalanche's commitment to providing a low-cost, high-performance blockchain experience. By enabling dynamic gas limits and refining price discovery, the upgrade enhances the C-Chain's ability to maintain stable and predictable transaction fees, even during periods of high demand.

## About Avalanche Blockchain Network

Avalanche is a high-performance blockchain platform designed for builders who need to scale. Engineered with a revolutionary three-part Layer 1 (L1) architecture, Avalanche is anchored by its Avalanche Consensus Mechanism, ensuring near-instant finality for transactions. The platform also features an open-source Layer 0 (L0) framework, enabling the seamless creation of interoperable Layer 1 blockchains with high throughput on both public and private networks.

Supported by a global community of developers and validators, Avalanche offers a fast, low-cost environment for building the next generation of decentralized applications (dApps). With its unique blend of speed, flexibility, and scalability, Avalanche is the preferred choice for innovators pushing the boundaries of blockchain technology.

[Website](https://avax.network/) | [Whitepapers](https://avalabs.org/whitepapers) | [X](https://twitter.com/avax) | [Discord](https://chat.avalabs.org/) | [GitHub](https://github.com/ava-labs) | [Documentation](https://docs.avax.network/) | [Telegram](https://t.me/avalancheavax) | [Facebook](https://facebook.com/avalancheavax) | [LinkedIn](https://linkedin.com/company/avalancheavax) | [Reddit](https://reddit.com/r/avax) | [YouTube](https://www.youtube.com/c/Avalancheavax)


# Playing in the P2P Network: Investigating Anomalies in Avalanche's Transaction Gossip (/blog/p2p-network-anomalies)

---
title: "Playing in the P2P Network: Investigating Anomalies in Avalanche's Transaction Gossip"
description: A deep dive into how we detected and mitigated anomalous behavior in Avalanche's P2P network, where MEV actors were exploiting transaction gossip protocols to gain unfair advantages.
date: 2025-09-05
authors: [stephenbuttolph, martin_eckardt]
topics: [P2P Network, MEV, Transaction Gossip, Network Security]
comments: true
---

## Setting things up.

Why bother trying to attack a blockchain that's designed to be resilient when you could just [pretend to be someone's grandchild](https://www.fcc.gov/consumers/scam-alert/grandparent-scams-get-more-sophisticated)? Well, in **P2P (Peer-to-Peer) networks** (a.k.a the wild-west of blockchain systems), gaining even a slight edge can result in massive profits.

**That's why engineers working on a blockchain must pay attention to their P2P network.**

Despite looking cramped and chaotic to some, P2P network dashboards typically reflect a network steadily making progress, albeit occasionally observing packet loss during [monsoon season](https://forums.xfinity.com/conversations/your-home-network/ipv4-packet-loss-on-windy-afternoons/6087431943a1b761d4e812db?commentId=60db3dd83aae1c503595e417&replyId=60db410b4be6c333aae6cb0c) (yes, I've gotten woken up over stuff like this). 

Occasionally, a dashboard hints at something more interesting, like the game of cat-and-mouse revolving around transaction gossip and MEV.

On a recent summer day, one of our monitoring dashboards showed an imbalance between the inbound and outbound volume of "app" messages—those used in Avalanche's transaction gossip layer. We were receiving significantly more requests than we were sending, and the responses we were sending back were consuming a suspiciously large portion of validator bandwidth.

![graph bandwidth messages](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/P2P_1.png)

At first glance, it wasn't clear exactly what was happening. Maybe our metrics were off. Maybe there was a bug in the networking logic. But the imbalance held over time, and the asymmetry was too big to ignore. **Something was wrong.**

## A quick detour: How Avalanche gossip works.

Avalanche spreads transactions through a hybrid **push–pull gossip protocol** over its P2P network.

**Push gossip**: Newly issued transactions are pushed to validators across the network, especially those with more stake.*

**Pull gossip**: A validator periodically sends a [Bloom filter](https://en.wikipedia.org/wiki/Bloom_filter) describing its mempool to another uniformly sampled validator, who compares it with their own and responds with any new transactions.

The "pull" math is simple and powerful. Every validator samples uniformly once per second, so each validator should receive about one Bloom filter request per second.

When it comes to the rate of receiving a request from a specific validator, it depends on the size of the validator set:

- Fuji has **~100 validators**, and Mainnet has **~1,000 validators**.
- Fuji nodes are expected to get a request from a specific node **every ~2 minutes**
- On Mainnet, **the expected rate is higher at ~17 minutes.**

*Validators with more stake are prioritized because they're most likely to build the next block.

## The unexpected behavior: It is always the C-Chain mempool.

On the Fuji Testnet, these metrics behaved exactly as expected.

![Graph C-chain Messages Received Fuji](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/P2P_2.png)

What we observed on Mainnet wasn't even close.

![Graph C-chain Messages Received Mainnet](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/P2P_3.png)

Our Mainnet nodes were consistently handling 20x the expected number of Bloom filter requests. Additionally, the hit-rates of the Bloom filters were bimodal—an anomaly not seen on Fuji.

While most requests had a high hit-rate (>75%), many requests had an abysmal 0% hit-rate. Almost no requests landed in-between.

![Graph Hit-Rate](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/P2P_4.png)

This led to the suspicion that certain nodes were **intentionally** sending Bloom filters that didn't match any transactions in our mempool. That's like saying: "I don't have any of your transactions—send me everything you've got."

Intentional or not, they weren't sending bad Bloom filters once every 17 minutes (the rate at which a virtuous validator would). The worst offenders* were hammering the same validators with requests as quickly as **every 8 seconds** (0.125 bad Bloom filters per second).

![Graph C-Chain Mempool Bad Blooms per Second](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/P2P_5.png)

This meant that targeted validators were repeatedly sending **maximum sized responses—potentially** hundreds of transactions at a time—to the same small set of peers.

Sending too many Bloom filters is one thing. Sending bad Bloom filters is unacceptable! We worked hard to [optimize every CPU cycle](https://github.com/ava-labs/avalanchego/pull/2622) of those Bloom filter checks! For THIS!?!? Unacceptable.

Interestingly, even non-validators have been asked for mempool information. While these nodes wouldn't receive the initial push gossip, they may have locally issued transactions in their mempools. Although, this could have just been an oversight in the modified implementation.

*Worst offenders:
- NodeID-MuEFvXvbZ964sk1rdQKWNtUc5PJAGkWeL
- NodeID-NHEESrJJNnyCPn5c5Uyp9EZYHCCkZwzuW
- NodeID-MZV1PpqVuFPa56t7TmfA8VVdXxDSHnQW7
- NodeID-LPf42gVqz97N6bogZGXJNTWhgBABEe4qE
- NodeID-3632EmwYracXebFyFTQvcEC7U6VREbPkZ
- NodeID-2KSietvSEq4mX2C8p1DAT83RTJPykxUqN
- NodeID-AyByRGSrfbDaeW4njEYwCzhsnMyZ2KMcw
- NodeID-8fq1H8oStMi9BZrEk8qiE8QAV7AtqGnXt
- NodeID-EtFG3SrbbudeFQCaWRxhwvv28wHpo8VRq

## The Update: MOAR rate limits.

Avalanche already has a rate limit for Bloom filter requests, so what gives? 

When the Bloom filter requests were originally added, the algorithm was slightly different. Rather than sampling a random validator every second, 10 validators were randomly sampled every 10 seconds.

This meant that a node should never see more than **2 requests every 10 seconds** from the same node, even when accounting for time skew. As such, the rate limiting logic enforced this bound.

However, this sampling approach had two clear downsides:

1. **Wasted bandwidth.**
   Sending the same Bloom filter to multiple nodes made it likely that we would receive duplicate transactions.

2. **High discovery latency.**
   Sending requests every 10 seconds resulted in high discovery latency for nodes not included in the push gossip phase.

When changing to send **one** request every second we didn't make any changes to the rate limit logic. After doing some [quick calculations](https://stattrek.com/online-calculator/binomial), we can see that this was great for virtuous nodes and amazing for MEVers–our rate limit was **hundreds of times** looser than it needed to be.

### The fix:

**Instated probabilistic bounds.**
Instead of a flat cap, we now calculate the expected number of requests, and the variance, from the binomial distribution. On mainnet, this works out to about **10 requests per hour per peer** while still ensuring that honest nodes will almost never get rate-limited.

**Reinforce rate limits.**
Rather than immediately dropping rate limited requests, these requests are included in future rate limiting calculations. This enforces nodes to query no faster than the prescribed rate.

## The results

Immediately upon updating, our nodes reported a significant reduction in outbound bandwidth.

![Graph Result Bandwidth Messages](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/P2P_6.png)

By enabling the improved rate limiting, the total outbound bandwidth was reduced from 320 KiB/s to 200 KiB/s, almost a 40% reduction. These Bloom filter responses (blue) are now replaced with Rate limited responses (yellow), which utilize almost no bandwidth.

![Graph Result Message Count % for Messages](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/P2P_7.png)

Additionally, we observed that we are now rate-limiting the Bloom filters with a low hit-rate. We are now only responding to Bloom filters with a high hit-rate.

![Graph Result Hit-Rate](https://qizat5l3bwvomkny.public.blob.vercel-storage.com/P2P_8.png)

We expect MEV actors to adapt over time. Hopefully, they'll stop sending bad Bloom filters to maximize their limited queries. Regardless, the days of nearly unlimited pull gossip requests are over. DUN DUN DUUUUUUNNNNNNN 

## Reflections

This change didn't aim to reduce MEV on Avalanche. If you post a sloppy swap with wide slippage, you'll still get sandwiched. That's the nature of open, transparent blockchains (for now).

What it does is **protect the network itself**. Validators will no longer waste resources streaming their mempools to adversaries hundreds of times per hour. The gossip layer is back to working as designed: efficient and predictable.

These investigations are my favorite part of working on Avalanche. Sometimes, protocol development turns into a chess game played in code and metrics, with real money on the line.


# Validator Rewards and Staking Mechanisms on Avalanche L1s (/blog/staking-and-validator-management)

---
title: Validator Rewards and Staking Mechanisms on Avalanche L1s
description: This article provides an overview of the mechanics of how L1's can manage their validator set and how the software and infrastructure architecture can affect future integrations.
date: 2025-03-01
authors: [meagfitzgerald]
topics: [ Staking Tokens, L1 Validators, Validator Management]
comments: true
---

## What are L1 Validators?

Introduced with ACP-77, [Avalanche L1 Validators](https://build.avax.network/guides/subnet-vs-l1-validators) 
enable the creation of sovereign L1 networks with minimal dependency on the Avalanche Primary Network. 
Each L1 manages their own validators with a validator manager smart contract.

## What is a Validator Manager Smart Contract? 

A Validator Manager smart contract (VMC) is one or many smart contracts that work together to define the logic for
L1 validator addition and removal on an Avalanche L1.

ACP-77 enables any Avalanche L1 to independently manage its own validators. When an L1 network is established, the
Avalanche P-Chain requires each L1 to specify the address that controls the validator set. This address is
responsible for using Inter-chain messaging (ICM) to correspond with the P-Chain, notifying the network whenever a
validator is added or removed from the L1. This address should be set to the contract address of the chosen PoA or
PoS VMC. 

The ICM-Contracts repository hosts a standard suite of [validator-manager](https://github.com/ava-labs/icm-contracts/blob/main/contracts/validator-manager/README.md)
smart contracts that can define standard,
minimal functionality for either PoA and PoS L1 networks. This library is maintained by the Avalanche Platform
Engineers, and is open to use and extension by any developer in the ecosystem.

## Where Can I Deploy the Validator Manager Contract? 

The contract for controlling the validators of any L1 can be deployed on any blockchain in the Avalanche Network. Most
chains will choose to deploy their validator manager contract on either (a) the Avalanche C-Chain or (b) the L1 it
controls. 

## Proof-of-Authority Networks

If building a Proof-of-Authority (PoA) network, ideally the VMC should be deployed on the L1 chain it is managing so
that the native gas token can be used to pay for validator management transactions. Due to the nature of PoA chains,
the validators would be managed by the creators of the chain, meaning any transactions paid for with the L1's native
gas token would be given the chain creator owns most, if not all of the supply. Without the requirement to stake any
tokens in order to validate, PoA chains can create and instantiate the validators at the time of chain creation, and
maintain the [P-Chain validator fee](https://build.avax.network/guides/l1-validator-fee) for the foreseeable future.

## Proof-of-Stake Networks

If designing a Proof-of-Stake (PoS) Avalanche L1, the validator manager contract must be deployed on the same 
blockchain as the reward token that is being distributed, accompanied by a contract to [calculate validation rewards](https://github.com/ava-labs/icm-contracts/blob/main/contracts/validator-manager/ExampleRewardCalculator.sol). 
The reward token can be either an ERC20 token or the native token of the L1. The VMC must have minting privileges 
for the reward token, either by enabling the Native Minter Precompile if the VMC is deployed on the L1 it controls,
or via the [ERC20Mintable](https://github.com/ava-labs/icm-contracts/blob/main/contracts/validator-manager/interfaces/IERC20Mintable.sol) interface provided in the ICM-Contracts repo if the VMC is deployed on C-Chain or a 
blockchain other than the L1 itself. Ultimately, the staking token must have a supply that's controlled exclusively 
by the VMC and L1 blockchain itself. 

Because most cryptocurrency exchanges, custodians, and onramps are more likely to sync and index older, more 
established chains, deploying the VMC and ERC20 Staking Token contracts on the Avalanche C-Chain, in most cases, 
would expedite the time needed to have the staking token listed. The ERC20 staking token VMC controls the supply 
and distribution of the staking token when rewarding validators. 

However, if a PoS L1 aims to use transaction fees as a mechanism for generating validator rewards, implementing 
[native token](https://github.com/ava-labs/icm-contracts/blob/main/contracts/validator-manager/README.md#nativetokenstakingmanager)
staking offers a streamlined approach to reward distribution. By using the network's native token for 
staking, transaction fees collected from users can be directly recycled and distributed to validators without the 
need for complex processes like burning and re-minting tokens. This simplifies the economic model, reduces 
operational overhead, and ensures a more efficient flow of value within the ecosystem. 

It's important to note that a counterargument exists against the use of transaction fees for value accrual: most
blockchains aim to have the lowest gas fees possible. A better user experience for transactors on-chain usually
includes a fee that is so low, you barely notice it. If the fee is as low as possible, it wouldn't be a great
method of value accrual for an L1's validators; instead of this, the chain can employ a token emissions or token 
inflation scheme, such as the many tokenomics models present on chains like [Avalanche](https://build.avax.network/docs/quick-start/avax-token#tokenomics)
and [Ethereum](https://consensys.io/blog/your-guide-to-ethereum-validator-staking-rewards). Other mechanisms
can also be employed, such as using fees generated by any on-chain applications to [buy back](https://hyperliquid.gitbook.io/hyperliquid-docs/trading/fees)
tokens and either hold them in a fund or distribute them to the community.

Regardless of the choice of reward mechanism, native token staking using the ICM-Contracts implementation must be
deployed on the L1's blockchain. Staking rewards are minted by enabling the Native Minter Precompile on the L1's
Subnet-EVM binary, which is configured with a set of addresses with minting privileges of the L1's native token.
As such, the EVM address that NativeTokenStakingManager is deployed to must be added as an admin to the precompile.

Because the supply of the native token will be controlled on the L1 itself, a native staking token may still be
bridged to Avalanche C-Chain as a Wrapped ERC20 token and listed on exchanges without the need to index the L1 
chain. 

## Conclusion

In summary, managing L1 validators on Avalanche involves deploying and configuring Validator Manager Contracts
(VMCs). These contracts, which can be customized for Proof-of-Authority (PoA) or Proof-of-Stake (PoS) networks,
dictate how validators are added and removed. The deployment location of the VMC, along with the choice of reward
mechanism (ERC20 tokens or native tokens), are critical design decisions that impact the L1's functionality and
integration with the broader Avalanche ecosystem. 

Developers looking to implement or extend these functionalities can leverage the standard suite of validator-manager
smart contracts available in the [ICM-Contracts](https://github.com/ava-labs/icm-contracts/blob/main/contracts/validator-manager/README.md)
repository. Detailed information can be found in the [developer documentation](https://build.avax.network/docs/cross-chain/teleporter/overview).



# Subnet & L1 Validators, What's the Difference? (/blog/subnet-vs-l1-validators)

---
title: Subnet & L1 Validators, What's the Difference?
description: This guide defines the difference between Subnet and L1 validators, differentiating the roles and responsibilities of each.
date: 2024-12-04
authors: [meagfitzgerald]
topics: [Avalanche Network Upgrade, Etna Upgrade, Validators, Layer 1, L1, L1 Validators, Subnet Validators]
comments: true
---

The Etna Upgrade introduced L1s to the Avalanche network, providing an enhanced sovereign network design to the original Subnet model. 

**L1 Validators**, introduced with ACP-77, represent a departure from this model, enabling the creation of sovereign L1 networks with minimal dependency on the Primary Network. 
Unlike Subnet validators, L1 validators do not stake AVAX but instead pay a dynamic monthly fee, initially set at approximately 1.3 AVAX. 
They are exempt from validating the Primary Network, reducing their resource requirements and making L1 validation more accessible. 
This approach fosters economic inclusivity and sovereignty, allowing developers to define custom validation logic via smart contracts and operate independent networks without staking the Primary Network.  

## Primary Network Validators

Primary Network validators are responsible for processing transactions, securing the network, and participating in consensus and governance decisions. They must stake a minimum of 2,000 AVAX and validate all three primary network chains: the X, P, and C-Chain. 
These validators earn rewards in exchange for enhancing the security of the network. Their role is crucial for the seamless operation of the broader Avalanche ecosystem. 

As far as it relates to ACP-77 and the Etna Upgrade, the requirements for Primary Network validation **are not changing** with the Etna Upgrade. 

## Subnet Validators

Subnet validators are essentially Primary Network validators with additional permissions. They must:

- Stake 2,000 AVAX on the Primary Network
- Specify an "end time" for their validation period
- Sync and validate the Primary Network (X, P, and C-Chains)
- Sync and validate a specific Subnet 

For context, the creation of a Subnet involves issuing a `CreateSubnetTx` on the P-Chain, assigning an Owner Key to manage its validator set. 
After this, the holder(s) of the Owner Key can add and remove validators from the Subnet's validator set using the P-Chain transactions `AddSubnetValidatorTx` and `RemoveSubnetValidatorTx`. 
These transactions were created pre-Etna for Subnet management and are still valid post-Etna.

## L1 Validators

L1 validators are a new addition to the Avalanche ecosystem, introduced with ACP-77 and the Etna Upgrade. A Subnet can be converted 
by the Owner to a sovereign L1 with `ConvertSubnetToL1Tx`, a new P-Chain transaction introduced in this upgrade. This transaction revokes the authority to add and remove Subnet validators from the original Owner Key, and sets the validator
set management to the `address` specified. After a successful `ConvertSubnetToL1Tx`, `AddSubnetValidatorTx` is permanently disabled, and any validator set additions must be coordinated through a `RegisterL1ValidatorTx` (also introduced in ACP-77) which can only add **L1 validators**. 

L1 validators are required to:
- Pay a continuous dynamic fee, initially set at approximately 1.33 AVAX per month
- Sync and validate a specific L1
- Sync the latest P-Chain state

Syncing the P-Chain state is required for basic L1 functionality. It enables the L1 to track its validator weights so that it can perform consensus and validate ICM messages from other L1s, including the P-Chain.

L1 validators do not need to:
- Stake 2,000 AVAX
- Validate or participate in consensus on the Primary Network (X, P, and C-Chains)

Unless removed by the Owner Key, any Subnet validator added to the network before `ConvertSubnetToL1Tx` will continue to validate the network until its "end time" is reached.

Once a Subnet has been converted to an L1, Subnet validators can no longer be added. After a previous Subnet validator is removed or its "end time" is reached, a validator with
the name NodeID can be added as an L1 validator to the network with `RegisterL1ValidatorTx`, the same as any other L1 validator who wishes to join the network.


# Create a Telegram Mini-App using ThirdWeb SDK (/blog/telegram-miniapps-thirdweb)

---
title: Create a Telegram Mini-App using ThirdWeb SDK
description: This guide shows how to build a Telegram Mini-App using the ThirdWeb SDK on the Avalanche Fuji Network.
date: 2024-09-04
authors: [owenwahlgren]
topics: [solidity, typescript, Telegram, ThirdWeb]
---
import { Step, Steps } from 'fumadocs-ui/components/steps';

Telegram Mini-Apps are a new way to build and deploy applications and games embedded in the Telegram platform. They are built using ThirdWeb, a platform that allows developers to connect and utilize both external and in-app wallets on the Avalanche network.

Learn more about [ThirdWeb](https://thirdweb.com/).
## Recommended Knowledge

- Basic understanding of Solidity and Typescript.
- Basic understanding of Telegram Bots and the Telegram API.
- Basic understanding of the Avalanche Fuji Testnet.

## Getting started

<Steps>
<Step>
Create a template from the [ThirdWeb Telegram Mini-App Starter Kit](https://github.com/ava-labs/telegram-webapp-avalanche) by clicking the `Use this template` button on the top right.

![](/guide-images/telegram-miniapp/use-template.png)

**IMPORTANT!!** mark "Include all branches", otherwise Github pages deployment will not work.

![](/guide-images/telegram-miniapp/include-branches.png)

</Step>
<Step>
Clone the new repository & install the dependencies
```bash
git clone <new-repo-url>
cd <new repo>
yarn install
```
</Step>

<Step>
Get the `clientID` from a ThirdWeb account on the [ThirdWeb Dashboard](https://thirdweb.com/dashboard)
</Step>

<Step>
Create a `.env` file in the root of the project and add the `clientID` from the previous step:
```bash
VITE_THIRDWEB_CLIENT_ID=...
```
</Step>

<Step>
Run the project in development mode
```bash
yarn dev
```
</Step>
</Steps>

On `git push` to the `main` branch, the project will be automatically deployed to Github Pages.

Follow the section below to link a Telegram Bot to the webapp.

## Integrating with Telegram Bots
<Steps>
<Step>
Create a new Telegram Bot using [BotFather](https://t.me/botfather)
<Steps>
    <Step>
    Type `/newbot`
    </Step>
    <Step>
    Choose a name for the bot, e.g. `My Avalanche TWA`
    </Step>
    <Step>
    Choose a username for the bot, e.g. `my_avalanche_twa_482765_bot`
    </Step>
    <Step>
    Take note of the access token, e.g. `5712441624:AAHmiHvwrrju1F3h29rlVOZLRLnv-B8ZZZ`
    </Step>
    </Steps>
</Step>
 <Step>
    Run `yarn configbot` then follow the dialogue to link the Telegram bot with the webapp
    </Step>
</Steps>


## Points of Interest


<Accordions>
<Accordion title="src/main.tsx">
This is where the app is wrapped with the ThirdWeb provider
```tsx
ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render(
  <ThirdwebProvider>
    <QueryClientProvider client={queryClient}>
      <App />
    </QueryClientProvider>
  </ThirdwebProvider>
);
```
</Accordion>
<Accordion title="src/App.tsx">
This is where the ThirdWeb SDK gets initialized with the `clientID` from the `.env` file and also defines the list of acceptable wallets / authorizations.
```tsx
export const client = createThirdwebClient({ clientId: import.meta.env.VITE_THIRDWEB_CLIENT_ID });

const wallets = [
  inAppWallet({
    auth: {
      options: [
        "email",
        "phone",
      ],
    },
  }),
  createWallet("app.core"),
  createWallet("walletConnect")
];
```

```tsx
function App() {

  return (
    <StyledApp>
      <AppContainer>
        <FlexBoxCol>
          <FlexBoxRow>
            <ConnectButton client={client} wallets={wallets} chain={avalancheFuji} showAllWallets={false} />
          </FlexBoxRow>
          <TransferAvax />
          <Counter />
        </FlexBoxCol>
      </AppContainer>
    </StyledApp>
  );
}
```

</Accordion>
<Accordion title="src/components/TransferAvax.tsx">
The Thirdweb `TransferButton` component is used here to compose a new transfer of native tokens.
```tsx
 <TransactionButton
    transaction={() => {
        const transaction = prepareTransaction({
        to: avaxRecipient,
        chain: avalancheFuji,
        client: client,
        value: toWei(avaxAmount),
    });
    return transaction;
    }}
    onTransactionConfirmed={() => { console.log("Transaction confirmed") }}
    onError={() => { console.log("Transaction error") }}
    >
    Confirm Transaction
</TransactionButton>

```
</Accordion>
<Accordion title="src/components/Counter.tsx">
The `TransferButton` component is used again here to facilitate contract interaction.
```tsx
 <TransactionButton
    transaction={() => {
        const transaction = prepareContractCall({
        contract,
        method: "function increase()",
        params: [],
        });
    return transaction;
    }}
    onTransactionConfirmed={() => { console.log("Transaction confirmed") }}
    onError={() => { console.log("Transaction error") }}
    >
    Increase Count
</TransactionButton>

<TransactionButton
    transaction={() => {
        const transaction = prepareContractCall({
        contract,
        method: "function decrease()",
        params: [],
        });
    return transaction;
    }}
    onTransactionConfirmed={() => { console.log("Transaction confirmed") }}
    onError={() => { console.log("Transaction error") }}
    >
    Decrease Count
</TransactionButton>
```
The hardcoded contract address is `0x7Ff5ca07a5FC4AA062c29E6E32d2691B48598577` which is a [simple counter contract deployed on Fuji.](https://testnet.snowtrace.io/address/0x7Ff5ca07a5FC4AA062c29E6E32d2691B48598577/contract/43113/code)
</Accordion>
</Accordions>


# Use Privy on Avalanche L1 (/blog/use-privy-on-l1)

---
title: Use Privy on Avalanche L1
description: This guide shows how to use Social Login and Embedded Wallets with Privy on Avalanche L1.
date: 2024-08-23
authors: [satatocom]
topics: [Avalanche L1, Avalanche Starter Kit, Magic Link, Social Login, Embedded Wallets]
---

In this guide, you will learn how to use Privy to easily onboard your users and create transactions without the need for any Web3 wallet.

## What is Privy?

Privy is a simple tool to easily onboard all your users to web3, regardless of whether they already have a wallet, across mobile and desktop.

## Terminology

Before we dive into the guide, let's first understand the terminology.

| Term | Meaning |
| -------- | ------- |
| Social Login | Social Login is a form of single sign-on (SSO) that allows users to log into a third-party website or app using their existing credentials from a social media platform, such as Google, X (formerly Twitter), or Apple. Instead of creating a new username and password, users can authenticate themselves through their social media accounts, streamlining the login process. |
| Magic Link | A Magic Link is a form of passwordless authentication where users can log into an application or website by clicking a unique, time-sensitive link sent to their email address. This method eliminates the need for a traditional username and password combination, making the login process simpler and more user-friendly. |
| Next.js  | Next.js’ Pages Router is a full-stack React framework. It’s versatile and lets you create React apps of any size—from a mostly static blog to a complex dynamic application. |

## Prerequisites and Recommended Knowledge

- Privy account
- Basic understanding of EVM, and transaction data
- Basic understanding of frontend development

## Preparation

### Create Application and Retrieve API Keys

- Log in to [Privy Dashboard](https://dashboard.privy.io/)
- Click on `New App` on the Applications page.
- Click on the Settings button on the left pane. Under the Basic tab, you'll find the API keys.

### Start a New React Project with Next.js

To create a new Next.js project, run in your terminal:

```bash
npx create-next-app@latest
```

### Install Dependencies

After the React project is created, we need to install some dependencies: to use Privy (its own package), to add a custom chain, to create and use an HTTP client (viem), and to include utilities (ethers).

```bash
npm install @privy-io/react-auth@latest
npm i viem@latest
npm i ethers@latest
```

### Define Your Avalanche L1

In this guide, we are using the `Echo L1` as an example Avalanche L1. However, you can use any Avalanche L1 that has a public RPC URL. If the L1 has an explorer page, you can see better what is happening, but it is not required.

```typescript
export const echo = defineChain({
  id: 173750,
  name: 'Echo L1',
  network: 'echo',
  nativeCurrency: {
    decimals: 18,
    name: 'Ech',
    symbol: 'ECH',
  },
  rpcUrls: {
    default: {
      http: ['https://subnets.avax.network/echo/testnet/rpc']
    },
  },
  blockExplorers: {
    default: {name: 'Explorer', url: 'https://subnets-test.avax.network/echo'},
  },
});
```

### Import Privy into Your App 

After the React project is created, navigate to `page.tsx`. Inside the `Home` function, wrap your content with `PrivyProvider`.

```typescript title="page.tsx"
export default function Home() {

  return (
    <PrivyProvider
      appId="your-privy-app-id"
      config={{
        appearance: {
          theme: 'dark',
          accentColor: '#e84242',
          logo: 'https://your-logo-url',
        },
        embeddedWallets: {
          createOnLogin: 'users-without-wallets',
        },
        defaultChain: echo,
        supportedChains: [echo],
        loginMethods: ['email', 'wallet', 'google', 'apple']
      }}
    >
      { content }
    </PrivyProvider>
  );

}
```

## Walkthrough

So far in the guide, we have installed the necessary dependencies, created our Privy application, and obtained our API key. Now, we are ready to use Privy.

Here is our walkthrough:

- We will create a simple login flow.
- We will create a welcome page for users who have logged in, showing their embedded wallet address and balance.
- We will trigger a test transfer of the `ECH` token via Privy.

### Login Flow

To onboard your users into your application, you just need to know the following hooks:

```typescript
const { ready, authenticated } = usePrivy();
const { login } = useLogin();
```

It's really that simple!

- `ready`: Checks whether the `PrivyProvider` is `ready` to be used.
- `authenticated`: Returns `true` if the user is `authenticated`, `false` otherwise.
- `login`: Opens the Privy login modal and prompts the user to log in.

```typescript
<button onClick={login}>Login via Privy</button>
```

We've only added a button to trigger `login` function, and Privy handles the rest.

![](/guide-images/use-privy-on-l1/1.png)

When we click on the `Login via Privy` button, this modal appears.

![](/guide-images/use-privy-on-l1/2.png)

You can choose any login method to log in. We’ve already defined these options in the `PrivyProvider` when we wrapped our content.

### Welcome Page

After checking whether the user is authenticated or not, we display the following information to the user who has logged in.

![](/guide-images/use-privy-on-l1/3.png)

As you can see, Privy has generated an embedded wallet for our user. We’ve displayed the following properties on the screen: Privy ID, embedded wallet address, and embedded wallet balance.

```typescript
<span>{user.id}</span>
<span>{user.wallet.address}</span>
<span>{balance} ECH</span>
```

We’ve used the user object of Privy to retrieve the user ID and wallet address. To fetch the user’s balance, we need to create an HTTP client for our Avalanche L1, which we’ve already defined earlier.

```typescript
const client = createPublicClient({
    chain: echo,
    transport: http(),
});
// get native asset balance
client.getBalance({
    address: address,
}).then(balance => {
    setBalance(ethers.formatEther(balance));
});
```

We can allow users to log out using the following hook:

```typescript
const { logout } = useLogout();
```

### Fund the New Wallet Using the Faucet

We’ve funded the new wallet that was generated for our user with some ECH tokens from the [Echo AWM Testnet Faucet](https://test.core.app/tools/testnet-faucet/?subnet=echo&token=echo).

![](/guide-images/use-privy-on-l1/4.png)

After the ECH tokens were sent, our balance updated accordingly.

![](/guide-images/use-privy-on-l1/5.png)

### Send Test Transfer via Privy

Now that we have a balance, we can send some ECH tokens to another recipient via Privy to test Privy's `sendTransaction` flow. Privy provides the following hook for this:

```typescript
const { sendTransaction } = useSendTransaction();
```

We’ve already added the following button to trigger the `transfer` function, which will, in turn, trigger the `sendTransaction` function provided by Privy.

```typescript
<button onClick={transfer}>Send Test Transfer via Privy</button>
```

We have built a simple transaction that sends some ECH tokens to another recipient.


```typescript
const transfer = () => {
    if (authenticated === false || address === undefined) {
        return;
    }
    let receiver = "0x..."; // receiver address
    sendTransaction({
        "value": ethers.parseUnits("0.01", "ether"),
        "to": receiver, // destination address
        "from": address, // logged in user's embedded wallet address
    }).catch(() => {
        // handle err 
    });
}
```

When we click on the `Send Test Transfer via Privy` button, this modal appears. Users can see the following details related to the transaction.

![](/guide-images/use-privy-on-l1/6.png)
![](/guide-images/use-privy-on-l1/7.png)

## Conclusion

What we achieved is the creation of a simple React project that integrates Privy. Our application can now easily onboard new users to our Web3 application without needing them to install a Web3 wallet extension, regardless of which chain they are on.

# What is a blockchain? (/blog/what-is-a-blockchain)

---
title: What is a blockchain?
description: Learn how blockchains differ from centralized systems, their trade-offs, and the best use cases for their secure, transparent architecture.
date: 2024-07-24
authors: [martin_eckardt]
topics: [Blockchain Basics]
---

## Introduction to Different Types of Computers
Computers are integral to our daily lives, and they come in various forms, each designed to serve specific purposes. Here's a quick overview:

1. **Personal Computers (PCs)**: These are the desktops and laptops we use at home or work. They are versatile, powerful, and designed for individual use.
2. **Cloud Computers**: These are powerful servers located in data centers around the world. They provide vast computational resources and storage, accessible via the internet. They are designed for scalability and can handle large-scale applications and data processing.
3. **Mobile Computers**: These include smartphones and tablets. They are portable and offer the convenience of mobility, allowing us to perform computing tasks on the go.

All these computers are *centralized*. This means they are controlled by a single entity or organization. For example, your PC is controlled by you, cloud computers are managed by cloud service providers, and mobile devices are typically controlled by their manufacturers and network providers. Centralization implies that these entities have the power to manage, restrict access to, or shut down these computers if needed.

## Introducing the Blockchain Computer
A **blockchain** is a new kind of computer with a unique and defining property: **decentralization**. Unlike traditional centralized computers controlled by a single entity, a blockchain operates without any central authority. This means no single entity can:

- Turn it off
- Restrict access to it
- Interfere with the execution of the programs running on it

Furthermore, the computation is transparent. Anyone can see the programs running on the blockchain and verify their correctness. This transparency ensures that the blockchain operates fairly and securely.

## How Decentralization Works
Decentralization in blockchain is achieved through a network of **validators**. These are independent entities that run the blockchain software, perform computations, and ensure the integrity of the blockchain. Here’s how it works:

1. **Computation Execution**: Each validator independently performs the same computation. For example, let's consider a simple computation: `5 + 3`.
2. **Consensus Process**: After performing the computation, validators share their results with each other. They then use a process called **consensus** to agree on the correct result. You can think of it as a election, where all validators vote on the correct answer.

The consensus process ensures that all validators reach an agreement on the correct result, given that the majority is honest. This agreement is crucial for maintaining the integrity and security of the blockchain. If a validator tries to cheat or provide an incorrect result, the other validators will detect the discrepancy, and the cheating validator will be penalized.

## Efficiency of Blockchain Computation
While the decentralized nature of blockchain ensures security and integrity, it also makes it **inefficient** compared to traditional computers. Here’s why:

- **Redundant Computation**: Every validator must perform the same computation independently.
- **Consensus Overhead**: Validators need to communicate and agree on the results, which adds extra steps and time.

Due to the redundancy and additional processes, performing computations on a blockchain is much more expensive than on a PC or cloud computer. For instance, while a PC can perform a simple addition in a fraction of a second with minimal cost, a blockchain requires multiple validators to do the same computation and agree on the result, leading to higher computational costs and time.

So, while it's decentralized nature offers significant advantages in terms of security and resistance to control, it also comes at the cost of efficiency and higher computation expenses. As we continue to develop and optimize blockchain technology, we aim to balance these trade-offs and explore its vast potential in various applications.

## Use Cases for Blockchain

Blockchain technology excels in use cases where decentralization, security, and transparency are paramount, making the trade-off for reduced efficiency worthwhile. 

-  In *financial services*, blockchain enables secure, transparent, and tamper-proof transactions without the need for intermediaries like banks. 
- *Supply chain management* benefits from blockchain by providing an immutable ledger that tracks the provenance and movement of goods, enhancing traceability and reducing fraud. 
- *Voting systems* can leverage blockchain to ensure the integrity and transparency of the electoral process, making it resistant to tampering and fraud. 

However, for tasks that prioritize high efficiency and speed over decentralization, such as real-time data processing or complex computational tasks, traditional centralized systems are more suitable. In these cases, the overhead of consensus mechanisms and redundant computations in blockchain would introduce unnecessary latency and cost. Thus, the decision to use blockchain should be guided by the specific needs for security, transparency, and decentralization versus the demand for efficiency and speed.